diff --git a/docs/configuration.md b/docs/configuration.md index 6d1ad7563..917bda69d 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -91,18 +91,18 @@ Env var equivalent: ### Auth storage (OAuth + API keys) -Clawdbot keeps subscription OAuth tokens + API keys in the **agent auth store**: +Clawdbot stores **OAuth credentials** in: +- `~/.clawdbot/credentials/oauth.json` (or `$CLAWDBOT_STATE_DIR/credentials/oauth.json`) + +Clawdbot stores **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) +Overrides: +- OAuth dir: `CLAWDBOT_OAUTH_DIR` +- Agent dir: `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`. +On first use, Clawdbot imports `oauth.json` entries into `auth.json` so the embedded +agent can use them. `oauth.json` remains the source of truth for OAuth refresh. ### `identity` diff --git a/docs/faq.md b/docs/faq.md index 6ec58618f..a6128ac37 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -14,9 +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/oauth.json` | OAuth credentials (Anthropic/OpenAI, etc.) | +| `~/.clawdbot/agent/auth.json` | API key store | | `~/.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 | @@ -118,7 +118,7 @@ They're **separate billing**! An API key does NOT use your subscription. pnpm clawdbot login ``` -**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. +**If OAuth fails** (headless/container): Do OAuth on a normal machine, then copy `~/.clawdbot/credentials/oauth.json` to your server. The auth is just a JSON file. ### How are env vars loaded? @@ -148,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/agent/auth.json` to the container. +1. **Copy auth manually** — Run OAuth on your laptop, copy `~/.clawdbot/credentials/oauth.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 39edd2278..948d1c2c2 100644 --- a/docs/onboarding.md +++ b/docs/onboarding.md @@ -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 OAuth flows and write the Clawdbot auth store locally. +- **Local (this Mac):** onboarding can run OAuth flows and write OAuth credentials locally. - **Remote (over SSH/tailnet):** onboarding must not run OAuth locally, because credentials must exist on the **gateway host**. Gateway auth tip: @@ -38,10 +38,10 @@ 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/agent/auth.json` (file mode `0600`, directory mode `0700`) + - `~/.clawdbot/credentials/oauth.json` (file mode `0600`, directory mode `0700`) -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. +Why this location matters: it’s the Clawdbot-owned OAuth store. +Clawdbot also imports `oauth.json` into the agent auth store (`~/.clawdbot/agent/auth.json`) on first use. ### Recommended: OAuth (OpenAI Codex) @@ -49,7 +49,7 @@ 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). +- Store credentials in `~/.clawdbot/credentials/oauth.json` (same OAuth store as Anthropic). ### Alternative: API key (instructions only) @@ -148,12 +148,12 @@ If the Gateway runs on another machine, OAuth credentials must be created/stored For now, remote onboarding should: - explain why OAuth isn't shown -- point the user at the credential location (`~/.clawdbot/agent/auth.json`) and the workspace location on the gateway host +- point the user at the credential location (`~/.clawdbot/credentials/oauth.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/agent/auth.json` with this exact format: +On the gateway host, create `~/.clawdbot/credentials/oauth.json` with this exact format: ```json { @@ -162,7 +162,7 @@ On the gateway host, create `~/.clawdbot/agent/auth.json` with this exact format } ``` -Set permissions: `chmod 600 ~/.clawdbot/agent/auth.json` +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. @@ -177,8 +177,8 @@ cat ~/.claude/.credentials.json | jq '{ refresh: .claudeAiOauth.refreshToken, expires: .claudeAiOauth.expiresAt } -}' > ~/.clawdbot/agent/auth.json -chmod 600 ~/.clawdbot/agent/auth.json +}' > ~/.clawdbot/credentials/oauth.json +chmod 600 ~/.clawdbot/credentials/oauth.json ``` | Claude Code field | Clawdbot field | diff --git a/docs/wizard.md b/docs/wizard.md index d4ec67028..ae10f3785 100644 --- a/docs/wizard.md +++ b/docs/wizard.md @@ -52,7 +52,7 @@ It does **not** install or change anything on the remote host. - **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`. + - OAuth credentials live in `~/.clawdbot/credentials/oauth.json`; API keys live in `~/.clawdbot/agent/auth.json`. 3) **Workspace** - Default `~/clawd` (configurable).