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

docs: correct paths and setup guidance

Browse Source
This commit is contained in:
Peter Steinberger
2026-01-06 21:29:41 +00:00
parent de454fc385
commit 4198fcd7db
16 changed files with 33 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/RELEASING.md
View File

@@ -13,7 +13,7 @@ Use `pnpm` (Node 22+) from the repo root. Keep the working tree clean before tag
1) **Version & metadata** 1) **Version & metadata**
- [ ] Bump `package.json` version (e.g., `1.1.0`). - [ ] Bump `package.json` version (e.g., `1.1.0`).
- [ ] Update CLI/version strings: [`src/cli/program.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/cli/program.ts) and the Baileys user agent in [`src/provider-web.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/provider-web.ts). - [ ] Update CLI/version strings: [`src/cli/program.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/cli/program.ts) and the Baileys user agent in [`src/provider-web.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/provider-web.ts).
- [ ] Confirm package metadata (name, description, repository, keywords, license) and `bin` map points to [`dist/index.js`](https://github.com/clawdbot/clawdbot/blob/main/dist/index.js) for `clawdbot`. - [ ] Confirm package metadata (name, description, repository, keywords, license) and `bin` map points to [`dist/entry.js`](https://github.com/clawdbot/clawdbot/blob/main/dist/entry.js) for `clawdbot`.
- [ ] If dependencies changed, run `pnpm install` so `pnpm-lock.yaml` is current. - [ ] If dependencies changed, run `pnpm install` so `pnpm-lock.yaml` is current.
2) **Build & artifacts** 2) **Build & artifacts**

2
docs/agent.md
View File

@@ -74,7 +74,7 @@ Apply these notes **only** when the user is Peter Steinberger at steipete.
## Sessions ## Sessions
Session transcripts are stored as JSONL at: Session transcripts are stored as JSONL at:
- `~/.clawdbot/sessions/<SessionId>.jsonl` - `~/.clawdbot/agents/<agentId>/sessions/<SessionId>.jsonl`
The session ID is stable and chosen by CLAWDBOT. The session ID is stable and chosen by CLAWDBOT.
Legacy Pi/Tau session folders are **not** read. Legacy Pi/Tau session folders are **not** read.

4
docs/configuration.md
View File

@@ -933,11 +933,11 @@ URL is injected per session.
Clawdbot uses the **pi-coding-agent** model catalog. You can add custom providers Clawdbot uses the **pi-coding-agent** model catalog. You can add custom providers
(LiteLLM, local OpenAI-compatible servers, Anthropic proxies, etc.) by writing (LiteLLM, local OpenAI-compatible servers, Anthropic proxies, etc.) by writing
`~/.clawdbot/agent/models.json` or by defining the same schema inside your `~/.clawdbot/agents/<agentId>/agent/models.json` or by defining the same schema inside your
Clawdbot config under `models.providers`. Clawdbot config under `models.providers`.
When `models.providers` is present, Clawdbot writes/merges a `models.json` into When `models.providers` is present, Clawdbot writes/merges a `models.json` into
`~/.clawdbot/agent/` on startup: `~/.clawdbot/agents/<agentId>/agent/` on startup:
- default behavior: **merge** (keeps existing providers, overrides on name) - default behavior: **merge** (keeps existing providers, overrides on name)
- set `models.mode: "replace"` to overwrite the file contents - set `models.mode: "replace"` to overwrite the file contents

2
docs/docker.md
View File

@@ -68,7 +68,7 @@ pnpm test:docker:qr
### Notes ### Notes
- Gateway bind defaults to `lan` for container use. - Gateway bind defaults to `lan` for container use.
- The gateway container is the source of truth for sessions (`~/.clawdbot/sessions`). - The gateway container is the source of truth for sessions (`~/.clawdbot/agents/<agentId>/sessions/`).
## Per-session Agent Sandbox (host gateway + Docker tools) ## Per-session Agent Sandbox (host gateway + Docker tools)

4
docs/faq.md
View File

@@ -122,7 +122,7 @@ They're **separate billing**! An API key does NOT use your subscription.
pnpm clawdbot login pnpm clawdbot login
``` ```
**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. **If OAuth fails** (headless/container): Do OAuth on a normal machine, then copy `~/.clawdbot/agents/<agentId>/agent/auth-profiles.json` (and `auth.json` if present) to your server. Legacy installs can still import `~/.clawdbot/credentials/oauth.json` on first use.
### How are env vars loaded? ### How are env vars loaded?
@@ -152,7 +152,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: OAuth needs the callback to reach the machine running the CLI. Options:
1. **Copy auth manually** — Run OAuth on your laptop, copy `~/.clawdbot/credentials/oauth.json` to the container. 1. **Copy auth manually** — Run OAuth on your laptop, copy `~/.clawdbot/agents/<agentId>/agent/auth-profiles.json` (and `auth.json` if present) to the container. Legacy flow: copy `~/.clawdbot/credentials/oauth.json` to trigger import.
2. **SSH tunnel** — `ssh -L 18789:localhost:18789 user@server` 2. **SSH tunnel** — `ssh -L 18789:localhost:18789 user@server`
3. **Tailscale** — Put both machines on your tailnet. 3. **Tailscale** — Put both machines on your tailnet.

4
docs/getting-started.md
View File

@@ -69,8 +69,8 @@ Wizard doc: https://docs.clawd.bot/wizard
### Auth: where it lives (important) ### Auth: where it lives (important)
- OAuth credentials: `~/.clawdbot/credentials/oauth.json` - OAuth credentials (legacy import): `~/.clawdbot/credentials/oauth.json`
- Auth profiles (OAuth + API keys): `~/.clawdbot/agent/auth-profiles.json` - Auth profiles (OAuth + API keys): `~/.clawdbot/agents/<agentId>/agent/auth-profiles.json`
Headless/server tip: do OAuth on a normal machine first, then copy `oauth.json` to the gateway host. Headless/server tip: do OAuth on a normal machine first, then copy `oauth.json` to the gateway host.

2
docs/mac/dev-setup.md
View File

@@ -57,7 +57,7 @@ The macOS app requires a symlink named `clawdbot` in `/usr/local/bin` or `/opt/h
Alternatively, you can manually link it from your Admin account: Alternatively, you can manually link it from your Admin account:
```bash ```bash
sudo ln -sf "/Users/$(whoami)/clawdbot/dist/Clawdbot.app/Contents/Resources/Relay/clawdbot" /usr/local/bin/clawdbot sudo ln -sf "/Users/$(whoami)/Projects/clawdbot/dist/Clawdbot.app/Contents/Resources/Relay/clawdbot" /usr/local/bin/clawdbot
``` ```
## Troubleshooting ## Troubleshooting

4
docs/model-failover.md
View File

@@ -17,7 +17,7 @@ This doc explains the runtime rules and the data that backs them.
Clawdbot uses **auth profiles** for both API keys and OAuth tokens. Clawdbot uses **auth profiles** for both API keys and OAuth tokens.
- Secrets live in `~/.clawdbot/agent/auth-profiles.json` (default agent; multi-agent stores under `~/.clawdbot/agents/<agentId>/agent/auth-profiles.json`). - Secrets live in `~/.clawdbot/agents/<agentId>/agent/auth-profiles.json` (legacy: `~/.clawdbot/agent/auth-profiles.json`).
- Config `auth.profiles` / `auth.order` are **metadata + routing only** (no secrets). - Config `auth.profiles` / `auth.order` are **metadata + routing only** (no secrets).
- Legacy import-only OAuth file: `~/.clawdbot/credentials/oauth.json` (imported into `auth-profiles.json` on first use). - Legacy import-only OAuth file: `~/.clawdbot/credentials/oauth.json` (imported into `auth-profiles.json` on first use).
@@ -31,7 +31,7 @@ OAuth logins create distinct profiles so multiple accounts can coexist.
- Default: `provider:default` when no email is available. - Default: `provider:default` when no email is available.
- OAuth with email: `provider:<email>` (for example `google-antigravity:user@gmail.com`). - OAuth with email: `provider:<email>` (for example `google-antigravity:user@gmail.com`).
Profiles live in `~/.clawdbot/agent/auth-profiles.json` under `profiles`. Profiles live in `~/.clawdbot/agents/<agentId>/agent/auth-profiles.json` under `profiles`.
## Rotation order ## Rotation order

1
docs/multi-agent.md
View File

@@ -1,4 +1,5 @@
--- ---
summary: "Multi-agent routing: isolated agents, provider accounts, and bindings"
title: Multi-Agent Routing title: Multi-Agent Routing
read_when: "You want multiple isolated agents (workspaces + auth) in one gateway process." read_when: "You want multiple isolated agents (workspaces + auth) in one gateway process."
status: active status: active

4
docs/onboarding.md
View File

@@ -41,7 +41,7 @@ The macOS app should:
- `~/.clawdbot/credentials/oauth.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 OAuth store. Why this location matters: it’s the Clawdbot-owned OAuth store.
Clawdbot also imports `oauth.json` into the agent auth profile store (`~/.clawdbot/agent/auth-profiles.json`) on first use. Clawdbot also imports `oauth.json` into the agent auth profile store (`~/.clawdbot/agents/<agentId>/agent/auth-profiles.json`) on first use.
### Recommended: OAuth (OpenAI Codex) ### Recommended: OAuth (OpenAI Codex)
@@ -149,7 +149,7 @@ If the Gateway runs on another machine, OAuth credentials must be created/stored
For now, remote onboarding should: For now, remote onboarding should:
- explain why OAuth isn't shown - explain why OAuth isn't shown
- point the user at the credential location (`~/.clawdbot/credentials/oauth.json`) and the auth profile store (`~/.clawdbot/agent/auth-profiles.json`) on the gateway host - point the user at the credential location (`~/.clawdbot/credentials/oauth.json`) and the auth profile store (`~/.clawdbot/agents/<agentId>/agent/auth-profiles.json`) on the gateway host
- mention that the **bootstrap ritual happens on the gateway host** (same BOOTSTRAP/IDENTITY/USER files) - mention that the **bootstrap ritual happens on the gateway host** (same BOOTSTRAP/IDENTITY/USER files)
### Manual credential setup ### Manual credential setup

5
docs/plans/group-policy-hardening.md
View File

@@ -1,3 +1,8 @@
---
summary: "Spec: groupPolicy hardening for Telegram allowlist parity"
read_when:
- Reviewing historical Telegram allowlist normalization changes
---
# Engineering Execution Spec: groupPolicy Hardening (Telegram Allowlist Parity) # Engineering Execution Spec: groupPolicy Hardening (Telegram Allowlist Parity)
**Date**: 2026-01-05 **Date**: 2026-01-05

6
docs/remote-gateway-readme.md
View File

@@ -108,7 +108,7 @@ Save this as `~/Library/LaunchAgents/com.clawdbot.ssh-tunnel.plist`:
### Load the Launch Agent ### Load the Launch Agent
```bash ```bash
launchctl load ~/Library/LaunchAgents/com.clawdbot.ssh-tunnel.plist launchctl bootstrap gui/$UID ~/Library/LaunchAgents/com.clawdbot.ssh-tunnel.plist
``` ```
The tunnel will now: The tunnel will now:
@@ -130,13 +130,13 @@ lsof -i :18789
**Restart the tunnel:** **Restart the tunnel:**
```bash ```bash
launchctl restart com.clawdbot.ssh-tunnel launchctl kickstart -k gui/$UID/com.clawdbot.ssh-tunnel
``` ```
**Stop the tunnel:** **Stop the tunnel:**
```bash ```bash
launchctl unload ~/Library/LaunchAgents/com.clawdbot.ssh-tunnel.plist launchctl bootout gui/$UID/com.clawdbot.ssh-tunnel
``` ```
--- ---

2
docs/security.md
View File

@@ -162,7 +162,7 @@ If your AI does something bad:
1. **Stop it:** stop the macOS app (if it’s supervising the Gateway) or terminate your `clawdbot gateway` process 1. **Stop it:** stop the macOS app (if it’s supervising the Gateway) or terminate your `clawdbot gateway` process
2. **Check logs:** `/tmp/clawdbot/clawdbot-YYYY-MM-DD.log` (or your configured `logging.file`) 2. **Check logs:** `/tmp/clawdbot/clawdbot-YYYY-MM-DD.log` (or your configured `logging.file`)
3. **Review session:** Check `~/.clawdbot/sessions/` for what happened 3. **Review session:** Check `~/.clawdbot/agents/<agentId>/sessions/` for what happened
4. **Rotate secrets:** If credentials were exposed 4. **Rotate secrets:** If credentials were exposed
5. **Update rules:** Add to your security prompt 5. **Update rules:** Add to your security prompt

5
docs/setup.md
View File

@@ -77,7 +77,7 @@ pnpm install
pnpm gateway:watch pnpm gateway:watch
``` ```
`gateway:watch` runs `src/index.ts gateway --force` and reloads on [`src/**/*.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/**/*.ts) changes. `gateway:watch` runs `src/entry.ts gateway --force` and reloads on [`src/**/*.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/**/*.ts) changes.
### 2) Point the macOS app at your running Gateway ### 2) Point the macOS app at your running Gateway
@@ -102,7 +102,8 @@ pnpm clawdbot health
- **Wrong port:** Gateway WS defaults to `ws://127.0.0.1:18789`; keep app + CLI on the same port. - **Wrong port:** Gateway WS defaults to `ws://127.0.0.1:18789`; keep app + CLI on the same port.
- **Where state lives:** - **Where state lives:**
- Credentials: `~/.clawdbot/credentials/` - Credentials: `~/.clawdbot/credentials/`
- Sessions/logs: `~/.clawdbot/sessions/` - Sessions: `~/.clawdbot/agents/<agentId>/sessions/`
- Logs: `/tmp/clawdbot/`
## Updating (without wrecking your setup) ## Updating (without wrecking your setup)

6
docs/troubleshooting.md
View File

@@ -14,7 +14,7 @@ When your CLAWDBOT misbehaves, here's how to fix it.
The agent was interrupted mid-response. The agent was interrupted mid-response.
**Causes:** **Causes:**
- User sent `stop`, `abort`, `esc`, or `exit` - User sent `stop`, `abort`, `esc`, `wait`, or `exit`
- Timeout exceeded - Timeout exceeded
- Process crashed - Process crashed
@@ -50,7 +50,7 @@ Known issue: When you send an image with ONLY a mention (no other text), WhatsAp
**Check 1:** Is the session file there? **Check 1:** Is the session file there?
```bash ```bash
ls -la ~/.clawdbot/sessions/ ls -la ~/.clawdbot/agents/<agentId>/sessions/
``` ```
**Check 2:** Is `idleMinutes` too short? **Check 2:** Is `idleMinutes` too short?
@@ -188,7 +188,7 @@ clawdbot login --verbose
| Log | Location | | Log | Location |
|-----|----------| |-----|----------|
| Main logs (default) | `/tmp/clawdbot/clawdbot-YYYY-MM-DD.log` | | Main logs (default) | `/tmp/clawdbot/clawdbot-YYYY-MM-DD.log` |
| Session files | `~/.clawdbot/sessions/` | | Session files | `~/.clawdbot/agents/<agentId>/sessions/` |
| Media cache | `~/.clawdbot/media/` | | Media cache | `~/.clawdbot/media/` |
| Credentials | `~/.clawdbot/credentials/` | | Credentials | `~/.clawdbot/credentials/` |

6
docs/wizard.md
View File

@@ -54,7 +54,7 @@ It does **not** install or change anything on the remote host.
- **Minimax M2.1 (LM Studio)**: config is auto‑written for the LM Studio endpoint. - **Minimax M2.1 (LM Studio)**: config is auto‑written for the LM Studio endpoint.
- **Skip**: no auth configured yet. - **Skip**: no auth configured yet.
- Wizard runs a model check and warns if the configured model is unknown or missing auth. - 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/agent/auth-profiles.json` (API keys + OAuth). - OAuth credentials live in `~/.clawdbot/credentials/oauth.json`; auth profiles live in `~/.clawdbot/agents/<agentId>/agent/auth-profiles.json` (API keys + OAuth).
3) **Workspace** 3) **Workspace**
- Default `~/clawd` (configurable). - Default `~/clawd` (configurable).
@@ -156,8 +156,8 @@ Typical fields in `~/.clawdbot/clawdbot.json`:
- `wizard.lastRunCommand` - `wizard.lastRunCommand`
- `wizard.lastRunMode` - `wizard.lastRunMode`
WhatsApp credentials go to `~/.clawdbot/credentials/`. WhatsApp credentials go under `~/.clawdbot/credentials/whatsapp/<accountId>/`.
Sessions are stored under `~/.clawdbot/sessions/`. Sessions are stored under `~/.clawdbot/agents/<agentId>/sessions/`.
## Related docs ## Related docs