Skip to main content

​
Anthropic (Claude)

Anthropic builds the Claude model family and provides access via an API. In Equabot you can authenticate with an API key or reuse Claude Code CLI credentials (setup-token or OAuth).

​
Option A: Anthropic API key

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

​
CLI setup

equabot onboard
# choose: Anthropic API key

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

​
Config snippet

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

​
Prompt caching (Anthropic API)

Equabot does not override Anthropic’s default cache TTL unless you set it. This is API-only; Claude Code CLI OAuth ignores TTL settings. To set the TTL per model, use cacheControlTtl in the model params: 
{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-5": {
          params: { cacheControlTtl: "5m" } // or "1h"
        }
      }
    }
  }
}
Equabot 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 Code CLI (setup-token or OAuth)

Best for: using your Claude subscription or existing Claude Code CLI login.

​
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 Equabot (wizard: Anthropic token (paste setup-token)), or run it on the gateway host: 
equabot models auth setup-token --provider anthropic
If you generated the token on a different machine, paste it: 
equabot models auth paste-token --provider anthropic

​
CLI setup

# Reuse Claude Code CLI OAuth credentials if already logged in
equabot onboard --auth-choice claude-cli

​
Config snippet

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

​
Notes

  • Generate the setup-token with claude setup-token and paste it, or run equabot 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 or resync Claude Code CLI OAuth on the gateway host. See /gateway/troubleshooting#oauth-token-refresh-failed-anthropic-claude-subscription.
  • Equabot writes auth.profiles["anthropic:claude-cli"].mode as "oauth" so the profile accepts both OAuth and setup-token credentials. Older configs using "token" are auto-migrated on load.
  • Auth details + reuse rules are in /concepts/oauth.

​
Model ID normalization

Equabot normalizes common Anthropic model shorthands before looking up the model catalog. If you use one of these names in config, a session override, or a /model command, Equabot resolves it to the canonical catalog ID automatically.
InputResolves to
opus-4.5claude-opus-4-5
sonnet-4.5claude-sonnet-4-5
claude-sonnet-4claude-sonnet-4-20250514
claude-opus-4claude-opus-4-20250514
sonnet-4claude-sonnet-4-20250514
opus-4claude-opus-4-20250514
This normalization is separate from the /model command aliases (sonnet, opus) documented in Gateway configuration. It applies to any model reference — config values, session overrides, and API calls. If a model ID is not in this table and not in the pi-ai catalog, the gateway returns an “Unknown model” error. See Troubleshooting — Unknown model.

​
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 equabot 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 equabot models status.
No credentials found for profile anthropic:default or anthropic:claude-cli
  • Run equabot 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 equabot models status --json for auth.unusableProfiles.
  • Add another Anthropic profile or wait for cooldown.
More: /gateway/troubleshooting and /help/faq.