> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fased.ai/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 Fased you can authenticate with **Sign in (Claude Code OAuth)**, an
**Anthropic token (setup-token)**, or an **Anthropic API key**.

Anthropic is a current Fased model provider. The code route is `anthropic`; if
it does not appear in **Agent > Models**, add Anthropic auth first or check
provider health from the Models page.

## Where to set it up

Use the same Anthropic methods in every setup surface:

* **Control UI:** Open **Agents**, select an Agent, then use **Agent > Models**.
  Choose **Anthropic**, then **Sign in**, **Token**, or **API key**, and assign
  the Agent's model roles there. Chat can override the model for the current
  session.
* **Onboarding:** Choose **Set up model providers** only if you want provider
  setup during onboarding. Choose **Anthropic**, then pick **Anthropic OAuth
  (Claude Code)**, **Anthropic token (paste setup-token)**, or **Anthropic API
  key**.
* **CLI:** Use `fased models auth login --provider anthropic --method anthropic-oauth`,
  `fased models auth setup-token --provider anthropic`,
  `fased models auth paste-token --provider anthropic`, or
  `fased onboard --anthropic-api-key "$ANTHROPIC_API_KEY"`.

## Option A: Sign in (Claude Code OAuth)

**Best for:** using Claude sign-in from the Claude Code auth flow.

### OAuth control UI setup

1. Open **Agents** and select the Agent.
2. Open **Agent > Models**.
3. Open **Anthropic**.
4. Choose **Sign in**.
5. Open or copy the sign-in URL shown in the modal.
6. Finish Anthropic login in the browser.
7. Paste the Anthropic authorization code if the modal asks for it.
8. Return to **Agent > Models** after the modal reports success, then choose a
   model role for the Agent or use Chat to override a single session.

### OAuth onboarding setup

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
fased onboard
# choose: Set up model providers -> Anthropic -> Anthropic OAuth (Claude Code)

# or start that auth choice directly
fased onboard --auth-choice anthropic-oauth
```

### OAuth CLI setup

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
fased models auth login --provider anthropic --method anthropic-oauth
```

## Option B: Anthropic token (setup-token)

**Best for:** using a Claude setup-token generated by the Claude Code CLI.

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
claude setup-token
```

### Token control UI setup

1. Open **Agents** and select the Agent.
2. Open **Agent > Models**.
3. Open **Anthropic**.
4. Choose **Token**.
5. Paste the setup-token generated by `claude setup-token`.
6. Return to **Agent > Models** after the modal reports success, then choose a
   model role for the Agent or use Chat to override a single session.

### Token onboarding setup

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
fased onboard
# choose: Set up model providers -> Anthropic -> Anthropic token (paste setup-token)

# or paste a token non-interactively
fased onboard --auth-choice token --token-provider anthropic --token "$CLAUDE_SETUP_TOKEN"
```

### Token CLI setup

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Generate or paste a setup-token on the gateway host
fased models auth setup-token --provider anthropic
fased models auth paste-token --provider anthropic

# Or use the provider login command
fased models auth login --provider anthropic --method token
```

## Option C: Anthropic API key

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

### API key control UI setup

1. Open **Agents** and select the Agent.
2. Open **Agent > Models**.
3. Open **Anthropic**.
4. Use **API key** and paste an Anthropic Console API key.
5. Choose the Agent's Anthropic model roles.

### API key onboarding setup

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
fased onboard
# choose: Set up model providers -> Anthropic -> Anthropic API key
```

### API key CLI setup

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
fased onboard
# choose: Anthropic API key

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

### Config snippet

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  env: { ANTHROPIC_API_KEY: "sk-ant-..." },
  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-7" } } },
}
```

## Prompt caching (Anthropic API)

Fased 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) |

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-7": {
          params: { cacheRetention: "long" },
        },
      },
    },
  },
}
```

### Defaults

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

### Per-agent cacheRetention overrides

Use model-level params as your baseline, then override specific agents via `agents.list[].params`.

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-opus-4-7" },
      models: {
        "anthropic/claude-opus-4-7": {
          params: { cacheRetention: "long" }, // baseline for most agents
        },
      },
    },
    list: [
      { id: "research", default: true },
      { id: "alerts", params: { cacheRetention: "none" } }, // override for this agent only
    ],
  },
}
```

Config merge order for cache-related params:

1. `agents.defaults.models["provider/model"].params`
2. `agents.list[].params` (matching `id`, overrides by key)

This lets one agent keep a long-lived cache while another agent on the same
model disables caching to avoid write costs on bursty or low-reuse traffic.

### 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.

Fased 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)).

## 1M context window (Anthropic beta)

Anthropic's 1M context window is beta-gated. In Fased, enable it per model
with `params.context1m: true` for supported Opus/Sonnet models.

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-7": {
          params: { context1m: true },
        },
      },
    },
  },
}
```

Fased maps this to `anthropic-beta: context-1m-2025-08-07` on Anthropic
requests.

Note: Anthropic currently rejects `context-1m-*` beta requests when using
OAuth/subscription tokens (`sk-ant-oat-*`). Fased automatically skips the
context1m beta header for OAuth auth and keeps the required OAuth betas.

## Notes

* Generate setup-tokens with `claude setup-token` and paste them in
  **Agent > Models**, onboarding, or
  `fased models auth paste-token --provider anthropic`.
* If you see “OAuth token refresh failed …” on a Claude subscription, re-auth
  with a setup-token. See [Gateway troubleshooting](/gateway/troubleshooting).
* Auth details + reuse rules are in [/concepts/oauth](/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
  `fased 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 `fased models status`.

**No credentials found for profile `anthropic:default`**

* Run `fased 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 `fased models status --json` for `auth.unusableProfiles`.
* Add another Anthropic profile or wait for cooldown.

More: [/gateway/troubleshooting](/gateway/troubleshooting) and [/help/faq](/help/faq).