vultr/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-04-12 09:41:11 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(anthropic): clarify api key and doctor recovery

Browse Source
This commit is contained in:
Peter Steinberger
2026-04-05 18:04:36 +01:00
parent 2d7157b424
commit fe93f29486
18 changed files with 193 additions and 433 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
docs/help/faq.md
View File

@@ -565,7 +565,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
<Accordion title="What does onboarding actually do?">
`openclaw onboard` is the recommended setup path. In **local mode** it walks you through:
- **Model/auth setup** (provider OAuth, Claude CLI reuse, and API keys supported, plus local model options such as LM Studio)
- **Model/auth setup** (provider OAuth, API keys, Anthropic legacy setup-token, plus local model options such as LM Studio)
- **Workspace** location + bootstrap files
- **Gateway settings** (bind/port/auth/tailscale)
- **Channels** (WhatsApp, Telegram, Discord, Mattermost, Signal, iMessage, plus bundled channel plugins like QQ Bot)
@@ -581,14 +581,17 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
**local-only models** so your data stays on your device. Subscriptions (Claude
Pro/Max or OpenAI Codex) are optional ways to authenticate those providers.
We believe Claude Code CLI fallback is likely allowed for local,
user-managed automation based on Anthropic's public CLI docs. That said,
Anthropic's third-party harness policy creates enough ambiguity around
subscription-backed use in external products that we do not recommend it
for production. Anthropic also notified OpenClaw users on **April 4, 2026
at 12:00 PM PT / 8:00 PM BST** that the **OpenClaw** Claude-login path
counts as third-party harness usage and now requires **Extra Usage**
billed separately from the subscription. OpenAI Codex OAuth is explicitly
For Anthropic in OpenClaw, the practical split is:
- **Anthropic API key**: normal Anthropic API billing
- **Claude subscription auth in OpenClaw**: Anthropic told OpenClaw users on
**April 4, 2026 at 12:00 PM PT / 8:00 PM BST** that this requires
**Extra Usage** billed separately from the subscription
Our local repros also show that `claude -p --append-system-prompt ...` can
hit the same Extra Usage guard when the appended prompt identifies
OpenClaw, while the same prompt string does **not** reproduce that block on
the Anthropic SDK + API-key path. OpenAI Codex OAuth is explicitly
supported for external tools like OpenClaw.
OpenClaw also supports other hosted subscription-style options including
@@ -603,30 +606,27 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
</Accordion>
<Accordion title="Can I use Claude Max subscription without an API key?">
Yes, via a local **Claude CLI** login on the gateway host.
Yes, but treat it as **Claude subscription auth with Extra Usage**.
Claude Pro/Max subscriptions **do not include an API key**, so Claude CLI
reuse is the local fallback path in OpenClaw. We believe Claude Code CLI
fallback is likely allowed for local, user-managed automation based on
Anthropic's public CLI docs. That said, Anthropic's third-party harness
policy creates enough ambiguity around subscription-backed use in external
products that we do not recommend it for production. We recommend
Anthropic API keys instead.
Claude Pro/Max subscriptions do not include an API key. In OpenClaw, that
means Anthropic's OpenClaw-specific billing notice applies: subscription
traffic requires **Extra Usage**. If you want Anthropic traffic without
that Extra Usage path, use an Anthropic API key instead.
</Accordion>
<Accordion title="Do you support Claude subscription auth (Claude Pro or Max)?">
Yes. Reuse a local **Claude CLI** login on the gateway host with `openclaw models auth login --provider anthropic --method cli --set-default`.
Yes, but the supported interpretation is now:
Anthropic setup-token is also available again as a legacy/manual OpenClaw path. Anthropic's OpenClaw-specific billing notice still applies there, so use it with the expectation that Anthropic requires **Extra Usage**. See [Anthropic](/providers/anthropic) and [OAuth](/concepts/oauth).
- Anthropic in OpenClaw with a subscription means **Extra Usage**
- Anthropic in OpenClaw without that path means **API key**
Important: We believe Claude Code CLI fallback is likely allowed for local,
user-managed automation based on Anthropic's public CLI docs. That said,
Anthropic's third-party harness policy creates enough ambiguity around
subscription-backed use in external products that we do not recommend it
for production. Anthropic also told OpenClaw users on **April 4, 2026 at
12:00 PM PT / 8:00 PM BST** that the **OpenClaw** Claude-login path
requires **Extra Usage** billed separately from the subscription.
Anthropic setup-token is still available as a legacy/manual OpenClaw path,
and Anthropic's OpenClaw-specific billing notice still applies there. We
also reproduced the same billing guard locally with direct
`claude -p --append-system-prompt ...` usage when the appended prompt
identifies OpenClaw, while the same prompt string did **not** reproduce on
the Anthropic SDK + API-key path.
For production or multi-user workloads, Anthropic API key auth is the
safer, recommended choice. If you want other subscription-style hosted

34
docs/help/testing.md
View File

@@ -245,7 +245,7 @@ openclaw models list
openclaw models list --json
```
## Live: CLI backend smoke (Claude CLI or other local CLIs)
## Live: CLI backend smoke (Codex CLI or other local CLIs)
- Test: `src/gateway/gateway-cli-backend.live.test.ts`
- Goal: validate the Gateway + agent pipeline using a local CLI backend, without touching your default config.
@@ -253,26 +253,23 @@ openclaw models list --json
- `pnpm test:live` (or `OPENCLAW_LIVE_TEST=1` if invoking Vitest directly)
- `OPENCLAW_LIVE_CLI_BACKEND=1`
- Defaults:
- Model: `claude-cli/claude-sonnet-4-6`
- Command: `claude`
- Args: `["-p","--output-format","stream-json","--include-partial-messages","--verbose","--permission-mode","bypassPermissions"]`
- Model: `codex-cli/gpt-5.4`
- Command: `codex`
- Args: `["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]`
- Overrides (optional):
- `OPENCLAW_LIVE_CLI_BACKEND_MODEL="claude-cli/claude-opus-4-6"`
- `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"`
- `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/claude"`
- `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["-p","--output-format","stream-json","--include-partial-messages","--verbose","--permission-mode","bypassPermissions"]'`
- `OPENCLAW_LIVE_CLI_BACKEND_CLEAR_ENV='["ANTHROPIC_API_KEY","ANTHROPIC_API_KEY_OLD"]'`
- `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"`
- `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'`
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` to send a real image attachment (paths are injected into the prompt).
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` to pass image file paths as CLI args instead of prompt injection.
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (or `"list"`) to control how image args are passed when `IMAGE_ARG` is set.
- `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` to send a second turn and validate resume flow.
- `OPENCLAW_LIVE_CLI_BACKEND_DISABLE_MCP_CONFIG=0` to keep Claude CLI MCP config enabled (default injects a temporary strict empty `--mcp-config` so ambient/global MCP servers stay disabled during the smoke).
Example:
```bash
OPENCLAW_LIVE_CLI_BACKEND=1 \
OPENCLAW_LIVE_CLI_BACKEND_MODEL="claude-cli/claude-sonnet-4-6" \
OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4" \
pnpm test:live src/gateway/gateway-cli-backend.live.test.ts
```
@@ -285,10 +282,8 @@ pnpm test:docker:live-cli-backend
Notes:
- The Docker runner lives at `scripts/test-live-cli-backend-docker.sh`.
- It runs the live CLI-backend smoke inside the repo Docker image as the non-root `node` user, because Claude CLI rejects `bypassPermissions` when invoked as root.
- For `claude-cli`, it installs the Linux `@anthropic-ai/claude-code` package into a cached writable prefix at `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (default: `~/.cache/openclaw/docker-cli-tools`).
- For `claude-cli`, the live smoke injects a strict empty MCP config unless you set `OPENCLAW_LIVE_CLI_BACKEND_DISABLE_MCP_CONFIG=0`.
- It copies `~/.claude` into the container when available, but on machines where Claude auth is backed by `ANTHROPIC_API_KEY`, it also preserves `ANTHROPIC_API_KEY` / `ANTHROPIC_API_KEY_OLD` for the child Claude CLI via `OPENCLAW_LIVE_CLI_BACKEND_PRESERVE_ENV`.
- It runs the live CLI-backend smoke inside the repo Docker image as the non-root `node` user.
- For `codex-cli`, it installs the Linux `@openai/codex` package into a cached writable prefix at `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (default: `~/.cache/openclaw/docker-cli-tools`).
## Live: ACP bind smoke (`/acp spawn ... --bind here`)
@@ -330,8 +325,8 @@ pnpm test:docker:live-acp-bind
Docker notes:
- The Docker runner lives at `scripts/test-live-acp-bind-docker.sh`.
- It sources `~/.profile`, copies the matching CLI auth home (`~/.claude` or `~/.codex`) into the container, then installs the requested live CLI (`@anthropic-ai/claude-code` or `@openai/codex`) if missing.
- Inside Docker, the runner relies on the embedded `acpx` plugin's built-in agent registry and the sourced profile env; use `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` only when you need a custom harness command.
- It sources `~/.profile`, stages the matching CLI auth material into the container, installs `acpx` into a writable npm prefix, then installs the requested live CLI (`@anthropic-ai/claude-code` or `@openai/codex`) if missing.
- Inside Docker, the runner sets `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` so acpx keeps provider env vars from the sourced profile available to the child harness CLI.
### Recommended live recipes
@@ -528,9 +523,10 @@ Useful env vars:
- `OPENCLAW_WORKSPACE_DIR=...` (default: `~/.openclaw/workspace`) mounted to `/home/node/.openclaw/workspace`
- `OPENCLAW_PROFILE_FILE=...` (default: `~/.profile`) mounted to `/home/node/.profile` and sourced before running tests
- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (default: `~/.cache/openclaw/docker-cli-tools`) mounted to `/home/node/.npm-global` for cached CLI installs inside Docker
- External CLI auth dirs under `$HOME` are mounted read-only under `/host-auth/...`, then copied into `/home/node/...` before tests start
- Default: mount all supported dirs (`.codex`, `.claude`, `.minimax`)
- Narrowed provider runs mount only the needed dirs inferred from `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS`
- External CLI auth dirs/files under `$HOME` are mounted read-only under `/host-auth...`, then copied into `/home/node/...` before tests start
- Default dirs: `.codex`, `.minimax`
- Default files: `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json`
- Narrowed provider runs mount only the needed dirs/files inferred from `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS`
- Override manually with `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none`, or a comma list like `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex`
- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` to narrow the run
- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` to filter providers in-container