docs: add OAuth deep dive

docs/start/faq.md

@@ -339,6 +339,8 @@ Fix: either provide Google auth, or remove/avoid Google models in `agent.model.f
 
 ## Auth profiles: what they are and how to manage them
 
+Related: [/concepts/oauth](/concepts/oauth) (OAuth flows, token storage, multi-account patterns, CLI sync)
+
 ### What is an auth profile?
 
 An auth profile is a named credential record (OAuth or API key) tied to a provider. Profiles live in:

docs/start/hubs.md

@@ -54,6 +54,7 @@ Use these hubs to discover every page, including deep dives and reference docs t
 - [Groups](https://docs.clawd.bot/concepts/groups)
 - [Group messages](https://docs.clawd.bot/concepts/group-messages)
 - [Model failover](https://docs.clawd.bot/concepts/model-failover)
+- [OAuth](https://docs.clawd.bot/concepts/oauth)
 
 ## Providers + ingress
 

docs/start/onboarding.md

@@ -32,6 +32,8 @@ Implementation note (2025-12-19): in local mode, the macOS app bundles the Gatew
 
 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”.
 
+More detail: [/concepts/oauth](/concepts/oauth)
+
 ### Recommended: OAuth (Anthropic)
 
 The macOS app should:
@@ -165,15 +167,29 @@ On the gateway host, create `~/.clawdbot/credentials/oauth.json` with this exact
 
 Set permissions: `chmod 600 ~/.clawdbot/credentials/oauth.json`
 
-**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.
+**Note:** Clawdbot can import from legacy pi-coding-agent paths (`~/.pi/agent/oauth.json`, etc.), but Claude Code/Codex CLI credentials live in different files.
 
-### Using Claude Code credentials
+### Using Claude Code + Codex CLI credentials (direct)
 
-If Claude Code is installed on the gateway host, convert its credentials:
+If these CLIs are installed on the **gateway host** and you’ve already signed in, Clawdbot auto-syncs their OAuth tokens into the per-agent auth profile store (`~/.clawdbot/agents/<agentId>/agent/auth-profiles.json`) on load:
+
+- **Claude Code**: reads `~/.claude/.credentials.json` → profile `anthropic:claude-cli`
+- **Codex CLI**: reads `~/.codex/auth.json` → profile `openai-codex:codex-cli`
+
+Verification:
+
+```bash
+clawdbot providers list
+```
+
+### Fallback: convert Claude Code credentials into `oauth.json`
+
+If you don’t want to install Claude Code on the gateway host, you can still seed the legacy import file:
 
 ```bash
 cat ~/.claude/.credentials.json | jq '{
   anthropic: {
+    type: "oauth",
     access: .claudeAiOauth.accessToken,
     refresh: .claudeAiOauth.refreshToken,
     expires: .claudeAiOauth.expiresAt
@@ -182,12 +198,6 @@ cat ~/.claude/.credentials.json | jq '{
 chmod 600 ~/.clawdbot/credentials/oauth.json
 ```
 
-| Claude Code field | Clawdbot field |
-|-------------------|---------------|
-| `accessToken` | `access` |
-| `refreshToken` | `refresh` |
-| `expiresAt` | `expires` |
-
 ## Workspace backup (recommended)
 
 We suggest creating a **private GitHub repository** to back up the agent

docs/start/wizard.md

@@ -56,7 +56,9 @@ Tip: `--json` does **not** imply non-interactive mode. Use `--non-interactive` (
      - Full reset (also removes workspace)
 
 2) **Model/Auth**
+   - **Anthropic OAuth (Claude CLI)**: if `~/.claude/.credentials.json` exists, the wizard can reuse it.
    - **Anthropic OAuth (recommended)**: browser flow; paste the `code#state`.
+   - **OpenAI Codex OAuth (Codex CLI)**: if `~/.codex/auth.json` exists, the wizard can reuse it.
    - **OpenAI Codex OAuth**: browser flow; paste the `code#state`.
      - Sets `agent.model` to `openai-codex/gpt-5.2` when model is unset or `openai/*`.
    - **API key**: stores the key for you.
@@ -64,6 +66,7 @@ Tip: `--json` does **not** imply non-interactive mode. Use `--non-interactive` (
    - **Skip**: no auth configured yet.
    - Wizard runs a model check and warns if the configured model is unknown or missing auth.
   - OAuth credentials live in `~/.clawdbot/credentials/oauth.json`; auth profiles live in `~/.clawdbot/agents/<agentId>/agent/auth-profiles.json` (API keys + OAuth).
+   - More detail: [/concepts/oauth](/concepts/oauth)
 
 3) **Workspace**
    - Default `~/clawd` (configurable).