Claude Code CLI

Claude Code uses the Anthropic Messages API shape. For router traffic, use the router Anthropic-compatible base URL and a router-issued bearer token.

Replace https://<router-host> with your deployment URL. When these docs are served from a live router under /docs/, examples automatically use that router origin.

Required Environment

Use ANTHROPIC_BASE_URL=https://<router-host>/anthropic and ANTHROPIC_AUTH_TOKEN for router traffic. Keep ANTHROPIC_API_KEY reserved for direct Anthropic traffic; setting both for the router path can cause client warnings or incorrect authentication behavior.

Router tokens can only request model groups returned by /v1/models for that same token. Set the main Claude Code model and the default subagent model to allowed router model groups; otherwise Claude Code may send some Anthropic Messages requests with a model value the router key cannot use.

Record the Claude Code version used for deployment validation with claude --version; CLI flags can change over time.

Validated translated client tools (after v4.1.0)

Metrum AI Router can translate Messages client tools and their continuation history to OpenAI Chat or Responses. This is opt-in per target, not implied by the upstream model's function-tool support. Require all of:

request_shape_support.supported_inbound_dialects includes anthropic and validation_status: passed;
tool_support.anthropic_messages: [client_tools] records validation of this exact target's Messages tool bridge;
the active upstream skin also declares openai_chat: [tools] or openai_responses: [function] in tool_support.

Explicit tool_choice additionally requires tool_choice in both the Anthropic and active upstream tool capability lists. Omitted choice is independent. Do not copy these declarations from a Chat-only smoke: first run Claude Code's streaming write/read continuation against each isolated target. The bridge preserves multiple calls, tool IDs, arguments, results, usage and tool stop reasons. Provider-private thinking is not portable; reasoning requests remain rejected by the existing bridge gate. Native Anthropic passthrough is unchanged. Targets without the distinct Messages tool evidence still return 502 no-eligible-target without an upstream attempt.

In v4.1.0 these translated tool routes remain unavailable; use a validated native Anthropic Messages tool target on that release.

unset ANTHROPIC_API_KEY
export ANTHROPIC_BASE_URL="https://<router-host>/anthropic"
export ANTHROPIC_AUTH_TOKEN="rtr_metrum_<user>_<project>_<env>_<key>_<secret>"
export ANTHROPIC_MODEL="<allowed-model-group>"
export CLAUDE_CODE_SUBAGENT_MODEL="<allowed-model-group>"

Check the allowed groups with the same router token before choosing values:

curl "https://<router-host>/v1/models" -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"

One-Shot Check

Use one of the model group IDs returned by /v1/models for --model or ANTHROPIC_MODEL. See Available Models And Access if you need to check which groups your token can request.

The text check below proves only Anthropic Messages text routing. On v4.1.0, Claude Code tool requests cannot use a group whose only eligible targets are Anthropic-to-OpenAI Chat or Responses text translations. In that setup, the tool request returns 502 no-eligible-target before an upstream call. Use a separately validated Anthropic Messages tool-capable route for Claude Code file and shell tasks. OpenAI Chat or Codex Responses tool success does not validate the Claude Code tool path. See the v4.1.0 known limitation and tracking issue #295.

claude --bare --print --model "<allowed-model-group>" \
  "Reply with exactly: router claude ok"

Interactive Usage

claude --model "<allowed-model-group>"

Use the same deployment-defined coding group for mixed coding and image tasks only after the deployment has validated an image-capable Anthropic Messages target in that group. Some hosted examples use big-coder as a coding-oriented group name; your deployment may use a different group name. A group's aggregate image modality can come from an OpenAI Chat or Responses target and does not prove that Claude Code image traffic is eligible. When a Messages image target exists, the router filters image-bearing requests to that pool while text-only and ordinary tool requests continue to use the normal coding targets.

Subagent Model Routing

Claude Code can resolve subagent models separately from the main session. For router keys that are limited to one or more model groups, pin both the main session and subagents to groups returned by /v1/models.

For local project settings, use placeholders in shared examples and keep real router tokens out of version control:

.claude/settings.local.json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://<router-host>/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "rtr_metrum_<user>_<project>_<env>_<key>_<secret>",
    "ANTHROPIC_MODEL": "<allowed-model-group>",
    "CLAUDE_CODE_SUBAGENT_MODEL": "<allowed-model-group>"
  }
}

If an individual subagent should use a different router group, first leave CLAUDE_CODE_SUBAGENT_MODEL unset or set it to inherit behavior for that run. Then set the different group in the subagent frontmatter and make sure the same router token can see it in /v1/models:

.claude/agents/router-subagent.md
---
name: router-subagent
description: Work on the assigned task using the selected router model group.
model: <allowed-model-group>
---

Complete the assigned task and report the result.

If Claude Code still sends 403 model-not-allowed, check the main model, CLAUDE_CODE_SUBAGENT_MODEL, and any subagent frontmatter model values against /v1/models using the same ANTHROPIC_AUTH_TOKEN. A pinned CLAUDE_CODE_SUBAGENT_MODEL takes precedence over per-subagent frontmatter, so unset or inherit it before testing a different frontmatter model group.

Tool Smoke

Run tool smokes inside a disposable container or equivalent isolated workspace because the command intentionally grants file and shell tools. Pass only the router base URL and a scoped router token into the sandbox, and mount only the scratch directory where the smoke file should be written.

mkdir -p "$PWD/claude-tool-smoke"
docker run --rm --network host --cap-drop ALL --security-opt no-new-privileges \
  --cpus 1 --memory 1g --pids-limit 256 --read-only \
  --tmpfs /tmp:rw,nosuid,nodev,size=256m \
  --mount type=bind,source="$PWD/claude-tool-smoke",target=/workspace \
  -e "ANTHROPIC_BASE_URL={{origin}}/anthropic" \
  -e "ANTHROPIC_AUTH_TOKEN=$ANTHROPIC_AUTH_TOKEN" \
  -w /workspace "$TOOL_SMOKE_IMAGE" \
  claude --bare --print --model "<allowed-model-group>" \
    --permission-mode bypassPermissions \
    --allowedTools "Write,Bash" \
    "Create claude_tool_smoke.txt containing exactly claude-tool-ok, run cat claude_tool_smoke.txt, then finish with claude-tool-ok."

The requested model must be allowed by the caller token. Deployment admins decide which model groups each key may use. For v4.1.0, the group must also contain a separately validated Anthropic Messages tool target; Anthropic text translation alone will not run this smoke.

Image Input

Claude Code sends image work through the Anthropic Messages API shape when an image is attached in the conversation. Use a deployment-defined router model group that is allowed for the caller token and has validation evidence for image input on the Anthropic Messages surface. The router filters image-bearing Messages requests to targets that advertise image in input_modalities and are eligible for the inbound anthropic dialect and caller output cap.

/v1/models confirms that the token may request the group, but group-level image metadata can be backed by a different API skin. Before rollout, run the Messages image smoke below. A 502 no-eligible-target response means the group is authorized but has no target validated for that exact Messages image shape; ask the deployment administrator to add or enable a validated Anthropic Messages image target rather than retrying the same request.

For non-interactive validation, use the same Anthropic-compatible payload shape Claude Code sends:

curl "https://<router-host>/anthropic/v1/messages" -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" -H "Content-Type: application/json" -d '{
  "model": "<allowed-model-group>",
  "max_tokens": 64,
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "Read the receipt. Reply with only the merchant name."},
      {"type": "image", "source": {"type": "url", "url": "https://cdn.learnopencv.com/wp-content/uploads/2018/06/04100007/receipt.png"}}
    ]
  }]
}'

The legacy /v1/messages and /v1/messages/count_tokens paths remain compatible for existing clients. New Claude Code and Anthropic-compatible client setup should use /anthropic as the base URL, which sends requests to /anthropic/v1/messages and keeps Anthropic-compatible traffic visually separate from OpenAI-compatible /v1 traffic.

Image-bearing Claude Code requests bypass router response caching. Usage records include image count and upstream cost fields when the upstream reports them.

For the full VLM routing configuration and equivalent OpenAI API examples, see Image Analysis And VLM Routing.

For the broader coding-agent validation matrix, including opencode, aider, and IDE/agent clients, see Coding-Agent Client Matrix.

Required Environment​

Validated translated client tools (after v4.1.0)​

One-Shot Check​

Interactive Usage​

Subagent Model Routing​

Tool Smoke​

Image Input​