> ## Documentation Index
> Fetch the complete documentation index at: https://docs.equa.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Anthropic

# 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

```bash theme={null}
equabot onboard
# choose: Anthropic API key

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

### Config snippet

```json5 theme={null}
{
  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`:

```json5 theme={null}
{
  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](/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**:

```bash theme={null}
claude setup-token
```

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

```bash theme={null}
equabot models auth setup-token --provider anthropic
```

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

```bash theme={null}
equabot models auth paste-token --provider anthropic
```

### CLI setup

```bash theme={null}
# Reuse Claude Code CLI OAuth credentials if already logged in
equabot onboard --auth-choice claude-cli
```

### Config snippet

```json5 theme={null}
{
  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](/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](/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.

| Input             | Resolves to                |
| ----------------- | -------------------------- |
| `opus-4.5`        | `claude-opus-4-5`          |
| `sonnet-4.5`      | `claude-sonnet-4-5`        |
| `claude-sonnet-4` | `claude-sonnet-4-20250514` |
| `claude-opus-4`   | `claude-opus-4-20250514`   |
| `sonnet-4`        | `claude-sonnet-4-20250514` |
| `opus-4`          | `claude-opus-4-20250514`   |

This normalization is separate from the `/model` command aliases (`sonnet`,
`opus`) documented in [Gateway configuration](/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](/gateway/troubleshooting#agent-failed-before-reply-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](/gateway/troubleshooting) and [/help/faq](/help/faq).