> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/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 WednesdayAI 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

```bash theme={"dark"}
wednesdayai onboard
# choose: Anthropic API key

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

### Config snippet

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

## Thinking defaults (Claude 4.6)

* Anthropic Claude 4.6 models default to `adaptive` thinking in WednesdayAI when no explicit thinking level is set.
* You can override per-message (`/think:<level>`) or in model params:
  `agents.defaults.models["anthropic/<model>"].params.thinking`.
* Related Anthropic docs:
  * [Adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking)
  * [Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)

## Prompt caching (Anthropic API)

WednesdayAI 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={"dark"}
{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": {
          params: { cacheRetention: "long" },
        },
      },
    },
  },
}
```

### Defaults

When using Anthropic API Key authentication, WednesdayAI 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={"dark"}
{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-opus-4-6" },
      models: {
        "anthropic/claude-opus-4-6": {
          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/low-reuse traffic.

### Bedrock Claude notes

* Anthropic Claude models on Bedrock (`amazon-bedrock/*anthropic.claude*`) accept `cacheRetention` pass-through when configured.
* Non-Anthropic Bedrock models are forced to `cacheRetention: "none"` at runtime.
* Anthropic API-key smart defaults also seed `cacheRetention: "short"` for Claude-on-Bedrock model refs when no explicit value is set.

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

WednesdayAI includes the `extended-cache-ttl-2025-04-11` beta flag for Anthropic API
requests; keep it if you override provider headers (see [/gateway/configuration](https://docs.wednesdayai.dev/next/admin/gateway/configuration.md)).

## 1M context window (Anthropic beta)

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

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

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

This only activates when `params.context1m` is explicitly set to `true` for
that model.

Requirement: Anthropic must allow long-context usage on that credential
(typically API key billing, or a subscription account with Extra Usage
enabled). Otherwise Anthropic returns:
`HTTP 429: rate_limit_error: Extra usage is required for long context requests`.

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

## Option B: Direct OAuth token (`ANTHROPIC_OAUTH_TOKEN`)

**Best for:** scripted or containerized setups where you already hold an Anthropic OAuth token (`sk-ant-oat-...`) and want to inject it via environment variable without running `claude setup-token`.

Set `ANTHROPIC_OAUTH_TOKEN` in the environment of the gateway host. WednesdayAI treats it as an OAuth bearer token with the same behavior as a stored setup-token.

```bash theme={"dark"}
export ANTHROPIC_OAUTH_TOKEN="sk-ant-oat-..."
wednesdayai gateway run
```

Or in your config:

```json5 theme={"dark"}
{
  env: { ANTHROPIC_OAUTH_TOKEN: "sk-ant-oat-..." },
  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
}
```

**Priority:** `ANTHROPIC_OAUTH_TOKEN` is checked before `ANTHROPIC_API_KEY`. If both are set, the OAuth token wins.

**Notes:**

* This env var bypasses the `auth-profiles.json` store; no `wednesdayai models auth` commands are needed.
* `wednesdayai models status` shows this auth as **OAuth (env)**.
* Prompt caching is API-only; `ANTHROPIC_OAUTH_TOKEN` uses OAuth auth, so prompt caching defaults to `"none"` (same behavior as a stored setup-token). Set `cacheRetention` explicitly if your account supports it.

## Option C: 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**:

```bash theme={"dark"}
claude setup-token
```

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

```bash theme={"dark"}
wednesdayai models auth setup-token --provider anthropic
```

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

```bash theme={"dark"}
wednesdayai models auth paste-token --provider anthropic
```

### CLI setup (setup-token)

```bash theme={"dark"}
# Paste a setup-token during onboarding
wednesdayai onboard --auth-choice setup-token
```

### Config snippet (setup-token)

```json5 theme={"dark"}
{
  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
}
```

## Notes

* Three auth options: **API key** (Option A), **OAuth token env var** (Option B / `ANTHROPIC_OAUTH_TOKEN`), or **setup-token** (Option C).
* Generate the setup-token with `claude setup-token` and paste it, or run `wednesdayai 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](https://docs.wednesdayai.dev/next/admin/gateway/troubleshooting.md#oauth-token-refresh-failed-anthropic-claude-subscription).
* Auth details + reuse rules are in [/concepts/oauth](https://docs.wednesdayai.dev/next/developers/concepts/oauth.md).

## 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
  `wednesdayai 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 `wednesdayai models status`.

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

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

More: [/gateway/troubleshooting](https://docs.wednesdayai.dev/next/admin/gateway/troubleshooting.md) and [/help/faq](https://docs.wednesdayai.dev/next/users/help/faq.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.