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**
- [ ] 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).
- [ ] 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.
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
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.
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
(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`.
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)
- set `models.mode: "replace"` to overwrite the file contents

2
docs/docker.md
View File

@@ -68,7 +68,7 @@ pnpm test:docker:qr
### Notes
- 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)

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
```
**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?
@@ -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:
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`
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)
- OAuth credentials: `~/.clawdbot/credentials/oauth.json`
- Auth profiles (OAuth + API keys): `~/.clawdbot/agent/auth-profiles.json`
- OAuth credentials (legacy import): `~/.clawdbot/credentials/oauth.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.

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

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

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
read_when: "You want multiple isolated agents (workspaces + auth) in one gateway process."
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`)
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)
@@ -149,7 +149,7 @@ 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/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)
### 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)
**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
```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:
@@ -130,13 +130,13 @@ lsof -i :18789
**Restart the tunnel:**
```bash
launchctl restart com.clawdbot.ssh-tunnel
launchctl kickstart -k gui/$UID/com.clawdbot.ssh-tunnel
```
**Stop the tunnel:**
```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
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
5. **Update rules:** Add to your security prompt

5
docs/setup.md
View File

@@ -77,7 +77,7 @@ pnpm install
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
@@ -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.
- **Where state lives:**
- Credentials: `~/.clawdbot/credentials/`
- Sessions/logs: `~/.clawdbot/sessions/`
- Sessions: `~/.clawdbot/agents/<agentId>/sessions/`
- Logs: `/tmp/clawdbot/`
## 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.
**Causes:**
- User sent `stop`, `abort`, `esc`, or `exit`
- User sent `stop`, `abort`, `esc`, `wait`, or `exit`
- Timeout exceeded
- 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?
```bash
ls -la ~/.clawdbot/sessions/
ls -la ~/.clawdbot/agents/<agentId>/sessions/
```
**Check 2:** Is `idleMinutes` too short?
@@ -188,7 +188,7 @@ clawdbot login --verbose
| Log | Location |
|-----|----------|
| Main logs (default) | `/tmp/clawdbot/clawdbot-YYYY-MM-DD.log` |
| Session files | `~/.clawdbot/sessions/` |
| Session files | `~/.clawdbot/agents/<agentId>/sessions/` |
| Media cache | `~/.clawdbot/media/` |
| 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.
- **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/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**
- Default `~/clawd` (configurable).
@@ -156,8 +156,8 @@ Typical fields in `~/.clawdbot/clawdbot.json`:
- `wizard.lastRunCommand`
- `wizard.lastRunMode`
WhatsApp credentials go to `~/.clawdbot/credentials/`.
Sessions are stored under `~/.clawdbot/sessions/`.
WhatsApp credentials go under `~/.clawdbot/credentials/whatsapp/<accountId>/`.
Sessions are stored under `~/.clawdbot/agents/<agentId>/sessions/`.
## Related docs