bot/docs/providers/anthropic.md

summary, read_when, title

summary	read_when	title
Use Anthropic Claude via API keys or setup-token in Hanzo Bot	You want to use Anthropic models in Hanzo Bot You want setup-token instead of API keys	Anthropic

Anthropic (Claude)

Anthropic builds the Claude model family and provides access via an API. In Hanzo Bot you can authenticate with an API key or a setup-token.

Option A: Anthropic API key

Best for: standard API access and usage-based billing. Create your API key in the Anthropic Console.

CLI setup

hanzo-bot onboard
# choose: Anthropic API key

# or non-interactive
hanzo-bot onboard --anthropic-api-key "$ANTHROPIC_API_KEY"

Config snippet

{
  env: { ANTHROPIC_API_KEY: "sk-ant-..." },
  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
}

Prompt caching (Anthropic API)

Hanzo Bot supports Anthropic's prompt caching feature. This is API-only; subscription auth does not honor cache settings.

Configuration

Use the cacheRetention parameter in your model config:

Value	Cache Duration	Description
none	No caching	Disable prompt caching
short	5 minutes	Default for API Key auth
long	1 hour	Extended cache (requires beta flag)

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": {
          params: { cacheRetention: "long" },
        },
      },
    },
  },
}

Defaults

When using Anthropic API Key authentication, Hanzo Bot automatically applies cacheRetention: "short" (5-minute cache) for all Anthropic models. You can override this by explicitly setting cacheRetention in your config.

Legacy parameter

The older cacheControlTtl parameter is still supported for backwards compatibility:

• "5m" maps to short
• "1h" maps to long

We recommend migrating to the new cacheRetention parameter.

Hanzo Bot includes the extended-cache-ttl-2025-04-11 beta flag for Anthropic API requests; keep it if you override provider headers (see /gateway/configuration).

Option B: Claude setup-token

Best for: using your Claude subscription.

Where to get a setup-token

Setup-tokens are created by the Claude Code CLI, not the Anthropic Console. You can run this on any machine:

claude setup-token

Paste the token into Hanzo Bot (wizard: Anthropic token (paste setup-token)), or run it on the gateway host:

hanzo-bot models auth setup-token --provider anthropic

If you generated the token on a different machine, paste it:

hanzo-bot models auth paste-token --provider anthropic

CLI setup (setup-token)

# Paste a setup-token during onboarding
hanzo-bot onboard --auth-choice setup-token

Config snippet (setup-token)

{
  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
}

Notes

• Generate the setup-token with claude setup-token and paste it, or run hanzo-bot models auth setup-token on the gateway host.
• If you see “OAuth token refresh failed …” on a Claude subscription, re-auth with a setup-token. See /gateway/troubleshooting#oauth-token-refresh-failed-anthropic-claude-subscription.
• Auth details + reuse rules are in /concepts/oauth.

Troubleshooting

401 errors / token suddenly invalid

• Claude subscription auth can expire or be revoked. Re-run claude setup-token and paste it into the gateway host.
• If the Claude CLI login lives on a different machine, use hanzo-bot models auth paste-token --provider anthropic on the gateway host.

No API key found for provider "anthropic"

• Auth is per agent. New agents don’t inherit the main agent’s keys.
• Re-run onboarding for that agent, or paste a setup-token / API key on the gateway host, then verify with hanzo-bot models status.

No credentials found for profile anthropic:default

• Run hanzo-bot models status to see which auth profile is active.
• Re-run onboarding, or paste a setup-token / API key for that profile.

No available auth profile (all in cooldown/unavailable)

• Check hanzo-bot models status --json for auth.unusableProfiles.
• Add another Anthropic profile or wait for cooldown.

More: /gateway/troubleshooting and /help/faq.