docs: update auth docs

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: Connections removes the sidebar toggle from the Settings toolbar to avoid overflow.
-- macOS: Settings window hides the preferences toolbar row to keep a clean sidebar layout.
 - 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

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.

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!
+- **OAuth** — Uses your **subscription** (Anthropic Claude Pro/Max or OpenAI ChatGPT/Codex). No per‑token charges. ✅ Recommended!
-- **API key** — Pay-per-token via console.anthropic.com. Can get expensive fast.
+- **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.
 

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.
+Why this location matters: it’s the Clawdbot-owned auth store (OAuth + API keys).
-On first run, Clawdbot can import existing OAuth tokens from legacy p/Claude locations if present.
+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": {
+  "anthropic": { "type": "oauth", "access": "sk-ant-oat01-...", "refresh": "sk-ant-ort01-...", "expires": 1767304352803 },
-    "access": "sk-ant-oat01-...",
+  "openai-codex": { "type": "oauth", "access": "eyJhbGciOi...", "refresh": "oai-refresh-...", "expires": 1767304352803, "accountId": "acct_..." }
-    "refresh": "sk-ant-ort01-...",
-    "expires": 1767304352803
-  }
 }
 ```
 
-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
+}' > ~/.clawdbot/agent/auth.json
-chmod 600 ~/.clawdbot/credentials/oauth.json
+chmod 600 ~/.clawdbot/agent/auth.json
 ```
 
 | Claude Code field | Clawdbot field |

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