From 799114ac8bd2fcaa88ac8939f2e5bf30a68ea4aa Mon Sep 17 00:00:00 2001 From: teknium1 Date: Sat, 14 Mar 2026 19:49:38 -0700 Subject: [PATCH] docs: clarify Anthropic Claude auth flow --- .../docs/developer-guide/provider-runtime.md | 7 +++++++ website/docs/getting-started/quickstart.md | 2 +- .../docs/reference/environment-variables.md | 8 +++++--- website/docs/user-guide/configuration.md | 18 ++++++++++++------ 4 files changed, 25 insertions(+), 10 deletions(-) diff --git a/website/docs/developer-guide/provider-runtime.md b/website/docs/developer-guide/provider-runtime.md index 9bfd48c28..9b6743955 100644 --- a/website/docs/developer-guide/provider-runtime.md +++ b/website/docs/developer-guide/provider-runtime.md @@ -84,6 +84,13 @@ When provider resolution selects `anthropic`, Hermes uses: - the native Anthropic Messages API - `agent/anthropic_adapter.py` for translation +Credential resolution for native Anthropic now prefers refreshable Claude Code credentials over copied env tokens when both are present. In practice that means: + +- Claude Code credential files are treated as the preferred source when they include refreshable auth +- manual `ANTHROPIC_TOKEN` / `CLAUDE_CODE_OAUTH_TOKEN` values still work as explicit overrides +- Hermes preflights Anthropic credential refresh before native Messages API calls +- Hermes still retries once on a 401 after rebuilding the Anthropic client, as a fallback path + ## OpenAI Codex path Codex uses a separate Responses API path: diff --git a/website/docs/getting-started/quickstart.md b/website/docs/getting-started/quickstart.md index e743baf6a..4d8c75ff0 100644 --- a/website/docs/getting-started/quickstart.md +++ b/website/docs/getting-started/quickstart.md @@ -43,7 +43,7 @@ hermes setup # Or configure everything at once |----------|-----------|---------------| | **Nous Portal** | Subscription-based, zero-config | OAuth login via `hermes model` | | **OpenAI Codex** | ChatGPT OAuth, uses Codex models | Device code auth via `hermes model` | -| **Anthropic** | Claude models directly (Pro/Max or API key) | API key or Claude Code setup-token | +| **Anthropic** | Claude models directly (Pro/Max or API key) | `hermes model` with Claude Code auth, or an Anthropic API key | | **OpenRouter** | Multi-provider routing across many models | Enter your API key | | **Z.AI** | GLM / Zhipu-hosted models | Set `GLM_API_KEY` / `ZAI_API_KEY` | | **Kimi / Moonshot** | Moonshot-hosted coding and chat models | Set `KIMI_API_KEY` | diff --git a/website/docs/reference/environment-variables.md b/website/docs/reference/environment-variables.md index f179437a2..66707fa1b 100644 --- a/website/docs/reference/environment-variables.md +++ b/website/docs/reference/environment-variables.md @@ -26,9 +26,9 @@ All variables go in `~/.hermes/.env`. You can also set them with `hermes config | `MINIMAX_BASE_URL` | Override MiniMax base URL (default: `https://api.minimax.io/v1`) | | `MINIMAX_CN_API_KEY` | MiniMax API key — China endpoint ([minimaxi.com](https://www.minimaxi.com)) | | `MINIMAX_CN_BASE_URL` | Override MiniMax China base URL (default: `https://api.minimaxi.com/v1`) | -| `ANTHROPIC_API_KEY` | Anthropic API key or setup-token ([console.anthropic.com](https://console.anthropic.com/)) | -| `ANTHROPIC_TOKEN` | Anthropic OAuth/setup token (alternative to `ANTHROPIC_API_KEY`) | -| `CLAUDE_CODE_OAUTH_TOKEN` | Claude Code setup-token (same as `ANTHROPIC_TOKEN`) | +| `ANTHROPIC_API_KEY` | Anthropic Console API key ([console.anthropic.com](https://console.anthropic.com/)) | +| `ANTHROPIC_TOKEN` | Manual or legacy Anthropic OAuth/setup-token override | +| `CLAUDE_CODE_OAUTH_TOKEN` | Explicit Claude Code token override if you export one manually | | `HERMES_MODEL` | Preferred model name (checked before `LLM_MODEL`, used by gateway) | | `LLM_MODEL` | Default model name (fallback when not set in config.yaml) | | `VOICE_TOOLS_OPENAI_KEY` | OpenAI key for TTS and voice transcription (separate from custom endpoint) | @@ -36,6 +36,8 @@ All variables go in `~/.hermes/.env`. You can also set them with `hermes config ## Provider Auth (OAuth) +For native Anthropic auth, Hermes prefers Claude Code's own credential files when they exist because those credentials can refresh automatically. Environment variables such as `ANTHROPIC_TOKEN` remain useful as manual overrides, but they are no longer the preferred path for Claude Pro/Max login. + | Variable | Description | |----------|-------------| | `HERMES_INFERENCE_PROVIDER` | Override provider selection: `auto`, `openrouter`, `nous`, `openai-codex`, `anthropic`, `zai`, `kimi-coding`, `minimax`, `minimax-cn` (default: `auto`) | diff --git a/website/docs/user-guide/configuration.md b/website/docs/user-guide/configuration.md index 13da3fe4e..dc97d11c4 100644 --- a/website/docs/user-guide/configuration.md +++ b/website/docs/user-guide/configuration.md @@ -63,7 +63,7 @@ You need at least one way to connect to an LLM. Use `hermes model` to switch pro |----------|-------| | **Nous Portal** | `hermes model` (OAuth, subscription-based) | | **OpenAI Codex** | `hermes model` (ChatGPT OAuth, uses Codex models) | -| **Anthropic** | `hermes model` (API key, setup-token, or Claude Code auto-detect) | +| **Anthropic** | `hermes model` (Claude Pro/Max via Claude Code auth, Anthropic API key, or manual setup-token) | | **OpenRouter** | `OPENROUTER_API_KEY` in `~/.hermes/.env` | | **z.ai / GLM** | `GLM_API_KEY` in `~/.hermes/.env` (provider: `zai`) | | **Kimi / Moonshot** | `KIMI_API_KEY` in `~/.hermes/.env` (provider: `kimi-coding`) | @@ -85,17 +85,23 @@ Use Claude models directly through the Anthropic API — no OpenRouter proxy nee ```bash # With an API key (pay-per-token) -export ANTHROPIC_API_KEY=sk-ant-api03-... +export ANTHROPIC_API_KEY=*** hermes chat --provider anthropic --model claude-sonnet-4-6 -# With a Claude Code setup-token (Pro/Max subscription) -export ANTHROPIC_API_KEY=sk-ant-oat01-... # from 'claude setup-token' +# Preferred: authenticate through `hermes model` +# Hermes will use Claude Code's credential store directly when available +hermes model + +# Manual override with a setup-token (fallback / legacy) +export ANTHROPIC_TOKEN=*** # setup-token or manual OAuth token hermes chat --provider anthropic -# Auto-detect Claude Code credentials (if you have Claude Code installed) -hermes chat --provider anthropic # reads ~/.claude.json automatically +# Auto-detect Claude Code credentials (if you already use Claude Code) +hermes chat --provider anthropic # reads Claude Code credential files automatically ``` +When you choose Anthropic OAuth through `hermes model`, Hermes prefers Claude Code's own credential store over copying the token into `~/.hermes/.env`. That keeps refreshable Claude credentials refreshable. + Or set it permanently: ```yaml model: