docs: clarify model picks and auth setup

docs/concepts/models.md

@@ -23,6 +23,23 @@ Related:
 - `agents.defaults.models` is the allowlist/catalog of models Clawdbot can use (plus aliases).
 - `agents.defaults.imageModel` is used **only when** the primary model can’t accept images.
 
+## Quick model picks (anecdotal)
+
+- **GLM**: a bit better for coding/tool calling.
+- **MiniMax**: better for writing and vibes.
+
+## Setup wizard (recommended)
+
+If you don’t want to hand-edit config, run the onboarding wizard:
+
+```bash
+clawdbot onboard
+```
+
+It can set up model + auth for common providers, including **OpenAI Code (Codex)
+subscription** (OAuth) and **Anthropic** (API key recommended; `claude
+setup-token` also supported).
+
 ## Config keys (overview)
 
 - `agents.defaults.model.primary` and `agents.defaults.model.fallbacks`

docs/gateway/authentication.md

@@ -7,15 +7,50 @@ read_when:
 # Authentication
 
 Clawdbot supports OAuth and API keys for model providers. For Anthropic
-subscription accounts, the most stable path is to **reuse Claude Code OAuth
+accounts, we recommend using an **API key**. Clawdbot can also reuse Claude Code
-credentials**, including the 1‑year token created by `claude setup-token`.
+credentials, including the long‑lived token created by `claude setup-token`.
 
 See [/concepts/oauth](/concepts/oauth) for the full OAuth flow and storage
 layout.
 
-## Preferred Anthropic setup (Claude CLI setup-token)
+## Recommended Anthropic setup (API key)
 
-For Anthropic, the **preferred** path is the Claude CLI setup-token, not an API key.
+If you’re using Anthropic directly, use an API key.
+
+1) Create an API key in the Anthropic Console.
+2) Put it on the **gateway host** (the machine running `clawdbot gateway`).
+
+```bash
+export ANTHROPIC_API_KEY="..."
+clawdbot models status
+```
+
+3) If the Gateway runs under systemd/launchd, prefer putting the key in
+`~/.clawdbot/.env` so the daemon can read it:
+
+```bash
+cat >> ~/.clawdbot/.env <<'EOF'
+ANTHROPIC_API_KEY=...
+EOF
+```
+
+Then restart the daemon (or restart your Gateway process) and re-check:
+
+```bash
+clawdbot models status
+clawdbot doctor
+```
+
+If you’d rather not manage env vars yourself, the onboarding wizard can store
+API keys for daemon use: `clawdbot onboard`.
+
+See [/start/faq](/start/faq) for details on env inheritance (`env.shellEnv`,
+`~/.clawdbot/.env`, systemd/launchd).
+
+## Anthropic: Claude CLI setup-token (supported)
+
+For Anthropic, the recommended path is an **API key**. If you’re already using
+Claude Code, the Claude CLI setup-token is also supported.
 Run it on the **gateway host**:
 
 ```bash
@@ -29,6 +64,17 @@ clawdbot models status
 clawdbot doctor
 ```
 
+This should create (or refresh) an auth profile like `anthropic:claude-cli` in
+the agent auth store.
+
+If you see an Anthropic error like:
+
+```
+This credential is only authorized for use with Claude Code and cannot be used for other API requests.
+```
+
+…use an Anthropic API key instead.
+
 Alternative: run the wrapper (also updates Clawdbot config):
 
 ```bash
@@ -42,22 +88,6 @@ clawdbot models auth paste-token --provider anthropic
 clawdbot models auth paste-token --provider openrouter
 ```
 
-## Recommended: long‑lived Claude Code token
-
-Run this on the **gateway host** (the machine running the Gateway):
-
-```bash
-claude setup-token
-```
-
-This issues a long‑lived **OAuth token** (not an API key) and stores it for
-Claude Code. Then sync and verify:
-
-```bash
-clawdbot models status
-clawdbot doctor
-```
-
 Automation-friendly check (exit `1` when expired/missing, `2` when expiring):
 
 ```bash

docs/start/getting-started.md

@@ -64,7 +64,7 @@ clawdbot onboard --install-daemon
 
 What you’ll choose:
 - **Local vs Remote** gateway
-- **Auth**: **Anthropic OAuth via Claude CLI setup-token (preferred)**, OpenAI OAuth (recommended), API key (optional), or skip for now
+- **Auth**: OpenAI Code (Codex) subscription (OAuth) or API keys. For Anthropic we recommend an API key; `claude setup-token` is also supported.
 - **Providers**: WhatsApp QR login, Telegram/Discord bot tokens, etc.
 - **Daemon**: background install (launchd/systemd; WSL2 uses systemd)
   - **Runtime**: Node (recommended; required for WhatsApp) or Bun (faster, but incompatible with WhatsApp)
@@ -73,7 +73,7 @@ Wizard doc: [Wizard](/start/wizard)
 
 ### Auth: where it lives (important)
 
-- **Preferred Anthropic path:** install Claude CLI on the gateway host and run `claude setup-token`. The wizard can reuse it, and `clawdbot models status` will sync it into Clawdbot auth profiles.
+- **Recommended Anthropic path:** set an API key (wizard can store it for daemon use). `claude setup-token` is also supported if you want to reuse Claude Code credentials.
 
 - OAuth credentials (legacy import): `~/.clawdbot/credentials/oauth.json`
 - Auth profiles (OAuth + API keys): `~/.clawdbot/agents/<agentId>/agent/auth-profiles.json`

docs/start/wizard.md

@@ -41,7 +41,7 @@ The wizard starts with **QuickStart** (defaults) vs **Advanced** (full control).
 ## What the wizard does
 
 **Local mode (default)** walks you through:
-- Model/auth (Anthropic or OpenAI Codex OAuth recommended, API key optional, Minimax M2.1 via LM Studio)
+- Model/auth (OpenAI Code (Codex) subscription OAuth, Anthropic API key (recommended) or `claude setup-token`, plus MiniMax/GLM options)
 - Workspace location + bootstrap files
 - Gateway settings (port/bind/auth/tailscale)
 - Providers (Telegram, WhatsApp, Discord, Signal)
@@ -70,11 +70,12 @@ Tip: `--json` does **not** imply non-interactive mode. Use `--non-interactive` (
      - Full reset (also removes workspace)
 
 2) **Model/Auth**
-   - **Preferred Anthropic setup:** install Claude CLI on the gateway host and run `claude setup-token` (the wizard can run it for you and reuse the token).
+   - **Anthropic API key (recommended)**: uses `ANTHROPIC_API_KEY` if present or prompts for a key, then saves it for daemon use.
+   - **Anthropic token (setup-token)**: run `claude setup-token` on the gateway host (the wizard can run it for you and reuse the token).
    - **Anthropic OAuth (Claude CLI)**: on macOS the wizard checks Keychain item "Claude Code-credentials" (choose "Always Allow" so launchd starts don't block); on Linux/Windows it reuses `~/.claude/.credentials.json` if present.
    - **Anthropic token (paste setup-token)**: run `claude setup-token` in your terminal, then paste the token (you can name it; blank = default).
-   - **OpenAI Codex OAuth (Codex CLI)**: if `~/.codex/auth.json` exists, the wizard can reuse it.
+   - **OpenAI Code (Codex) subscription (Codex CLI)**: if `~/.codex/auth.json` exists, the wizard can reuse it.
-   - **OpenAI Codex OAuth**: browser flow; paste the `code#state`.
+   - **OpenAI Code (Codex) subscription (OAuth)**: browser flow; paste the `code#state`.
      - Sets `agents.defaults.model` to `openai-codex/gpt-5.2` when model is unset or `openai/*`.
    - **OpenAI API key**: uses `OPENAI_API_KEY` if present or prompts for a key, then saves it to `~/.clawdbot/.env` so launchd can read it.
    - **OpenCode Zen (multi-model proxy)**: prompts for `OPENCODE_ZEN_API_KEY` (get it at https://opencode.ai/auth).