jerry/claude-agent-acp
1
0
Fork 0
mirror of https://github.com/agentclientprotocol/claude-agent-acp.git synced 2026-10-27 04:30:59 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
v0.74.0
claude-agent-acp/docs/model-configuration.md
Anna Zhdan 1e15f3d8b0 feat: allow configuring models through env vars (#586) 
Allow providing Claude model settings via env var on startup. Providing
model settings is required when using Claude with alternative llm
provider, e.g. Bedrock as models have different IDs there
2026-04-24 15:50:28 +02:00

2.7 KiB
Raw Permalink Blame History

Model Configuration

When using claude-agent-acp with alternative providers (e.g. AWS Bedrock), model IDs differ from the direct Anthropic API. The CLAUDE_MODEL_CONFIG environment variable lets you configure model overrides and availability at the deployment level.

CLAUDE_MODEL_CONFIG

A JSON string with two optional fields:

Field Type Description
modelOverrides Record<string, string> Maps Anthropic model IDs to provider-specific model IDs (e.g. Bedrock model IDs or ARNs)
availableModels string[] Restricts which models are offered to users. Accepts aliases ("opus"), prefixes ("opus-4-5"), or full IDs

Examples

Bedrock model overrides:

CLAUDE_MODEL_CONFIG='{"modelOverrides":{"claude-opus-4-6":"us.anthropic.claude-opus-4-6-v1","claude-sonnet-4-5":"us.anthropic.claude-sonnet-4-5-v1"}}'

Restrict available models:

CLAUDE_MODEL_CONFIG='{"availableModels":["opus","sonnet"]}'

Both together:

CLAUDE_MODEL_CONFIG='{"modelOverrides":{"claude-opus-4-6":"us.anthropic.claude-opus-4-6-v1","claude-sonnet-4-5":"us.anthropic.claude-sonnet-4-5-v1"},"availableModels":["opus","sonnet"]}'

Full Bedrock example:

CLAUDE_CODE_USE_BEDROCK=1 \
AWS_REGION=us-west-2 \
CLAUDE_MODEL_CONFIG='{"modelOverrides":{"claude-opus-4-6":"us.anthropic.claude-opus-4-6-v1"}}' \
node dist/index.js

Precedence

When an ACP caller provides settings via _meta.claudeCode.options.settings in the sessions/create request, CLAUDE_MODEL_CONFIG is ignored entirely. The env var is a deployment-level fallback for cases where the caller does not configure model settings itself.

Source Priority
_meta.claudeCode.options.settings (caller) Highest — used if present
CLAUDE_MODEL_CONFIG (env var) Fallback — used only when caller provides no settings

Format details

  • The value must be valid JSON. Invalid JSON will cause session creation to fail with a parse error.
  • Only modelOverrides and availableModels keys are read; other keys in the JSON are ignored.
  • Both fields map directly to the Claude Agent SDK's Settings type.