docs: update auth docs

2026-01-05 06:46:20 +01:00
parent bc74e7cd9b
commit 2c0f3a2887
5 changed files with 55 additions and 31 deletions
--- 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
--- 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.
--- 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.

--- 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 |
--- 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).