From 2c0f3a2887fdc7a7580c37f6247fa6c5d4ea3b72 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Mon, 5 Jan 2026 06:46:20 +0100 Subject: [PATCH] docs: update auth docs --- CHANGELOG.md | 4 ++-- docs/configuration.md | 15 +++++++++++++ docs/faq.md | 12 +++++----- docs/onboarding.md | 51 ++++++++++++++++++++++++------------------- docs/wizard.md | 4 +++- 5 files changed, 55 insertions(+), 31 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bef0f58e7..d4b407666 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,10 +8,10 @@ - Onboarding: resolve CLI entrypoint when running via `npx` so gateway daemon install works without a build step. - TUI: migrate key handling to the updated pi-tui Key matcher API. - macOS: local gateway now connects via tailnet IP when bind mode is `tailnet`/`auto`. -- macOS: Settings now use a sidebar layout to avoid toolbar overflow in Connections. -- macOS: Settings window hides the preferences toolbar row to keep a clean sidebar layout. +- macOS: Connections removes the sidebar toggle from the Settings toolbar to avoid overflow. - macOS: drop deprecated `afterMs` from agent wait params to match gateway schema. - Auth: add OpenAI Codex OAuth support and migrate legacy oauth.json into auth.json. +- Docs: clarify auth storage, migration, and OpenAI Codex OAuth onboarding. - Sandbox: copy inbound media into sandbox workspaces so agent tools can read attachments. ### Maintenance diff --git a/docs/configuration.md b/docs/configuration.md index 1b2355a47..006814237 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -89,6 +89,21 @@ Env var equivalent: - `CLAWDBOT_LOAD_SHELL_ENV=1` - `CLAWDBOT_SHELL_ENV_TIMEOUT_MS=15000` +### Auth storage (OAuth + API keys) + +Clawdbot keeps subscription OAuth tokens + API keys in the **agent auth store**: +- `~/.clawdbot/agent/auth.json` + +The agent directory can be overridden with: +- `CLAWDBOT_AGENT_DIR` (preferred) +- `PI_CODING_AGENT_DIR` (legacy) + +Legacy OAuth storage is still supported for migration: +- Default: `~/.clawdbot/credentials/oauth.json` (or `$CLAWDBOT_STATE_DIR/credentials/oauth.json`) +- Override: `CLAWDBOT_OAUTH_DIR` + +On first use, Clawdbot auto‑migrates legacy `oauth.json` entries into `auth.json`. + ### `identity` Optional agent identity used for defaults and UX. This is written by the macOS onboarding assistant. diff --git a/docs/faq.md b/docs/faq.md index 6f10fcf84..4918cdb97 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -14,7 +14,9 @@ Everything lives under `~/.clawdbot/`: | Path | Purpose | |------|---------| | `~/.clawdbot/clawdbot.json` | Main config (JSON5) | +| `~/.clawdbot/agent/auth.json` | OAuth + API key store (Anthropic/OpenAI, etc.) | | `~/.clawdbot/credentials/` | WhatsApp/Telegram auth tokens | +| `~/.clawdbot/credentials/oauth.json` | Legacy OAuth store (auto‑migrated) | | `~/.clawdbot/sessions/` | Conversation history & state | | `~/.clawdbot/sessions/sessions.json` | Session metadata | @@ -105,18 +107,18 @@ The macOS app onboarding is still being polished and can have quirks (e.g., What ### OAuth vs API key — what's the difference? -- **OAuth** — Uses your Claude Pro/Max subscription ($20-100/mo flat). No per-token charges. ✅ Recommended! -- **API key** — Pay-per-token via console.anthropic.com. Can get expensive fast. +- **OAuth** — Uses your **subscription** (Anthropic Claude Pro/Max or OpenAI ChatGPT/Codex). No per‑token charges. ✅ Recommended! +- **API key** — Pay‑per‑token via the provider’s API billing. Can get expensive fast. They're **separate billing**! An API key does NOT use your subscription. -**For OAuth:** During onboarding, pick "Anthropic OAuth", log in to your Claude account, paste the code back. Or just run: +**For OAuth:** During onboarding, pick **Anthropic OAuth** or **OpenAI Codex OAuth**, log in, paste the code/URL when prompted. Or just run: ```bash pnpm clawdbot login ``` -**If OAuth fails** (headless/container): Do OAuth on a normal machine, then copy `~/.clawdbot/` to your server. The auth is just a JSON file. +**If OAuth fails** (headless/container): Do OAuth on a normal machine, then copy `~/.clawdbot/agent/auth.json` to your server. The auth is just a JSON file. ### How are env vars loaded? @@ -146,7 +148,7 @@ Or set `CLAWDBOT_LOAD_SHELL_ENV=1` (timeout: `CLAWDBOT_SHELL_ENV_TIMEOUT_MS=1500 OAuth needs the callback to reach the machine running the CLI. Options: -1. **Copy auth manually** — Run OAuth on your laptop, copy `~/.clawdbot/credentials/` to the container. +1. **Copy auth manually** — Run OAuth on your laptop, copy `~/.clawdbot/agent/auth.json` to the container. 2. **SSH tunnel** — `ssh -L 18789:localhost:18789 user@server` 3. **Tailscale** — Put both machines on your tailnet. diff --git a/docs/onboarding.md b/docs/onboarding.md index 85caf4612..39edd2278 100644 --- a/docs/onboarding.md +++ b/docs/onboarding.md @@ -1,17 +1,17 @@ --- -summary: "Planned first-run onboarding flow for Clawdbot (local vs remote, Anthropic OAuth, workspace bootstrap ritual)" +summary: "Planned first-run onboarding flow for Clawdbot (local vs remote, OAuth auth, workspace bootstrap ritual)" read_when: - Designing the macOS onboarding assistant - - Implementing Anthropic auth or identity setup + - Implementing Anthropic/OpenAI auth or identity setup --- # Onboarding (macOS app) -This doc describes the intended **first-run onboarding** for Clawdbot. The goal is a good “day 0” experience: pick where the Gateway runs, bind Claude (Anthropic) auth for the embedded agent runtime, and then let the **agent bootstrap itself** via a first-run ritual in the workspace. +This doc describes the intended **first-run onboarding** for Clawdbot. The goal is a good “day 0” experience: pick where the Gateway runs, bind subscription auth (Anthropic or OpenAI) for the embedded agent runtime, and then let the **agent bootstrap itself** via a first-run ritual in the workspace. ## Page order (high level) 1) **Local vs Remote** -2) **(Local only)** Connect Claude (Anthropic OAuth) — optional, but recommended +2) **(Local only)** Connect subscription auth (Anthropic / OpenAI OAuth) — optional, but recommended 3) **Connect Gmail (optional)** — run `clawdbot hooks gmail setup` to configure Pub/Sub hooks 4) **Onboarding chat** — dedicated session where the agent introduces itself and guides setup @@ -19,7 +19,7 @@ This doc describes the intended **first-run onboarding** for Clawdbot. The goal First question: where does the **Gateway** run? -- **Local (this Mac):** onboarding can run the Anthropic OAuth flow and write the Clawdbot token store locally. +- **Local (this Mac):** onboarding can run OAuth flows and write the Clawdbot auth store locally. - **Remote (over SSH/tailnet):** onboarding must not run OAuth locally, because credentials must exist on the **gateway host**. Gateway auth tip: @@ -28,20 +28,28 @@ Gateway auth tip: Implementation note (2025-12-19): in local mode, the macOS app bundles the Gateway and enables it via a per-user launchd LaunchAgent (no global npm install/Node requirement for the user). -## 2) Local-only: Connect Claude (Anthropic OAuth) +## 2) Local-only: Connect subscription auth (Anthropic / OpenAI OAuth) -This is the “bind Clawdbot to Anthropic” step. It is explicitly the **Anthropic (Claude Pro/Max) OAuth flow**, not a generic “login”. +This is the “bind Clawdbot to subscription auth” step. It is explicitly the **Anthropic (Claude Pro/Max)** or **OpenAI (ChatGPT/Codex)** OAuth flow, not a generic “login”. -### Recommended: OAuth +### Recommended: OAuth (Anthropic) The macOS app should: - Start the Anthropic OAuth (PKCE) flow in the user’s browser. - Ask the user to paste the `code#state` value. - Exchange it for tokens and write credentials to: - - `~/.clawdbot/credentials/oauth.json` (file mode `0600`, directory mode `0700`) + - `~/.clawdbot/agent/auth.json` (file mode `0600`, directory mode `0700`) -Why this location matters: it’s the Clawdbot-owned OAuth store. -On first run, Clawdbot can import existing OAuth tokens from legacy p/Claude locations if present. +Why this location matters: it’s the Clawdbot-owned auth store (OAuth + API keys). +Clawdbot auto-migrates legacy OAuth tokens from `~/.clawdbot/credentials/oauth.json` (and older pi/Claude locations) into `auth.json` on first use. + +### Recommended: OAuth (OpenAI Codex) + +The macOS app should: +- Start the OpenAI Codex OAuth (PKCE) flow in the user’s browser. +- Auto-capture the callback on `http://127.0.0.1:1455/auth/callback` when possible. +- If the callback fails, prompt the user to paste the redirect URL or code. +- Store credentials in `~/.clawdbot/agent/auth.json` (same auth store as Anthropic). ### Alternative: API key (instructions only) @@ -136,30 +144,27 @@ Daily memory lives under `memory/` in the workspace: ## Remote mode note (why OAuth is hidden) -If the Gateway runs on another machine, the Anthropic OAuth credentials must be created/stored on that host (where the agent runtime runs). +If the Gateway runs on another machine, OAuth credentials must be created/stored on that host (where the agent runtime runs). For now, remote onboarding should: - explain why OAuth isn't shown -- point the user at the credential location (`~/.clawdbot/credentials/oauth.json`) and the workspace location on the gateway host +- point the user at the credential location (`~/.clawdbot/agent/auth.json`) and the workspace location on the gateway host - mention that the **bootstrap ritual happens on the gateway host** (same BOOTSTRAP/IDENTITY/USER files) ### Manual credential setup -On the gateway host, create `~/.clawdbot/credentials/oauth.json` with this exact format: +On the gateway host, create `~/.clawdbot/agent/auth.json` with this exact format: ```json { - "anthropic": { - "access": "sk-ant-oat01-...", - "refresh": "sk-ant-ort01-...", - "expires": 1767304352803 - } + "anthropic": { "type": "oauth", "access": "sk-ant-oat01-...", "refresh": "sk-ant-ort01-...", "expires": 1767304352803 }, + "openai-codex": { "type": "oauth", "access": "eyJhbGciOi...", "refresh": "oai-refresh-...", "expires": 1767304352803, "accountId": "acct_..." } } ``` -Set permissions: `chmod 600 ~/.clawdbot/credentials/oauth.json` +Set permissions: `chmod 600 ~/.clawdbot/agent/auth.json` -**Note:** Clawdbot can auto-import from legacy pi-coding-agent paths (`~/.pi/agent/oauth.json`, etc.) but this does NOT work with Claude Code credentials — different file and format. +**Note:** Clawdbot auto-imports from legacy pi-coding-agent paths (`~/.pi/agent/oauth.json`, etc.) but this does NOT work with Claude Code credentials — different file and format. ### Using Claude Code credentials @@ -172,8 +177,8 @@ cat ~/.claude/.credentials.json | jq '{ refresh: .claudeAiOauth.refreshToken, expires: .claudeAiOauth.expiresAt } -}' > ~/.clawdbot/credentials/oauth.json -chmod 600 ~/.clawdbot/credentials/oauth.json +}' > ~/.clawdbot/agent/auth.json +chmod 600 ~/.clawdbot/agent/auth.json ``` | Claude Code field | Clawdbot field | diff --git a/docs/wizard.md b/docs/wizard.md index 0ef0de786..33a109320 100644 --- a/docs/wizard.md +++ b/docs/wizard.md @@ -26,7 +26,7 @@ clawdbot configure ## What the wizard does **Local mode (default)** walks you through: -- Model/auth (Anthropic OAuth recommended, API key optional, Minimax M2.1 via LM Studio) +- Model/auth (Anthropic or OpenAI Codex OAuth recommended, API key optional, Minimax M2.1 via LM Studio) - Workspace location + bootstrap files - Gateway settings (port/bind/auth/tailscale) - Providers (WhatsApp, Telegram, Discord, Signal) @@ -48,9 +48,11 @@ It does **not** install or change anything on the remote host. 2) **Model/Auth** - **Anthropic OAuth (recommended)**: browser flow; paste the `code#state`. + - **OpenAI Codex OAuth**: browser flow; paste the `code#state`. - **API key**: stores the key for you. - **Minimax M2.1 (LM Studio)**: config is auto‑written for the LM Studio endpoint. - **Skip**: no auth configured yet. + - OAuth + API keys are stored in `~/.clawdbot/agent/auth.json`. 3) **Workspace** - Default `~/clawd` (configurable).