From be57af7188ddccad7bde6f4360c33b8905f35634 Mon Sep 17 00:00:00 2001 From: Teknium <127238744+teknium1@users.noreply.github.com> Date: Wed, 29 Apr 2026 04:05:43 -0700 Subject: [PATCH] docs(anthropic): clarify OAuth uses Claude Pro/Max subscription usage (#17399) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Users have been asking what they're billed for when they authenticate Anthropic via OAuth in Hermes. Clarify in the provider docs that OAuth routes through Anthropic's Claude Code subscription path — consuming the extra Claude Code usage included with their Pro or Max plan — and that an ANTHROPIC_API_KEY is pay-per-token against that key's org instead. Touches: - integrations/providers.md: new info admonition in Anthropic (Native) section, plus provider-table row. - user-guide/features/credential-pools.md: OAuth comment line. - reference/environment-variables.md: Provider Auth (OAuth) intro. - getting-started/quickstart.md: provider-picker table row. --- website/docs/getting-started/quickstart.md | 2 +- website/docs/integrations/providers.md | 8 +++++++- website/docs/reference/environment-variables.md | 2 +- website/docs/user-guide/features/credential-pools.md | 2 +- 4 files changed, 10 insertions(+), 4 deletions(-) diff --git a/website/docs/getting-started/quickstart.md b/website/docs/getting-started/quickstart.md index 16769bbd0..daf08abe9 100644 --- a/website/docs/getting-started/quickstart.md +++ b/website/docs/getting-started/quickstart.md @@ -70,7 +70,7 @@ Good defaults: |----------|-----------|---------------| | **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) | `hermes model` with Claude Code auth, or an Anthropic API key | +| **Anthropic** | Claude models directly — Pro/Max subscription (uses your included Claude Code usage) or API key | `hermes model` → OAuth login, 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/integrations/providers.md b/website/docs/integrations/providers.md index b7743697d..49d871bb5 100644 --- a/website/docs/integrations/providers.md +++ b/website/docs/integrations/providers.md @@ -18,7 +18,7 @@ You need at least one way to connect to an LLM. Use `hermes model` to switch pro | **OpenAI Codex** | `hermes model` (ChatGPT OAuth, uses Codex models) | | **GitHub Copilot** | `hermes model` (OAuth device code flow, `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, or `gh auth token`) | | **GitHub Copilot ACP** | `hermes model` (spawns local `copilot --acp --stdio`) | -| **Anthropic** | `hermes model` (Claude Pro/Max via Claude Code auth, Anthropic API key, or manual setup-token) | +| **Anthropic** | `hermes model` (Claude Pro/Max subscription via OAuth — uses your included Claude Code usage; also supports Anthropic API key or manual setup-token) | | **OpenRouter** | `OPENROUTER_API_KEY` in `~/.hermes/.env` | | **AI Gateway** | `AI_GATEWAY_API_KEY` in `~/.hermes/.env` (provider: `ai-gateway`) | | **z.ai / GLM** | `GLM_API_KEY` in `~/.hermes/.env` (provider: `zai`) | @@ -158,6 +158,12 @@ If you're trying to switch to a provider you haven't set up yet (e.g. you only h Use Claude models directly through the Anthropic API — no OpenRouter proxy needed. Supports three auth methods: +:::info Claude Pro / Max subscription usage +When you authenticate via `hermes model` → Anthropic OAuth (or via `hermes auth add anthropic --type oauth`), Hermes consumes the **extra usage included with your Claude Pro or Max subscription** — the same quota Claude Code uses. This is per Anthropic's policy: requests identified as Claude Code route against your subscription's included Claude Code usage before any overage billing. You do not need an Anthropic API key or pay-per-token credits for this path — your Pro/Max plan covers it. + +If you use an `ANTHROPIC_API_KEY` instead, requests are billed pay-per-token against that key's organization (standard API pricing, independent of your Pro/Max subscription). +::: + ```bash # With an API key (pay-per-token) export ANTHROPIC_API_KEY=*** diff --git a/website/docs/reference/environment-variables.md b/website/docs/reference/environment-variables.md index 3bb4e170d..31f601b09 100644 --- a/website/docs/reference/environment-variables.md +++ b/website/docs/reference/environment-variables.md @@ -89,7 +89,7 @@ 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. +For native Anthropic auth, Hermes prefers Claude Code's own credential files when they exist because those credentials can refresh automatically. OAuth-authenticated Anthropic requests draw from the **extra Claude Code usage included with your Claude Pro or Max subscription** — no separate API key or per-token billing. 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 | |----------|-------------| diff --git a/website/docs/user-guide/features/credential-pools.md b/website/docs/user-guide/features/credential-pools.md index f4d113696..e50cde334 100644 --- a/website/docs/user-guide/features/credential-pools.md +++ b/website/docs/user-guide/features/credential-pools.md @@ -40,7 +40,7 @@ hermes auth add openrouter --api-key sk-or-v1-your-second-key # Add a second Anthropic key hermes auth add anthropic --type api-key --api-key sk-ant-api03-your-second-key -# Add an Anthropic OAuth credential (Claude Code subscription) +# Add an Anthropic OAuth credential (uses your Claude Pro/Max subscription's included Claude Code usage) hermes auth add anthropic --type oauth # Opens browser for OAuth login ```