From 05c8a85f8b5c450b6aa0eb330981cddafc5b5bb9 Mon Sep 17 00:00:00 2001 From: asatire1 Date: Mon, 3 Aug 2026 22:50:23 +0100 Subject: [PATCH] docs(acp): correct subscription auth for codex-acp and claude-agent-acp MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Codex section said an OpenAI API key was required, "not a ChatGPT subscription", and described a 426 WebSocket fallback. That is no longer how the adapter behaves: codex-acp reuses the Codex CLI's stored login at ~/.codex/auth.json, and reads CODEX_API_KEY/OPENAI_API_KEY only when the api-key auth method is selected. The Claude section told operators to export ANTHROPIC_API_KEY, which is also unnecessary — claude-agent-acp advertises claude-ai-login ("Claude Subscription") alongside console-login ("Anthropic Console (API usage billing)"). It does keep its own credential store rather than inheriting an existing Claude Code login, so the one-time --claudeai command is now shown explicitly. Neither claim was true because buzz-acp injects no auth of its own: AcpClient::spawn uses tokio::process::Command with no env_clear(), so the adapter's own login applies. Verified against codex-acp 1.1.9 and claude-agent-acp 0.64.2 by driving each adapter through initialize -> session/new -> session/prompt with ANTHROPIC_API_KEY, OPENAI_API_KEY, CODEX_API_KEY and CLAUDE_CODE_OAUTH_TOKEN removed from the child environment. Both completed a turn with stopReason: end_turn. Also confirmed end-to-end through buzz-acp against a local relay: the agent replied to an @mention with zero *_API_KEY vars in the harness process environment. Signed-off-by: asatire1 --- crates/buzz-acp/README.md | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/crates/buzz-acp/README.md b/crates/buzz-acp/README.md index e6164b02dd..313b501124 100644 --- a/crates/buzz-acp/README.md +++ b/crates/buzz-acp/README.md @@ -72,13 +72,17 @@ That's it. The harness spawns `goose acp`, connects to the relay, discovers chan # Install the adapter (npm package — no Rust build required) npm install -g @agentclientprotocol/codex-acp -# Run -export OPENAI_API_KEY="sk-..." # required — use an OpenAI API key, not a ChatGPT subscription +# Authenticate once — either a ChatGPT subscription or an API key +codex login buzz-acp ``` -> **API key note:** `codex-acp` always attempts a ChatGPT WebSocket login first, which logs a `426 Upgrade Required` error. This is expected and non-fatal — it falls back to `OPENAI_API_KEY` automatically. Set `OPENAI_API_KEY` to ensure it has a working fallback. +> **Auth note:** a ChatGPT subscription works. `codex-acp` reuses the Codex CLI's stored +> login at `~/.codex/auth.json`, and `buzz-acp` spawns it with the parent environment intact, +> so no API key is involved. `CODEX_API_KEY`/`OPENAI_API_KEY` are read only when the +> API-key auth method is selected — set one if you would rather bill the API. Do not set +> `NO_BROWSER=1`, which hides the ChatGPT auth method. ## Running with Claude Code @@ -88,13 +92,22 @@ buzz-acp # Install the current adapter package npm install -g @agentclientprotocol/claude-agent-acp +# Authenticate once — a Claude Pro/Max subscription or the Anthropic Console +claude-agent-acp --cli auth login --claudeai + # Run -export ANTHROPIC_API_KEY="sk-ant-..." export BUZZ_ACP_AGENT_COMMAND="claude-agent-acp" buzz-acp ``` +> **Auth note:** a Claude Pro/Max subscription works, and no `ANTHROPIC_API_KEY` is needed. +> The adapter advertises two methods — `claude-ai-login` ("Claude Subscription") and +> `console-login` ("Anthropic Console (API usage billing)") — and keeps its own credential +> store, so it does **not** inherit an existing Claude Code login; run the `--claudeai` +> command above once. Set `ANTHROPIC_API_KEY` only if you would rather bill the API. +> Do not pass `--hide-claude-auth`, which makes the adapter reject subscription sessions. + Older installs that still expose `claude-code-acp` are also supported. `buzz-acp` treats both Claude ACP command names as the same zero-arg runtime.