let5see/clawdbot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: fix oauth path references

Browse Source
This commit is contained in:
Peter Steinberger
2026-01-05 21:53:37 +01:00
parent 872f30fee0
commit 1e9d7e0d79
4 changed files with 24 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
docs/configuration.md
View File

@@ -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`

8
docs/faq.md
View File

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

20
docs/onboarding.md
View File

@@ -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 |

2
docs/wizard.md
View File

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