Skip to main content

How to govern CoPaw with Talon

This guide shows how to route CoPaw's LLM traffic through Talon so every request is audited and policy-enforced. CoPaw is an open-source personal AI assistant (AgentScope/Alibaba DAMO) with multi-channel support (DingTalk, Feishu, Discord, etc.). Allow about 15 minutes.

For a Docker-based setup, see the CoPaw + Talon primer.

Prerequisites​

  • Talon installed (go install github.com/dativo-io/talon/cmd/talon@latest or curl -sL https://install.gettalon.dev | sh)
  • CoPaw installed (pip install copaw or from source)
  • Your real LLM provider API key (OpenAI, DashScope, or other OpenAI-compatible provider)

Steps​

1. Install Talon and generate CoPaw config​

# Generate a gateway-ready project pre-configured for CoPaw:
mkdir talon-copaw && cd talon-copaw
talon init --pack copaw --name copaw-gateway
# Or run `talon init` and choose CoPaw from the wizard.

This creates agent.talon.yaml — the copaw-gateway agent: CoPaw's Talon traffic identity (agent.key.secret_name: copaw-gateway-talon-key) plus its policy override (cost limits, gateway model allowlist, metadata.tags: [copaw] for the CoPaw dashboard views) — and talon.config.yaml (gateway config with providers and the organization baseline under organization_policy).

2. Set the vault key, store the real provider key, mint the agent key​

export TALON_SECRETS_KEY=$(openssl rand -hex 32)
talon secrets set openai-api-key "sk-your-openai-key"
# Or for DashScope: talon secrets set dashscope-api-key "sk-your-dashscope-key"

# Mint the agent key CoPaw will present (bound via agent.key.secret_name)
COPAW_KEY="$(openssl rand -hex 24)"
talon secrets set copaw-gateway-talon-key "$COPAW_KEY"

talon serve --gateway

Use the same TALON_SECRETS_KEY when running talon secrets set and talon serve. The agent key ($COPAW_KEY) is the token CoPaw sends to Talon; it resolves to the copaw-gateway agent (and its derived tenant) and goes into CoPaw's provider api_key field.

3. Confirm the gateway is running​

curl -s -X POST http://localhost:8080/v1/proxy/openai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $COPAW_KEY" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Say hi"}],"max_tokens":5}'

You should get a JSON completion. If Talon runs on another host, use http://<talon-host>:8080.

4. Point CoPaw at the gateway​

CoPaw stores provider settings in ~/.copaw.secret/providers.json and can be configured via the CoPaw Console (port 8088) or the CoPaw CLI.

Option A — CoPaw Console (Settings → Models):

  1. Open the CoPaw web UI (e.g. http://localhost:8088).
  2. Go to Settings → Models.
  3. Select the provider you use (e.g. OpenAI or a custom one).
  4. Set Base URL to http://localhost:8080/v1/proxy/openai/v1 (or http://<talon-host>:8080/v1/proxy/openai/v1).
  5. Set API Key to the agent key you minted in step 2 ($COPAW_KEY).
  6. Save. CoPaw will use this endpoint for all LLM calls.

Option B — Environment variables (when starting CoPaw):

export OPENAI_BASE_URL=http://localhost:8080/v1/proxy/openai/v1
export OPENAI_API_KEY=$COPAW_KEY
copaw run

Option C — CoPaw CLI / REST API:

Use copaw providers or the REST API to set the provider's base_url and api_key to the Talon gateway URL and the agent key.

Important:

  • The API Key in CoPaw is the Talon agent key ($COPAW_KEY), not your real OpenAI/DashScope key. Talon resolves the copaw-gateway agent by this key and injects the real key when forwarding.
  • Base URL must end with /v1 so that paths like chat/completions become .../v1/chat/completions.
  • Rotation: talon secrets set copaw-gateway-talon-key <new> + restart Talon, then update CoPaw — one active key per agent, never two.

5. Verify​

Send a message through CoPaw (Console or any connected channel), then check the audit trail:

talon audit list
talon audit list --agent copaw-gateway

Evidence rows will show agent_id: copaw-gateway. The Talon dashboard (/dashboard) has a CoPaw Agents tab with stats and alerts (driven by the copaw entry in the agent's metadata.tags).

6. Policy and monitoring​

  • Always enforced: there is no shadow posture (#442) — the action each rule declares is what happens. Check the files before pointing CoPaw at Talon (talon doctor for talon.config.yaml, talon validate for the agent file), start with permissive actions (pii_action: warn), and tighten after reviewing talon audit list --agent copaw-gateway.
  • Cost limits: Adjust policies.cost_limits.daily and .monthly in the agent file — each replaces the organization baseline cap when > 0.
  • PII: Set the floor in gateway.organization_policy.defaults.pii_action; tighten per agent via the policies.data_classification booleans (input_scan + redact_input → redact; block_on_pii → block; input_scan alone scans without changing the action). The merge is monotonic — an agent can only tighten the org floor, never weaken it.

Troubleshooting​

SymptomCauseFix
"Invalid or missing agent key"CoPaw is not sending the agent key, or key mismatchSet CoPaw's API Key to exactly the value minted into copaw-gateway-talon-key.
"Service configuration error"Vault key mismatchUse the same TALON_SECRETS_KEY for talon secrets set and talon serve.
404 on chat/completionsBase URL missing /v1Use http://talon-host:8080/v1/proxy/openai/v1 (trailing /v1).
CoPaw uses DashScopeProvider base URLAdd a dashscope provider in Talon gateway config with base_url: https://dashscope.aliyuncs.com/compatible-mode (no trailing /v1; gateway appends the path) and point CoPaw at http://talon-host:8080/v1/proxy/dashscope/v1.

See also​

You're done​

You now have CoPaw sending all LLM traffic through Talon. Talon is logging every request, scanning for PII, and enforcing per-agent policy and cost limits.

Next steps:

I want to…Doc
Cap cost or restrict models for CoPawHow to cap daily spend per team or application
Run CoPaw + Talon in DockerCoPaw + Talon Docker primer
Export evidence for auditorsHow to export evidence for auditors
Add another app through the gatewayAdd Talon to your existing app