refactor: rename clawdbot to moltbot with legacy compat
This commit is contained in:
Peter Steinberger
@@ -6,7 +6,7 @@ read_when:
|
||||
---
|
||||
# Authentication
|
||||
|
||||
Clawdbot supports OAuth and API keys for model providers. For Anthropic
|
||||
Moltbot supports OAuth and API keys for model providers. For Anthropic
|
||||
accounts, we recommend using an **API key**. For Claude subscription access,
|
||||
use the long‑lived token created by `claude setup-token`.
|
||||
|
||||
@@ -18,11 +18,11 @@ layout.
|
||||
If you’re using Anthropic directly, use an API key.
|
||||
|
||||
1) Create an API key in the Anthropic Console.
|
||||
2) Put it on the **gateway host** (the machine running `clawdbot gateway`).
|
||||
2) Put it on the **gateway host** (the machine running `moltbot gateway`).
|
||||
|
||||
```bash
|
||||
export ANTHROPIC_API_KEY="..."
|
||||
clawdbot models status
|
||||
moltbot models status
|
||||
```
|
||||
|
||||
3) If the Gateway runs under systemd/launchd, prefer putting the key in
|
||||
@@ -37,12 +37,12 @@ EOF
|
||||
Then restart the daemon (or restart your Gateway process) and re-check:
|
||||
|
||||
```bash
|
||||
clawdbot models status
|
||||
clawdbot doctor
|
||||
moltbot models status
|
||||
moltbot doctor
|
||||
```
|
||||
|
||||
If you’d rather not manage env vars yourself, the onboarding wizard can store
|
||||
API keys for daemon use: `clawdbot onboard`.
|
||||
API keys for daemon use: `moltbot onboard`.
|
||||
|
||||
See [Help](/help) for details on env inheritance (`env.shellEnv`,
|
||||
`~/.clawdbot/.env`, systemd/launchd).
|
||||
@@ -56,16 +56,16 @@ subscription, the setup-token flow is also supported. Run it on the **gateway ho
|
||||
claude setup-token
|
||||
```
|
||||
|
||||
Then paste it into Clawdbot:
|
||||
Then paste it into Moltbot:
|
||||
|
||||
```bash
|
||||
clawdbot models auth setup-token --provider anthropic
|
||||
moltbot models auth setup-token --provider anthropic
|
||||
```
|
||||
|
||||
If the token was created on another machine, paste it manually:
|
||||
|
||||
```bash
|
||||
clawdbot models auth paste-token --provider anthropic
|
||||
moltbot models auth paste-token --provider anthropic
|
||||
```
|
||||
|
||||
If you see an Anthropic error like:
|
||||
@@ -79,14 +79,14 @@ This credential is only authorized for use with Claude Code and cannot be used f
|
||||
Manual token entry (any provider; writes `auth-profiles.json` + updates config):
|
||||
|
||||
```bash
|
||||
clawdbot models auth paste-token --provider anthropic
|
||||
clawdbot models auth paste-token --provider openrouter
|
||||
moltbot models auth paste-token --provider anthropic
|
||||
moltbot models auth paste-token --provider openrouter
|
||||
```
|
||||
|
||||
Automation-friendly check (exit `1` when expired/missing, `2` when expiring):
|
||||
|
||||
```bash
|
||||
clawdbot models status --check
|
||||
moltbot models status --check
|
||||
```
|
||||
|
||||
Optional ops scripts (systemd/Termux) are documented here:
|
||||
@@ -97,8 +97,8 @@ Optional ops scripts (systemd/Termux) are documented here:
|
||||
## Checking model auth status
|
||||
|
||||
```bash
|
||||
clawdbot models status
|
||||
clawdbot doctor
|
||||
moltbot models status
|
||||
moltbot doctor
|
||||
```
|
||||
|
||||
## Controlling which credential is used
|
||||
@@ -114,9 +114,9 @@ Use `/model` (or `/model list`) for a compact picker; use `/model status` for th
|
||||
Set an explicit auth profile order override for an agent (stored in that agent’s `auth-profiles.json`):
|
||||
|
||||
```bash
|
||||
clawdbot models auth order get --provider anthropic
|
||||
clawdbot models auth order set --provider anthropic anthropic:default
|
||||
clawdbot models auth order clear --provider anthropic
|
||||
moltbot models auth order get --provider anthropic
|
||||
moltbot models auth order set --provider anthropic anthropic:default
|
||||
moltbot models auth order clear --provider anthropic
|
||||
```
|
||||
|
||||
Use `--agent <id>` to target a specific agent; omit it to use the configured default agent.
|
||||
@@ -129,12 +129,12 @@ If the Anthropic token profile is missing, run `claude setup-token` on the
|
||||
**gateway host**, then re-check:
|
||||
|
||||
```bash
|
||||
clawdbot models status
|
||||
moltbot models status
|
||||
```
|
||||
|
||||
### Token expiring/expired
|
||||
|
||||
Run `clawdbot models status` to confirm which profile is expiring. If the profile
|
||||
Run `moltbot models status` to confirm which profile is expiring. If the profile
|
||||
is missing, rerun `claude setup-token` and paste the token again.
|
||||
|
||||
## Requirements
|
||||
|
||||
@@ -7,7 +7,7 @@ read_when:
|
||||
|
||||
# Background Exec + Process Tool
|
||||
|
||||
Clawdbot runs shell commands through the `exec` tool and keeps long‑running tasks in memory. The `process` tool manages those background sessions.
|
||||
Moltbot runs shell commands through the `exec` tool and keeps long‑running tasks in memory. The `process` tool manages those background sessions.
|
||||
|
||||
## exec tool
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@ read_when:
|
||||
---
|
||||
# Bonjour / mDNS discovery
|
||||
|
||||
Clawdbot uses Bonjour (mDNS / DNS‑SD) as a **LAN‑only convenience** to discover
|
||||
Moltbot uses Bonjour (mDNS / DNS‑SD) as a **LAN‑only convenience** to discover
|
||||
an active Gateway (WebSocket endpoint). It is best‑effort and does **not** replace SSH or
|
||||
Tailnet-based connectivity.
|
||||
|
||||
@@ -19,38 +19,38 @@ boundary. You can keep the same discovery UX by switching to **unicast DNS‑SD*
|
||||
High‑level steps:
|
||||
|
||||
1) Run a DNS server on the gateway host (reachable over Tailnet).
|
||||
2) Publish DNS‑SD records for `_clawdbot-gw._tcp` under a dedicated zone
|
||||
(example: `clawdbot.internal.`).
|
||||
3) Configure Tailscale **split DNS** so `clawdbot.internal` resolves via that
|
||||
2) Publish DNS‑SD records for `_moltbot-gw._tcp` under a dedicated zone
|
||||
(example: `moltbot.internal.`).
|
||||
3) Configure Tailscale **split DNS** so `moltbot.internal` resolves via that
|
||||
DNS server for clients (including iOS).
|
||||
|
||||
Clawdbot standardizes on `clawdbot.internal.` for this mode. iOS/Android nodes
|
||||
browse both `local.` and `clawdbot.internal.` automatically.
|
||||
Moltbot standardizes on `moltbot.internal.` for this mode. iOS/Android nodes
|
||||
browse both `local.` and `moltbot.internal.` automatically.
|
||||
|
||||
### Gateway config (recommended)
|
||||
|
||||
```json5
|
||||
{
|
||||
gateway: { bind: "tailnet" }, // tailnet-only (recommended)
|
||||
discovery: { wideArea: { enabled: true } } // enables clawdbot.internal DNS-SD publishing
|
||||
discovery: { wideArea: { enabled: true } } // enables moltbot.internal DNS-SD publishing
|
||||
}
|
||||
```
|
||||
|
||||
### One‑time DNS server setup (gateway host)
|
||||
|
||||
```bash
|
||||
clawdbot dns setup --apply
|
||||
moltbot dns setup --apply
|
||||
```
|
||||
|
||||
This installs CoreDNS and configures it to:
|
||||
- listen on port 53 only on the gateway’s Tailscale interfaces
|
||||
- serve `clawdbot.internal.` from `~/.clawdbot/dns/clawdbot.internal.db`
|
||||
- serve `moltbot.internal.` from `~/.clawdbot/dns/moltbot.internal.db`
|
||||
|
||||
Validate from a tailnet‑connected machine:
|
||||
|
||||
```bash
|
||||
dns-sd -B _clawdbot-gw._tcp clawdbot.internal.
|
||||
dig @<TAILNET_IPV4> -p 53 _clawdbot-gw._tcp.clawdbot.internal PTR +short
|
||||
dns-sd -B _moltbot-gw._tcp moltbot.internal.
|
||||
dig @<TAILNET_IPV4> -p 53 _moltbot-gw._tcp.clawdbot.internal PTR +short
|
||||
```
|
||||
|
||||
### Tailscale DNS settings
|
||||
@@ -58,10 +58,10 @@ dig @<TAILNET_IPV4> -p 53 _clawdbot-gw._tcp.clawdbot.internal PTR +short
|
||||
In the Tailscale admin console:
|
||||
|
||||
- Add a nameserver pointing at the gateway’s tailnet IP (UDP/TCP 53).
|
||||
- Add split DNS so the domain `clawdbot.internal` uses that nameserver.
|
||||
- Add split DNS so the domain `moltbot.internal` uses that nameserver.
|
||||
|
||||
Once clients accept tailnet DNS, iOS nodes can browse
|
||||
`_clawdbot-gw._tcp` in `clawdbot.internal.` without multicast.
|
||||
`_moltbot-gw._tcp` in `moltbot.internal.` without multicast.
|
||||
|
||||
### Gateway listener security (recommended)
|
||||
|
||||
@@ -69,16 +69,16 @@ The Gateway WS port (default `18789`) binds to loopback by default. For LAN/tail
|
||||
access, bind explicitly and keep auth enabled.
|
||||
|
||||
For tailnet‑only setups:
|
||||
- Set `gateway.bind: "tailnet"` in `~/.clawdbot/clawdbot.json`.
|
||||
- Set `gateway.bind: "tailnet"` in `~/.clawdbot/moltbot.json`.
|
||||
- Restart the Gateway (or restart the macOS menubar app).
|
||||
|
||||
## What advertises
|
||||
|
||||
Only the Gateway advertises `_clawdbot-gw._tcp`.
|
||||
Only the Gateway advertises `_moltbot-gw._tcp`.
|
||||
|
||||
## Service types
|
||||
|
||||
- `_clawdbot-gw._tcp` — gateway transport beacon (used by macOS/iOS/Android nodes).
|
||||
- `_moltbot-gw._tcp` — gateway transport beacon (used by macOS/iOS/Android nodes).
|
||||
|
||||
## TXT keys (non‑secret hints)
|
||||
|
||||
@@ -93,7 +93,7 @@ The Gateway advertises small non‑secret hints to make UI flows convenient:
|
||||
- `canvasPort=<port>` (only when the canvas host is enabled; default `18793`)
|
||||
- `sshPort=<port>` (defaults to 22 when not overridden)
|
||||
- `transport=gateway`
|
||||
- `cliPath=<path>` (optional; absolute path to a runnable `clawdbot` entrypoint)
|
||||
- `cliPath=<path>` (optional; absolute path to a runnable `moltbot` entrypoint)
|
||||
- `tailnetDns=<magicdns>` (optional hint when Tailnet is available)
|
||||
|
||||
## Debugging on macOS
|
||||
@@ -102,11 +102,11 @@ Useful built‑in tools:
|
||||
|
||||
- Browse instances:
|
||||
```bash
|
||||
dns-sd -B _clawdbot-gw._tcp local.
|
||||
dns-sd -B _moltbot-gw._tcp local.
|
||||
```
|
||||
- Resolve one instance (replace `<instance>`):
|
||||
```bash
|
||||
dns-sd -L "<instance>" _clawdbot-gw._tcp local.
|
||||
dns-sd -L "<instance>" _moltbot-gw._tcp local.
|
||||
```
|
||||
|
||||
If browsing works but resolving fails, you’re usually hitting a LAN policy or
|
||||
@@ -123,7 +123,7 @@ The Gateway writes a rolling log file (printed on startup as
|
||||
|
||||
## Debugging on iOS node
|
||||
|
||||
The iOS node uses `NWBrowser` to discover `_clawdbot-gw._tcp`.
|
||||
The iOS node uses `NWBrowser` to discover `_moltbot-gw._tcp`.
|
||||
|
||||
To capture logs:
|
||||
- Settings → Gateway → Advanced → **Discovery Debug Logs**
|
||||
@@ -151,7 +151,7 @@ sequences (e.g. spaces become `\032`).
|
||||
## Disabling / configuration
|
||||
|
||||
- `CLAWDBOT_DISABLE_BONJOUR=1` disables advertising.
|
||||
- `gateway.bind` in `~/.clawdbot/clawdbot.json` controls the Gateway bind mode.
|
||||
- `gateway.bind` in `~/.clawdbot/moltbot.json` controls the Gateway bind mode.
|
||||
- `CLAWDBOT_SSH_PORT` overrides the SSH port advertised in TXT.
|
||||
- `CLAWDBOT_TAILNET_DNS` publishes a MagicDNS hint in TXT.
|
||||
- `CLAWDBOT_CLI_PATH` overrides the advertised CLI path.
|
||||
|
||||
@@ -14,7 +14,7 @@ should use the unified Gateway WebSocket protocol instead.
|
||||
If you are building an operator or node client, use the
|
||||
[Gateway protocol](/gateway/protocol).
|
||||
|
||||
**Note:** Current Clawdbot builds no longer ship the TCP bridge listener; this document is kept for historical reference.
|
||||
**Note:** Current Moltbot builds no longer ship the TCP bridge listener; this document is kept for historical reference.
|
||||
Legacy `bridge.*` config keys are no longer part of the config schema.
|
||||
|
||||
## Why we have both
|
||||
@@ -74,7 +74,7 @@ Payload fields (all optional unless noted):
|
||||
## Tailnet usage
|
||||
|
||||
- Bind the bridge to a tailnet IP: `bridge.bind: "tailnet"` in
|
||||
`~/.clawdbot/clawdbot.json`.
|
||||
`~/.clawdbot/moltbot.json`.
|
||||
- Clients connect via MagicDNS name or tailnet IP.
|
||||
- Bonjour does **not** cross networks; use manual host/port or wide-area DNS‑SD
|
||||
when needed.
|
||||
|
||||
@@ -7,7 +7,7 @@ read_when:
|
||||
---
|
||||
# CLI backends (fallback runtime)
|
||||
|
||||
Clawdbot can run **local AI CLIs** as a **text-only fallback** when API providers are down,
|
||||
Moltbot can run **local AI CLIs** as a **text-only fallback** when API providers are down,
|
||||
rate-limited, or temporarily misbehaving. This is intentionally conservative:
|
||||
|
||||
- **Tools are disabled** (no tool calls).
|
||||
@@ -20,16 +20,16 @@ want “always works” text responses without relying on external APIs.
|
||||
|
||||
## Beginner-friendly quick start
|
||||
|
||||
You can use Claude Code CLI **without any config** (Clawdbot ships a built-in default):
|
||||
You can use Claude Code CLI **without any config** (Moltbot ships a built-in default):
|
||||
|
||||
```bash
|
||||
clawdbot agent --message "hi" --model claude-cli/opus-4.5
|
||||
moltbot agent --message "hi" --model claude-cli/opus-4.5
|
||||
```
|
||||
|
||||
Codex CLI also works out of the box:
|
||||
|
||||
```bash
|
||||
clawdbot agent --message "hi" --model codex-cli/gpt-5.2-codex
|
||||
moltbot agent --message "hi" --model codex-cli/gpt-5.2-codex
|
||||
```
|
||||
|
||||
If your gateway runs under launchd/systemd and PATH is minimal, add just the
|
||||
@@ -76,7 +76,7 @@ Add a CLI backend to your fallback list so it only runs when primary models fail
|
||||
|
||||
Notes:
|
||||
- If you use `agents.defaults.models` (allowlist), you must include `claude-cli/...`.
|
||||
- If the primary provider fails (auth, rate limits, timeouts), Clawdbot will
|
||||
- If the primary provider fails (auth, rate limits, timeouts), Moltbot will
|
||||
try the CLI backend next.
|
||||
|
||||
## Configuration overview
|
||||
@@ -132,7 +132,7 @@ The provider id becomes the left side of your model ref:
|
||||
## How it works
|
||||
|
||||
1) **Selects a backend** based on the provider prefix (`claude-cli/...`).
|
||||
2) **Builds a system prompt** using the same Clawdbot prompt + workspace context.
|
||||
2) **Builds a system prompt** using the same Moltbot prompt + workspace context.
|
||||
3) **Executes the CLI** with a session id (if supported) so history stays consistent.
|
||||
4) **Parses output** (JSON or plain text) and returns the final text.
|
||||
5) **Persists session ids** per backend, so follow-ups reuse the same CLI session.
|
||||
@@ -159,8 +159,8 @@ imageArg: "--image",
|
||||
imageMode: "repeat"
|
||||
```
|
||||
|
||||
Clawdbot will write base64 images to temp files. If `imageArg` is set, those
|
||||
paths are passed as CLI args. If `imageArg` is missing, Clawdbot appends the
|
||||
Moltbot will write base64 images to temp files. If `imageArg` is set, those
|
||||
paths are passed as CLI args. If `imageArg` is missing, Moltbot appends the
|
||||
file paths to the prompt (path injection), which is enough for CLIs that auto-
|
||||
load local files from plain paths (Claude Code CLI behavior).
|
||||
|
||||
@@ -178,7 +178,7 @@ Input modes:
|
||||
|
||||
## Defaults (built-in)
|
||||
|
||||
Clawdbot ships a default for `claude-cli`:
|
||||
Moltbot ships a default for `claude-cli`:
|
||||
|
||||
- `command: "claude"`
|
||||
- `args: ["-p", "--output-format", "json", "--dangerously-skip-permissions"]`
|
||||
@@ -189,7 +189,7 @@ Clawdbot ships a default for `claude-cli`:
|
||||
- `systemPromptWhen: "first"`
|
||||
- `sessionMode: "always"`
|
||||
|
||||
Clawdbot also ships a default for `codex-cli`:
|
||||
Moltbot also ships a default for `codex-cli`:
|
||||
|
||||
- `command: "codex"`
|
||||
- `args: ["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]`
|
||||
@@ -204,12 +204,12 @@ Override only if needed (common: absolute `command` path).
|
||||
|
||||
## Limitations
|
||||
|
||||
- **No Clawdbot tools** (the CLI backend never receives tool calls). Some CLIs
|
||||
- **No Moltbot tools** (the CLI backend never receives tool calls). Some CLIs
|
||||
may still run their own agent tooling.
|
||||
- **No streaming** (CLI output is collected then returned).
|
||||
- **Structured outputs** depend on the CLI’s JSON format.
|
||||
- **Codex CLI sessions** resume via text output (no JSONL), which is less
|
||||
structured than the initial `--json` run. Clawdbot sessions still work
|
||||
structured than the initial `--json` run. Moltbot sessions still work
|
||||
normally.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
---
|
||||
summary: "Schema-accurate configuration examples for common Clawdbot setups"
|
||||
summary: "Schema-accurate configuration examples for common Moltbot setups"
|
||||
read_when:
|
||||
- Learning how to configure Clawdbot
|
||||
- Learning how to configure Moltbot
|
||||
- Looking for configuration examples
|
||||
- Setting up Clawdbot for the first time
|
||||
- Setting up Moltbot for the first time
|
||||
---
|
||||
# Configuration Examples
|
||||
|
||||
@@ -19,7 +19,7 @@ Examples below are aligned with the current config schema. For the exhaustive re
|
||||
}
|
||||
```
|
||||
|
||||
Save to `~/.clawdbot/clawdbot.json` and you can DM the bot from that number.
|
||||
Save to `~/.clawdbot/moltbot.json` and you can DM the bot from that number.
|
||||
|
||||
### Recommended starter
|
||||
```json5
|
||||
@@ -85,7 +85,7 @@ Save to `~/.clawdbot/clawdbot.json` and you can DM the bot from that number.
|
||||
// Logging
|
||||
logging: {
|
||||
level: "info",
|
||||
file: "/tmp/clawdbot/clawdbot.log",
|
||||
file: "/tmp/moltbot/moltbot.log",
|
||||
consoleLevel: "info",
|
||||
consoleStyle: "pretty",
|
||||
redactSensitive: "tools"
|
||||
@@ -93,7 +93,7 @@ Save to `~/.clawdbot/clawdbot.json` and you can DM the bot from that number.
|
||||
|
||||
// Message formatting
|
||||
messages: {
|
||||
messagePrefix: "[clawdbot]",
|
||||
messagePrefix: "[moltbot]",
|
||||
responsePrefix: ">",
|
||||
ackReaction: "👀",
|
||||
ackReactionScope: "group-mentions"
|
||||
@@ -102,7 +102,7 @@ Save to `~/.clawdbot/clawdbot.json` and you can DM the bot from that number.
|
||||
// Routing + queue
|
||||
routing: {
|
||||
groupChat: {
|
||||
mentionPatterns: ["@clawd", "clawdbot"],
|
||||
mentionPatterns: ["@clawd", "moltbot"],
|
||||
historyLimit: 50
|
||||
},
|
||||
queue: {
|
||||
@@ -274,7 +274,7 @@ Save to `~/.clawdbot/clawdbot.json` and you can DM the bot from that number.
|
||||
perSession: true,
|
||||
workspaceRoot: "~/.clawdbot/sandboxes",
|
||||
docker: {
|
||||
image: "clawdbot-sandbox:bookworm-slim",
|
||||
image: "moltbot-sandbox:bookworm-slim",
|
||||
workdir: "/workspace",
|
||||
readOnlyRoot: true,
|
||||
tmpfs: ["/tmp", "/var/tmp", "/run"],
|
||||
@@ -369,7 +369,7 @@ Save to `~/.clawdbot/clawdbot.json` and you can DM the bot from that number.
|
||||
}
|
||||
],
|
||||
gmail: {
|
||||
account: "clawdbot@gmail.com",
|
||||
account: "moltbot@gmail.com",
|
||||
label: "INBOX",
|
||||
topic: "projects/<project-id>/topics/gog-gmail-watch",
|
||||
subscription: "gog-gmail-watch-push",
|
||||
@@ -388,7 +388,7 @@ Save to `~/.clawdbot/clawdbot.json` and you can DM the bot from that number.
|
||||
mode: "local",
|
||||
port: 18789,
|
||||
bind: "loopback",
|
||||
controlUi: { enabled: true, basePath: "/clawdbot" },
|
||||
controlUi: { enabled: true, basePath: "/moltbot" },
|
||||
auth: {
|
||||
mode: "token",
|
||||
token: "gateway-token",
|
||||
|
||||
@@ -1,13 +1,13 @@
|
||||
---
|
||||
summary: "All configuration options for ~/.clawdbot/clawdbot.json with examples"
|
||||
summary: "All configuration options for ~/.clawdbot/moltbot.json with examples"
|
||||
read_when:
|
||||
- Adding or modifying config fields
|
||||
---
|
||||
# Configuration 🔧
|
||||
|
||||
Clawdbot reads an optional **JSON5** config from `~/.clawdbot/clawdbot.json` (comments + trailing commas allowed).
|
||||
Moltbot reads an optional **JSON5** config from `~/.clawdbot/moltbot.json` (comments + trailing commas allowed).
|
||||
|
||||
If the file is missing, Clawdbot uses safe-ish defaults (embedded Pi agent + per-sender sessions + workspace `~/clawd`). You usually only need a config to:
|
||||
If the file is missing, Moltbot uses safe-ish defaults (embedded Pi agent + per-sender sessions + workspace `~/clawd`). You usually only need a config to:
|
||||
- restrict who can trigger the bot (`channels.whatsapp.allowFrom`, `channels.telegram.allowFrom`, etc.)
|
||||
- control group allowlists + mention behavior (`channels.whatsapp.groups`, `channels.telegram.groups`, `channels.discord.guilds`, `agents.list[].groupChat`)
|
||||
- customize message prefixes (`messages`)
|
||||
@@ -19,14 +19,14 @@ If the file is missing, Clawdbot uses safe-ish defaults (embedded Pi agent + per
|
||||
|
||||
## Strict config validation
|
||||
|
||||
Clawdbot only accepts configurations that fully match the schema.
|
||||
Moltbot only accepts configurations that fully match the schema.
|
||||
Unknown keys, malformed types, or invalid values cause the Gateway to **refuse to start** for safety.
|
||||
|
||||
When validation fails:
|
||||
- The Gateway does not boot.
|
||||
- Only diagnostic commands are allowed (for example: `clawdbot doctor`, `clawdbot logs`, `clawdbot health`, `clawdbot status`, `clawdbot service`, `clawdbot help`).
|
||||
- Run `clawdbot doctor` to see the exact issues.
|
||||
- Run `clawdbot doctor --fix` (or `--yes`) to apply migrations/repairs.
|
||||
- Only diagnostic commands are allowed (for example: `moltbot doctor`, `moltbot logs`, `moltbot health`, `moltbot status`, `moltbot service`, `moltbot help`).
|
||||
- Run `moltbot doctor` to see the exact issues.
|
||||
- Run `moltbot doctor --fix` (or `--yes`) to apply migrations/repairs.
|
||||
|
||||
Doctor never writes changes unless you explicitly opt into `--fix`/`--yes`.
|
||||
|
||||
@@ -47,7 +47,7 @@ Use `config.apply` to validate + write the full config and restart the Gateway i
|
||||
It writes a restart sentinel and pings the last active session after the Gateway comes back.
|
||||
|
||||
Warning: `config.apply` replaces the **entire config**. If you want to change only a few keys,
|
||||
use `config.patch` or `clawdbot config set`. Keep a backup of `~/.clawdbot/clawdbot.json`.
|
||||
use `config.patch` or `moltbot config set`. Keep a backup of `~/.clawdbot/moltbot.json`.
|
||||
|
||||
Params:
|
||||
- `raw` (string) — JSON5 payload for the entire config
|
||||
@@ -59,8 +59,8 @@ Params:
|
||||
Example (via `gateway call`):
|
||||
|
||||
```bash
|
||||
clawdbot gateway call config.get --params '{}' # capture payload.hash
|
||||
clawdbot gateway call config.apply --params '{
|
||||
moltbot gateway call config.get --params '{}' # capture payload.hash
|
||||
moltbot gateway call config.apply --params '{
|
||||
"raw": "{\\n agents: { defaults: { workspace: \\"~/clawd\\" } }\\n}\\n",
|
||||
"baseHash": "<hash-from-config.get>",
|
||||
"sessionKey": "agent:main:whatsapp:dm:+15555550123",
|
||||
@@ -88,8 +88,8 @@ Params:
|
||||
Example:
|
||||
|
||||
```bash
|
||||
clawdbot gateway call config.get --params '{}' # capture payload.hash
|
||||
clawdbot gateway call config.patch --params '{
|
||||
moltbot gateway call config.get --params '{}' # capture payload.hash
|
||||
moltbot gateway call config.patch --params '{
|
||||
"raw": "{\\n channels: { telegram: { groups: { \\"*\\": { requireMention: false } } } }\\n}\\n",
|
||||
"baseHash": "<hash-from-config.get>",
|
||||
"sessionKey": "agent:main:whatsapp:dm:+15555550123",
|
||||
@@ -146,7 +146,7 @@ Split your config into multiple files using the `$include` directive. This is us
|
||||
### Basic usage
|
||||
|
||||
```json5
|
||||
// ~/.clawdbot/clawdbot.json
|
||||
// ~/.clawdbot/moltbot.json
|
||||
{
|
||||
gateway: { port: 18789 },
|
||||
|
||||
@@ -208,7 +208,7 @@ Included files can themselves contain `$include` directives (up to 10 levels dee
|
||||
|
||||
```json5
|
||||
{ "$include": "./sub/config.json5" } // relative
|
||||
{ "$include": "/etc/clawdbot/base.json5" } // absolute
|
||||
{ "$include": "/etc/moltbot/base.json5" } // absolute
|
||||
{ "$include": "../shared/common.json5" } // parent dir
|
||||
```
|
||||
|
||||
@@ -221,7 +221,7 @@ Included files can themselves contain `$include` directives (up to 10 levels dee
|
||||
### Example: Multi-client legal setup
|
||||
|
||||
```json5
|
||||
// ~/.clawdbot/clawdbot.json
|
||||
// ~/.clawdbot/moltbot.json
|
||||
{
|
||||
gateway: { port: 18789, auth: { token: "secret" } },
|
||||
|
||||
@@ -266,7 +266,7 @@ Included files can themselves contain `$include` directives (up to 10 levels dee
|
||||
|
||||
### Env vars + `.env`
|
||||
|
||||
Clawdbot reads env vars from the parent process (shell, launchd/systemd, CI, etc.).
|
||||
Moltbot reads env vars from the parent process (shell, launchd/systemd, CI, etc.).
|
||||
|
||||
Additionally, it loads:
|
||||
- `.env` from the current working directory (if present)
|
||||
@@ -292,7 +292,7 @@ See [/environment](/environment) for full precedence and sources.
|
||||
|
||||
### `env.shellEnv` (optional)
|
||||
|
||||
Opt-in convenience: if enabled and none of the expected keys are set yet, Clawdbot runs your login shell and imports only the missing expected keys (never overrides).
|
||||
Opt-in convenience: if enabled and none of the expected keys are set yet, Moltbot runs your login shell and imports only the missing expected keys (never overrides).
|
||||
This effectively sources your shell profile.
|
||||
|
||||
```json5
|
||||
@@ -354,7 +354,7 @@ You can reference environment variables directly in any config string value usin
|
||||
|
||||
### Auth storage (OAuth + API keys)
|
||||
|
||||
Clawdbot stores **per-agent** auth profiles (OAuth + API keys) in:
|
||||
Moltbot stores **per-agent** auth profiles (OAuth + API keys) in:
|
||||
- `<agentDir>/auth-profiles.json` (default: `~/.clawdbot/agents/<agentId>/agent/auth-profiles.json`)
|
||||
|
||||
See also: [/concepts/oauth](/concepts/oauth)
|
||||
@@ -366,13 +366,13 @@ The embedded Pi agent maintains a runtime cache at:
|
||||
- `<agentDir>/auth.json` (managed automatically; don’t edit manually)
|
||||
|
||||
Legacy agent dir (pre multi-agent):
|
||||
- `~/.clawdbot/agent/*` (migrated by `clawdbot doctor` into `~/.clawdbot/agents/<defaultAgentId>/agent/*`)
|
||||
- `~/.clawdbot/agent/*` (migrated by `moltbot doctor` into `~/.clawdbot/agents/<defaultAgentId>/agent/*`)
|
||||
|
||||
Overrides:
|
||||
- OAuth dir (legacy import only): `CLAWDBOT_OAUTH_DIR`
|
||||
- Agent dir (default agent root override): `CLAWDBOT_AGENT_DIR` (preferred), `PI_CODING_AGENT_DIR` (legacy)
|
||||
|
||||
On first use, Clawdbot imports `oauth.json` entries into `auth-profiles.json`.
|
||||
On first use, Moltbot imports `oauth.json` entries into `auth-profiles.json`.
|
||||
|
||||
### `auth`
|
||||
|
||||
@@ -398,7 +398,7 @@ rotation order used for failover.
|
||||
|
||||
Optional per-agent identity used for defaults and UX. This is written by the macOS onboarding assistant.
|
||||
|
||||
If set, Clawdbot derives defaults (only when you haven’t set them explicitly):
|
||||
If set, Moltbot derives defaults (only when you haven’t set them explicitly):
|
||||
- `messages.ackReaction` from the **active agent**’s `identity.emoji` (falls back to 👀)
|
||||
- `agents.list[].groupChat.mentionPatterns` from the agent’s `identity.name`/`identity.emoji` (so “@Samantha” works in groups across Telegram/Slack/Discord/Google Chat/iMessage/WhatsApp)
|
||||
- `identity.avatar` accepts a workspace-relative image path or a remote URL/data URL. Local files must live inside the agent workspace.
|
||||
@@ -444,8 +444,8 @@ Metadata written by CLI wizards (`onboard`, `configure`, `doctor`).
|
||||
|
||||
### `logging`
|
||||
|
||||
- Default log file: `/tmp/clawdbot/clawdbot-YYYY-MM-DD.log`
|
||||
- If you want a stable path, set `logging.file` to `/tmp/clawdbot/clawdbot.log`.
|
||||
- Default log file: `/tmp/moltbot/moltbot-YYYY-MM-DD.log`
|
||||
- If you want a stable path, set `logging.file` to `/tmp/moltbot/moltbot.log`.
|
||||
- Console output can be tuned separately via:
|
||||
- `logging.consoleLevel` (defaults to `info`, bumps to `debug` when `--verbose`)
|
||||
- `logging.consoleStyle` (`pretty` | `compact` | `json`)
|
||||
@@ -457,7 +457,7 @@ Metadata written by CLI wizards (`onboard`, `configure`, `doctor`).
|
||||
{
|
||||
logging: {
|
||||
level: "info",
|
||||
file: "/tmp/clawdbot/clawdbot.log",
|
||||
file: "/tmp/moltbot/moltbot.log",
|
||||
consoleLevel: "info",
|
||||
consoleStyle: "pretty",
|
||||
redactSensitive: "tools",
|
||||
@@ -481,8 +481,8 @@ Controls how WhatsApp direct chats (DMs) are handled:
|
||||
Pairing codes expire after 1 hour; the bot only sends a pairing code when a new request is created. Pending DM pairing requests are capped at **3 per channel** by default.
|
||||
|
||||
Pairing approvals:
|
||||
- `clawdbot pairing list whatsapp`
|
||||
- `clawdbot pairing approve whatsapp <code>`
|
||||
- `moltbot pairing list whatsapp`
|
||||
- `moltbot pairing approve whatsapp <code>`
|
||||
|
||||
### `channels.whatsapp.allowFrom`
|
||||
|
||||
@@ -543,7 +543,7 @@ Run multiple WhatsApp accounts in one gateway:
|
||||
|
||||
Notes:
|
||||
- Outbound commands default to account `default` if present; otherwise the first configured account id (sorted).
|
||||
- The legacy single-account Baileys auth dir is migrated by `clawdbot doctor` into `whatsapp/default`.
|
||||
- The legacy single-account Baileys auth dir is migrated by `moltbot doctor` into `whatsapp/default`.
|
||||
|
||||
### `channels.telegram.accounts` / `channels.discord.accounts` / `channels.googlechat.accounts` / `channels.slack.accounts` / `channels.mattermost.accounts` / `channels.signal.accounts` / `channels.imessage.accounts`
|
||||
|
||||
@@ -590,7 +590,7 @@ Group messages default to **require mention** (either metadata mention or regex
|
||||
},
|
||||
agents: {
|
||||
list: [
|
||||
{ id: "main", groupChat: { mentionPatterns: ["@clawd", "clawdbot", "clawd"] } }
|
||||
{ id: "main", groupChat: { mentionPatterns: ["@clawd", "moltbot", "clawd"] } }
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -949,7 +949,7 @@ Notes:
|
||||
- `channels.telegram.customCommands` adds extra Telegram bot menu entries. Names are normalized; conflicts with native commands are ignored.
|
||||
- `commands.bash: true` enables `! <cmd>` to run host shell commands (`/bash <cmd>` also works as an alias). Requires `tools.elevated.enabled` and allowlisting the sender in `tools.elevated.allowFrom.<channel>`.
|
||||
- `commands.bashForegroundMs` controls how long bash waits before backgrounding. While a bash job is running, new `! <cmd>` requests are rejected (one at a time).
|
||||
- `commands.config: true` enables `/config` (reads/writes `clawdbot.json`).
|
||||
- `commands.config: true` enables `/config` (reads/writes `moltbot.json`).
|
||||
- `channels.<provider>.configWrites` gates config mutations initiated by that channel (default: true). This applies to `/config set|unset` plus provider-specific auto-migrations (Telegram supergroup ID changes, Slack channel ID changes).
|
||||
- `commands.debug: true` enables `/debug` (runtime-only overrides).
|
||||
- `commands.restart: true` enables `/restart` and the gateway tool restart action.
|
||||
@@ -980,7 +980,7 @@ Set `web.enabled: false` to keep it off by default.
|
||||
|
||||
### `channels.telegram` (bot transport)
|
||||
|
||||
Clawdbot starts Telegram only when a `channels.telegram` config section exists. The bot token is resolved from `channels.telegram.botToken` (or `channels.telegram.tokenFile`), with `TELEGRAM_BOT_TOKEN` as a fallback for the default account.
|
||||
Moltbot starts Telegram only when a `channels.telegram` config section exists. The bot token is resolved from `channels.telegram.botToken` (or `channels.telegram.tokenFile`), with `TELEGRAM_BOT_TOKEN` as a fallback for the default account.
|
||||
Set `channels.telegram.enabled: false` to disable automatic startup.
|
||||
Multi-account support lives under `channels.telegram.accounts` (see the multi-account section above). Env tokens only apply to the default account.
|
||||
Set `channels.telegram.configWrites: false` to block Telegram-initiated config writes (including supergroup ID migrations and `/config set|unset`).
|
||||
@@ -1118,7 +1118,7 @@ Multi-account support lives under `channels.discord.accounts` (see the multi-acc
|
||||
}
|
||||
```
|
||||
|
||||
Clawdbot starts Discord only when a `channels.discord` config section exists. The token is resolved from `channels.discord.token`, with `DISCORD_BOT_TOKEN` as a fallback for the default account (unless `channels.discord.enabled` is `false`). Use `user:<id>` (DM) or `channel:<id>` (guild channel) when specifying delivery targets for cron/CLI commands; bare numeric IDs are ambiguous and rejected.
|
||||
Moltbot starts Discord only when a `channels.discord` config section exists. The token is resolved from `channels.discord.token`, with `DISCORD_BOT_TOKEN` as a fallback for the default account (unless `channels.discord.enabled` is `false`). Use `user:<id>` (DM) or `channel:<id>` (guild channel) when specifying delivery targets for cron/CLI commands; bare numeric IDs are ambiguous and rejected.
|
||||
Guild slugs are lowercase with spaces replaced by `-`; channel keys use the slugged channel name (no leading `#`). Prefer guild ids as keys to avoid rename ambiguity.
|
||||
Bot-authored messages are ignored by default. Enable with `channels.discord.allowBots` (own messages are still filtered to prevent self-reply loops).
|
||||
Reaction notification modes:
|
||||
@@ -1228,7 +1228,7 @@ Slack runs in Socket Mode and requires both a bot token and app token:
|
||||
|
||||
Multi-account support lives under `channels.slack.accounts` (see the multi-account section above). Env tokens only apply to the default account.
|
||||
|
||||
Clawdbot starts Slack when the provider is enabled and both tokens are set (via config or `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`). Use `user:<id>` (DM) or `channel:<id>` when specifying delivery targets for cron/CLI commands.
|
||||
Moltbot starts Slack when the provider is enabled and both tokens are set (via config or `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`). Use `user:<id>` (DM) or `channel:<id>` when specifying delivery targets for cron/CLI commands.
|
||||
Set `channels.slack.configWrites: false` to block Slack-initiated config writes (including channel ID migrations and `/config set|unset`).
|
||||
|
||||
Bot-authored messages are ignored by default. Enable with `channels.slack.allowBots` or `channels.slack.channels.<id>.allowBots`.
|
||||
@@ -1255,7 +1255,7 @@ Slack action groups (gate `slack` tool actions):
|
||||
### `channels.mattermost` (bot token)
|
||||
|
||||
Mattermost ships as a plugin and is not bundled with the core install.
|
||||
Install it first: `clawdbot plugins install @clawdbot/mattermost` (or `./extensions/mattermost` from a git checkout).
|
||||
Install it first: `moltbot plugins install @moltbot/mattermost` (or `./extensions/mattermost` from a git checkout).
|
||||
|
||||
Mattermost requires a bot token plus the base URL for your server:
|
||||
|
||||
@@ -1276,7 +1276,7 @@ Mattermost requires a bot token plus the base URL for your server:
|
||||
}
|
||||
```
|
||||
|
||||
Clawdbot starts Mattermost when the account is configured (bot token + base URL) and enabled. The token + base URL are resolved from `channels.mattermost.botToken` + `channels.mattermost.baseUrl` or `MATTERMOST_BOT_TOKEN` + `MATTERMOST_URL` for the default account (unless `channels.mattermost.enabled` is `false`).
|
||||
Moltbot starts Mattermost when the account is configured (bot token + base URL) and enabled. The token + base URL are resolved from `channels.mattermost.botToken` + `channels.mattermost.baseUrl` or `MATTERMOST_BOT_TOKEN` + `MATTERMOST_URL` for the default account (unless `channels.mattermost.enabled` is `false`).
|
||||
|
||||
Chat modes:
|
||||
- `oncall` (default): respond to channel messages only when @mentioned.
|
||||
@@ -1315,7 +1315,7 @@ Reaction notification modes:
|
||||
|
||||
### `channels.imessage` (imsg CLI)
|
||||
|
||||
Clawdbot spawns `imsg rpc` (JSON-RPC over stdio). No daemon or port required.
|
||||
Moltbot spawns `imsg rpc` (JSON-RPC over stdio). No daemon or port required.
|
||||
|
||||
```json5
|
||||
{
|
||||
@@ -1369,13 +1369,13 @@ own per-scope workspaces under `agents.defaults.sandbox.workspaceRoot`.
|
||||
|
||||
### `agents.defaults.repoRoot`
|
||||
|
||||
Optional repository root to show in the system prompt’s Runtime line. If unset, Clawdbot
|
||||
Optional repository root to show in the system prompt’s Runtime line. If unset, Moltbot
|
||||
tries to detect a `.git` directory by walking upward from the workspace (and current
|
||||
working directory). The path must exist to be used.
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: { defaults: { repoRoot: "~/Projects/clawdbot" } }
|
||||
agents: { defaults: { repoRoot: "~/Projects/moltbot" } }
|
||||
}
|
||||
```
|
||||
|
||||
@@ -1396,7 +1396,7 @@ Use this for pre-seeded deployments where your workspace files come from a repo.
|
||||
Max characters of each workspace bootstrap file injected into the system prompt
|
||||
before truncation. Default: `20000`.
|
||||
|
||||
When a file exceeds this limit, Clawdbot logs a warning and injects a truncated
|
||||
When a file exceeds this limit, Moltbot logs a warning and injects a truncated
|
||||
head/tail with a marker.
|
||||
|
||||
```json5
|
||||
@@ -1408,7 +1408,7 @@ head/tail with a marker.
|
||||
### `agents.defaults.userTimezone`
|
||||
|
||||
Sets the user’s timezone for **system prompt context** (not for timestamps in
|
||||
message envelopes). If unset, Clawdbot uses the host timezone at runtime.
|
||||
message envelopes). If unset, Moltbot uses the host timezone at runtime.
|
||||
|
||||
```json5
|
||||
{
|
||||
@@ -1448,7 +1448,7 @@ streaming, final replies) across channels unless already present.
|
||||
|
||||
If `messages.responsePrefix` is unset, no prefix is applied by default. WhatsApp self-chat
|
||||
replies are the exception: they default to `[{identity.name}]` when set, otherwise
|
||||
`[clawdbot]`, so same-phone conversations stay legible.
|
||||
`[moltbot]`, so same-phone conversations stay legible.
|
||||
Set it to `"auto"` to derive `[{identity.name}]` for the routed agent (when set).
|
||||
|
||||
#### Template variables
|
||||
@@ -1477,9 +1477,9 @@ Unresolved variables remain as literal text.
|
||||
Example output: `[claude-opus-4-5 | think:high] Here's my response...`
|
||||
|
||||
WhatsApp inbound prefix is configured via `channels.whatsapp.messagePrefix` (deprecated:
|
||||
`messages.messagePrefix`). Default stays **unchanged**: `"[clawdbot]"` when
|
||||
`messages.messagePrefix`). Default stays **unchanged**: `"[moltbot]"` when
|
||||
`channels.whatsapp.allowFrom` is empty, otherwise `""` (no prefix). When using
|
||||
`"[clawdbot]"`, Clawdbot will instead use `[{identity.name}]` when the routed
|
||||
`"[moltbot]"`, Moltbot will instead use `[{identity.name}]` when the routed
|
||||
agent has `identity.name` set.
|
||||
|
||||
`ackReaction` sends a best-effort emoji reaction to acknowledge inbound messages
|
||||
@@ -1497,7 +1497,7 @@ active agent’s `identity.emoji` when set, otherwise `"👀"`. Set it to `""` t
|
||||
|
||||
#### `messages.tts`
|
||||
|
||||
Enable text-to-speech for outbound replies. When on, Clawdbot generates audio
|
||||
Enable text-to-speech for outbound replies. When on, Moltbot generates audio
|
||||
using ElevenLabs or OpenAI and attaches it to responses. Telegram uses Opus
|
||||
voice notes; other channels send MP3 audio.
|
||||
|
||||
@@ -1613,7 +1613,7 @@ Z.AI GLM-4.x models automatically enable thinking mode unless you:
|
||||
- set `--thinking off`, or
|
||||
- define `agents.defaults.models["zai/<model>"].params.thinking` yourself.
|
||||
|
||||
Clawdbot also ships a few built-in alias shorthands. Defaults only apply when the model
|
||||
Moltbot also ships a few built-in alias shorthands. Defaults only apply when the model
|
||||
is already present in `agents.defaults.models`:
|
||||
|
||||
- `opus` -> `anthropic/claude-opus-4-5`
|
||||
@@ -1908,7 +1908,7 @@ See [/concepts/typing-indicators](/concepts/typing-indicators) for behavior deta
|
||||
|
||||
`agents.defaults.model.primary` should be set as `provider/model` (e.g. `anthropic/claude-opus-4-5`).
|
||||
Aliases come from `agents.defaults.models.*.alias` (e.g. `Opus`).
|
||||
If you omit the provider, Clawdbot currently assumes `anthropic` as a temporary
|
||||
If you omit the provider, Moltbot currently assumes `anthropic` as a temporary
|
||||
deprecation fallback.
|
||||
Z.AI models are available as `zai/<model>` (e.g. `zai/glm-4.7`) and require
|
||||
`ZAI_API_KEY` (or legacy `Z_AI_API_KEY`) in the environment.
|
||||
@@ -1943,7 +1943,7 @@ Note: `applyPatch` is only under `tools.exec`.
|
||||
|
||||
`tools.web` configures web search + fetch tools:
|
||||
- `tools.web.search.enabled` (default: true when key is present)
|
||||
- `tools.web.search.apiKey` (recommended: set via `clawdbot configure --section web`, or use `BRAVE_API_KEY` env var)
|
||||
- `tools.web.search.apiKey` (recommended: set via `moltbot configure --section web`, or use `BRAVE_API_KEY` env var)
|
||||
- `tools.web.search.maxResults` (1–10, default 5)
|
||||
- `tools.web.search.timeoutSeconds` (default 30)
|
||||
- `tools.web.search.cacheTtlMinutes` (default 15)
|
||||
@@ -2101,7 +2101,7 @@ Tool groups (shorthands) work in **global** and **per-agent** tool policies:
|
||||
- `group:automation`: `cron`, `gateway`
|
||||
- `group:messaging`: `message`
|
||||
- `group:nodes`: `nodes`
|
||||
- `group:clawdbot`: all built-in Clawdbot tools (excludes provider plugins)
|
||||
- `group:moltbot`: all built-in Moltbot tools (excludes provider plugins)
|
||||
|
||||
`tools.elevated` controls elevated (host) exec access:
|
||||
- `enabled`: allow elevated mode (default true)
|
||||
@@ -2194,8 +2194,8 @@ For package installs, ensure network egress, a writable root FS, and a root user
|
||||
workspaceAccess: "none", // none | ro | rw
|
||||
workspaceRoot: "~/.clawdbot/sandboxes",
|
||||
docker: {
|
||||
image: "clawdbot-sandbox:bookworm-slim",
|
||||
containerPrefix: "clawdbot-sbx-",
|
||||
image: "moltbot-sandbox:bookworm-slim",
|
||||
containerPrefix: "moltbot-sbx-",
|
||||
workdir: "/workspace",
|
||||
readOnlyRoot: true,
|
||||
tmpfs: ["/tmp", "/var/tmp", "/run"],
|
||||
@@ -2214,15 +2214,15 @@ For package installs, ensure network egress, a writable root FS, and a root user
|
||||
nproc: 256
|
||||
},
|
||||
seccompProfile: "/path/to/seccomp.json",
|
||||
apparmorProfile: "clawdbot-sandbox",
|
||||
apparmorProfile: "moltbot-sandbox",
|
||||
dns: ["1.1.1.1", "8.8.8.8"],
|
||||
extraHosts: ["internal.service:10.0.0.5"],
|
||||
binds: ["/var/run/docker.sock:/var/run/docker.sock", "/home/user/source:/source:rw"]
|
||||
},
|
||||
browser: {
|
||||
enabled: false,
|
||||
image: "clawdbot-sandbox-browser:bookworm-slim",
|
||||
containerPrefix: "clawdbot-sbx-browser-",
|
||||
image: "moltbot-sandbox-browser:bookworm-slim",
|
||||
containerPrefix: "moltbot-sbx-browser-",
|
||||
cdpPort: 9222,
|
||||
vncPort: 5900,
|
||||
noVncPort: 6080,
|
||||
@@ -2289,13 +2289,13 @@ Defaults: all allowlists are unset (no restriction). `allowHostControl` defaults
|
||||
|
||||
### `models` (custom providers + base URLs)
|
||||
|
||||
Clawdbot uses the **pi-coding-agent** model catalog. You can add custom providers
|
||||
Moltbot uses the **pi-coding-agent** model catalog. You can add custom providers
|
||||
(LiteLLM, local OpenAI-compatible servers, Anthropic proxies, etc.) by writing
|
||||
`~/.clawdbot/agents/<agentId>/agent/models.json` or by defining the same schema inside your
|
||||
Clawdbot config under `models.providers`.
|
||||
Moltbot config under `models.providers`.
|
||||
Provider-by-provider overview + examples: [/concepts/model-providers](/concepts/model-providers).
|
||||
|
||||
When `models.providers` is present, Clawdbot writes/merges a `models.json` into
|
||||
When `models.providers` is present, Moltbot writes/merges a `models.json` into
|
||||
`~/.clawdbot/agents/<agentId>/agent/` on startup:
|
||||
- default behavior: **merge** (keeps existing providers, overrides on name)
|
||||
- set `models.mode: "replace"` to overwrite the file contents
|
||||
@@ -2338,14 +2338,14 @@ Select the model via `agents.defaults.model.primary` (provider/model).
|
||||
|
||||
### OpenCode Zen (multi-model proxy)
|
||||
|
||||
OpenCode Zen is a multi-model gateway with per-model endpoints. Clawdbot uses
|
||||
OpenCode Zen is a multi-model gateway with per-model endpoints. Moltbot uses
|
||||
the built-in `opencode` provider from pi-ai; set `OPENCODE_API_KEY` (or
|
||||
`OPENCODE_ZEN_API_KEY`) from https://opencode.ai/auth.
|
||||
|
||||
Notes:
|
||||
- Model refs use `opencode/<modelId>` (example: `opencode/claude-opus-4-5`).
|
||||
- If you enable an allowlist via `agents.defaults.models`, add each model you plan to use.
|
||||
- Shortcut: `clawdbot onboard --auth-choice opencode-zen`.
|
||||
- Shortcut: `moltbot onboard --auth-choice opencode-zen`.
|
||||
|
||||
```json5
|
||||
{
|
||||
@@ -2363,7 +2363,7 @@ Notes:
|
||||
Z.AI models are available via the built-in `zai` provider. Set `ZAI_API_KEY`
|
||||
in your environment and reference the model by provider/model.
|
||||
|
||||
Shortcut: `clawdbot onboard --auth-choice zai-api-key`.
|
||||
Shortcut: `moltbot onboard --auth-choice zai-api-key`.
|
||||
|
||||
```json5
|
||||
{
|
||||
@@ -2425,7 +2425,7 @@ Use Moonshot's OpenAI-compatible endpoint:
|
||||
```
|
||||
|
||||
Notes:
|
||||
- Set `MOONSHOT_API_KEY` in the environment or use `clawdbot onboard --auth-choice moonshot-api-key`.
|
||||
- Set `MOONSHOT_API_KEY` in the environment or use `moltbot onboard --auth-choice moonshot-api-key`.
|
||||
- Model ref: `moonshot/kimi-k2-0905-preview`.
|
||||
- Use `https://api.moonshot.cn/v1` if you need the China endpoint.
|
||||
|
||||
@@ -2469,7 +2469,7 @@ Use Kimi Code's dedicated OpenAI-compatible endpoint (separate from Moonshot):
|
||||
```
|
||||
|
||||
Notes:
|
||||
- Set `KIMICODE_API_KEY` in the environment or use `clawdbot onboard --auth-choice kimi-code-api-key`.
|
||||
- Set `KIMICODE_API_KEY` in the environment or use `moltbot onboard --auth-choice kimi-code-api-key`.
|
||||
- Model ref: `kimi-code/kimi-for-coding`.
|
||||
|
||||
### Synthetic (Anthropic-compatible)
|
||||
@@ -2510,7 +2510,7 @@ Use Synthetic's Anthropic-compatible endpoint:
|
||||
```
|
||||
|
||||
Notes:
|
||||
- Set `SYNTHETIC_API_KEY` or use `clawdbot onboard --auth-choice synthetic-api-key`.
|
||||
- Set `SYNTHETIC_API_KEY` or use `moltbot onboard --auth-choice synthetic-api-key`.
|
||||
- Model ref: `synthetic/hf:MiniMaxAI/MiniMax-M2.1`.
|
||||
- Base URL should omit `/v1` because the Anthropic client appends it.
|
||||
|
||||
@@ -2557,7 +2557,7 @@ Use MiniMax M2.1 directly without LM Studio:
|
||||
```
|
||||
|
||||
Notes:
|
||||
- Set `MINIMAX_API_KEY` environment variable or use `clawdbot onboard --auth-choice minimax-api`.
|
||||
- Set `MINIMAX_API_KEY` environment variable or use `moltbot onboard --auth-choice minimax-api`.
|
||||
- Available model: `MiniMax-M2.1` (default).
|
||||
- Update pricing in `models.json` if you need exact cost tracking.
|
||||
|
||||
@@ -2664,7 +2664,7 @@ Fields:
|
||||
- `atHour`: local hour (0-23) for the daily reset boundary.
|
||||
- `idleMinutes`: sliding idle window in minutes. When daily + idle are both configured, whichever expires first wins.
|
||||
- `resetByType`: per-session overrides for `dm`, `group`, and `thread`.
|
||||
- If you only set legacy `session.idleMinutes` without any `reset`/`resetByType`, Clawdbot stays in idle-only mode for backward compatibility.
|
||||
- If you only set legacy `session.idleMinutes` without any `reset`/`resetByType`, Moltbot stays in idle-only mode for backward compatibility.
|
||||
- `heartbeatIdleMinutes`: optional idle override for heartbeat checks (daily reset still applies when enabled).
|
||||
- `agentToAgent.maxPingPongTurns`: max reply-back turns between requester/target (0–5, default 5).
|
||||
- `sendPolicy.default`: `allow` or `deny` fallback when no rule matches.
|
||||
@@ -2759,7 +2759,7 @@ Example:
|
||||
|
||||
### `browser` (clawd-managed browser)
|
||||
|
||||
Clawdbot can start a **dedicated, isolated** Chrome/Brave/Edge/Chromium instance for clawd and expose a small loopback control service.
|
||||
Moltbot can start a **dedicated, isolated** Chrome/Brave/Edge/Chromium instance for clawd and expose a small loopback control service.
|
||||
Profiles can point at a **remote** Chromium-based browser via `profiles.<name>.cdpUrl`. Remote
|
||||
profiles are attach-only (start/stop/reset are disabled).
|
||||
|
||||
@@ -2772,7 +2772,7 @@ Defaults:
|
||||
- control service: loopback only (port derived from `gateway.port`, default `18791`)
|
||||
- CDP URL: `http://127.0.0.1:18792` (control service + 1, legacy single-profile)
|
||||
- profile color: `#FF4500` (lobster-orange)
|
||||
- Note: the control server is started by the running gateway (Clawdbot.app menubar, or `clawdbot gateway`).
|
||||
- Note: the control server is started by the running gateway (Moltbot.app menubar, or `moltbot gateway`).
|
||||
- Auto-detect order: default browser if Chromium-based; otherwise Chrome → Brave → Edge → Chromium → Chrome Canary.
|
||||
|
||||
```json5
|
||||
@@ -2810,7 +2810,7 @@ If unset, clients fall back to a muted light-blue.
|
||||
// Optional: Control UI assistant identity override.
|
||||
// If unset, the Control UI uses the active agent identity (config or IDENTITY.md).
|
||||
assistant: {
|
||||
name: "Clawdbot",
|
||||
name: "Moltbot",
|
||||
avatar: "CB" // emoji, short text, or image URL/data URI
|
||||
}
|
||||
}
|
||||
@@ -2832,7 +2832,7 @@ Defaults:
|
||||
mode: "local", // or "remote"
|
||||
port: 18789, // WS + HTTP multiplex
|
||||
bind: "loopback",
|
||||
// controlUi: { enabled: true, basePath: "/clawdbot" }
|
||||
// controlUi: { enabled: true, basePath: "/moltbot" }
|
||||
// auth: { mode: "token", token: "your-token" } // token gates WS + Control UI access
|
||||
// tailscale: { mode: "off" | "serve" | "funnel" }
|
||||
}
|
||||
@@ -2841,7 +2841,7 @@ Defaults:
|
||||
|
||||
Control UI base path:
|
||||
- `gateway.controlUi.basePath` sets the URL prefix where the Control UI is served.
|
||||
- Examples: `"/ui"`, `"/clawdbot"`, `"/apps/clawdbot"`.
|
||||
- Examples: `"/ui"`, `"/moltbot"`, `"/apps/moltbot"`.
|
||||
- Default: root (`/`) (unchanged).
|
||||
- `gateway.controlUi.allowInsecureAuth` allows token-only auth for the Control UI when
|
||||
device identity is omitted (typically over HTTP). Default: `false`. Prefer HTTPS
|
||||
@@ -2857,11 +2857,11 @@ Related docs:
|
||||
|
||||
Trusted proxies:
|
||||
- `gateway.trustedProxies`: list of reverse proxy IPs that terminate TLS in front of the Gateway.
|
||||
- When a connection comes from one of these IPs, Clawdbot uses `x-forwarded-for` (or `x-real-ip`) to determine the client IP for local pairing checks and HTTP auth/local checks.
|
||||
- When a connection comes from one of these IPs, Moltbot uses `x-forwarded-for` (or `x-real-ip`) to determine the client IP for local pairing checks and HTTP auth/local checks.
|
||||
- Only list proxies you fully control, and ensure they **overwrite** incoming `x-forwarded-for`.
|
||||
|
||||
Notes:
|
||||
- `clawdbot gateway` refuses to start unless `gateway.mode` is set to `local` (or you pass the override flag).
|
||||
- `moltbot gateway` refuses to start unless `gateway.mode` is set to `local` (or you pass the override flag).
|
||||
- `gateway.port` controls the single multiplexed port used for WebSocket + HTTP (control UI, hooks, A2UI).
|
||||
- OpenAI Chat Completions endpoint: **disabled by default**; enable with `gateway.http.endpoints.chatCompletions.enabled: true`.
|
||||
- Precedence: `--port` > `CLAWDBOT_GATEWAY_PORT` > `gateway.port` > default `18789`.
|
||||
@@ -2876,7 +2876,7 @@ Auth and Tailscale:
|
||||
- `gateway.auth.password` can be set here, or via `CLAWDBOT_GATEWAY_PASSWORD` (recommended).
|
||||
- `gateway.auth.allowTailscale` allows Tailscale Serve identity headers
|
||||
(`tailscale-user-login`) to satisfy auth when the request arrives on loopback
|
||||
with `x-forwarded-for`, `x-forwarded-proto`, and `x-forwarded-host`. Clawdbot
|
||||
with `x-forwarded-for`, `x-forwarded-proto`, and `x-forwarded-host`. Moltbot
|
||||
verifies the identity by resolving the `x-forwarded-for` address via
|
||||
`tailscale whois` before accepting it. When `true`, Serve requests do not need
|
||||
a token/password; set `false` to require explicit credentials. Defaults to
|
||||
@@ -2892,7 +2892,7 @@ Remote client defaults (CLI):
|
||||
- `gateway.remote.password` supplies the password for remote calls (leave unset for no auth).
|
||||
|
||||
macOS app behavior:
|
||||
- Clawdbot.app watches `~/.clawdbot/clawdbot.json` and switches modes live when `gateway.mode` or `gateway.remote.url` changes.
|
||||
- Moltbot.app watches `~/.clawdbot/moltbot.json` and switches modes live when `gateway.mode` or `gateway.remote.url` changes.
|
||||
- If `gateway.mode` is unset but `gateway.remote.url` is set, the macOS app treats it as remote mode.
|
||||
- When you change connection mode in the macOS app, it writes `gateway.mode` (and `gateway.remote.url` + `gateway.remote.transport` in remote mode) back to the config file.
|
||||
|
||||
@@ -2926,7 +2926,7 @@ Direct transport example (macOS app):
|
||||
|
||||
### `gateway.reload` (Config hot reload)
|
||||
|
||||
The Gateway watches `~/.clawdbot/clawdbot.json` (or `CLAWDBOT_CONFIG_PATH`) and applies changes automatically.
|
||||
The Gateway watches `~/.clawdbot/moltbot.json` (or `CLAWDBOT_CONFIG_PATH`) and applies changes automatically.
|
||||
|
||||
Modes:
|
||||
- `hybrid` (default): hot-apply safe changes; restart the Gateway for critical changes.
|
||||
@@ -2948,7 +2948,7 @@ Modes:
|
||||
#### Hot reload matrix (files + impact)
|
||||
|
||||
Files watched:
|
||||
- `~/.clawdbot/clawdbot.json` (or `CLAWDBOT_CONFIG_PATH`)
|
||||
- `~/.clawdbot/moltbot.json` (or `CLAWDBOT_CONFIG_PATH`)
|
||||
|
||||
Hot-applied (no full gateway restart):
|
||||
- `hooks` (webhook auth/path/mappings) + `hooks.gmail` (Gmail watcher restarted)
|
||||
@@ -2976,8 +2976,8 @@ To run multiple gateways on one host (for redundancy or a rescue bot), isolate p
|
||||
- `gateway.port` (unique per instance)
|
||||
|
||||
Convenience flags (CLI):
|
||||
- `clawdbot --dev …` → uses `~/.clawdbot-dev` + shifts ports from base `19001`
|
||||
- `clawdbot --profile <name> …` → uses `~/.clawdbot-<name>` (port via config/env/flags)
|
||||
- `moltbot --dev …` → uses `~/.clawdbot-dev` + shifts ports from base `19001`
|
||||
- `moltbot --profile <name> …` → uses `~/.clawdbot-<name>` (port via config/env/flags)
|
||||
|
||||
See [Gateway runbook](/gateway) for the derived port mapping (gateway/browser/canvas).
|
||||
See [Multiple gateways](/gateway/multiple-gateways) for browser/CDP port isolation details.
|
||||
@@ -2986,7 +2986,7 @@ Example:
|
||||
```bash
|
||||
CLAWDBOT_CONFIG_PATH=~/.clawdbot/a.json \
|
||||
CLAWDBOT_STATE_DIR=~/.clawdbot-a \
|
||||
clawdbot gateway --port 19001
|
||||
moltbot gateway --port 19001
|
||||
```
|
||||
|
||||
### `hooks` (Gateway webhooks)
|
||||
@@ -3026,7 +3026,7 @@ Defaults:
|
||||
|
||||
Requests must include the hook token:
|
||||
- `Authorization: Bearer <token>` **or**
|
||||
- `x-clawdbot-token: <token>` **or**
|
||||
- `x-moltbot-token: <token>` **or**
|
||||
- `?token=<token>`
|
||||
|
||||
Endpoints:
|
||||
@@ -3045,13 +3045,13 @@ Mapping notes:
|
||||
- If there is no prior delivery route, set `channel` + `to` explicitly (required for Telegram/Discord/Google Chat/Slack/Signal/iMessage/MS Teams).
|
||||
- `model` overrides the LLM for this hook run (`provider/model` or alias; must be allowed if `agents.defaults.models` is set).
|
||||
|
||||
Gmail helper config (used by `clawdbot webhooks gmail setup` / `run`):
|
||||
Gmail helper config (used by `moltbot webhooks gmail setup` / `run`):
|
||||
|
||||
```json5
|
||||
{
|
||||
hooks: {
|
||||
gmail: {
|
||||
account: "clawdbot@gmail.com",
|
||||
account: "moltbot@gmail.com",
|
||||
topic: "projects/<project-id>/topics/gog-gmail-watch",
|
||||
subscription: "gog-gmail-watch-push",
|
||||
pushToken: "shared-push-token",
|
||||
@@ -3087,7 +3087,7 @@ Gateway auto-start:
|
||||
- Avoid running a separate `gog gmail watch serve` alongside the Gateway; it will
|
||||
fail with `listen tcp 127.0.0.1:8788: bind: address already in use`.
|
||||
|
||||
Note: when `tailscale.mode` is on, Clawdbot defaults `serve.path` to `/` so
|
||||
Note: when `tailscale.mode` is on, Moltbot defaults `serve.path` to `/` so
|
||||
Tailscale can proxy `/gmail-pubsub` correctly (it strips the set-path prefix).
|
||||
If you need the backend to receive the prefixed path, set
|
||||
`hooks.gmail.tailscale.target` to a full URL (and align `serve.path`).
|
||||
@@ -3103,9 +3103,9 @@ The server listens on the **gateway bind host** (LAN or Tailnet) so nodes can re
|
||||
The server:
|
||||
- serves files under `canvasHost.root`
|
||||
- injects a tiny live-reload client into served HTML
|
||||
- watches the directory and broadcasts reloads over a WebSocket endpoint at `/__clawdbot/ws`
|
||||
- watches the directory and broadcasts reloads over a WebSocket endpoint at `/__moltbot/ws`
|
||||
- auto-creates a starter `index.html` when the directory is empty (so you see something immediately)
|
||||
- also serves A2UI at `/__clawdbot__/a2ui/` and is advertised to nodes as `canvasHostUrl`
|
||||
- also serves A2UI at `/__moltbot__/a2ui/` and is advertised to nodes as `canvasHostUrl`
|
||||
(always used by nodes for Canvas/A2UI)
|
||||
|
||||
Disable live reload (and file watching) if the directory is large or you hit `EMFILE`:
|
||||
@@ -3175,7 +3175,7 @@ Auto-generated certs require `openssl` on PATH; if generation fails, the bridge
|
||||
|
||||
### `discovery.mdns` (Bonjour / mDNS broadcast mode)
|
||||
|
||||
Controls LAN mDNS discovery broadcasts (`_clawdbot-gw._tcp`).
|
||||
Controls LAN mDNS discovery broadcasts (`_moltbot-gw._tcp`).
|
||||
|
||||
- `minimal` (default): omit `cliPath` + `sshPort` from TXT records
|
||||
- `full`: include `cliPath` + `sshPort` in TXT records
|
||||
@@ -3189,16 +3189,16 @@ Controls LAN mDNS discovery broadcasts (`_clawdbot-gw._tcp`).
|
||||
|
||||
### `discovery.wideArea` (Wide-Area Bonjour / unicast DNS‑SD)
|
||||
|
||||
When enabled, the Gateway writes a unicast DNS-SD zone for `_clawdbot-bridge._tcp` under `~/.clawdbot/dns/` using the standard discovery domain `clawdbot.internal.`
|
||||
When enabled, the Gateway writes a unicast DNS-SD zone for `_moltbot-bridge._tcp` under `~/.clawdbot/dns/` using the standard discovery domain `moltbot.internal.`
|
||||
|
||||
To make iOS/Android discover across networks (Vienna ⇄ London), pair this with:
|
||||
- a DNS server on the gateway host serving `clawdbot.internal.` (CoreDNS is recommended)
|
||||
- Tailscale **split DNS** so clients resolve `clawdbot.internal` via that server
|
||||
- a DNS server on the gateway host serving `moltbot.internal.` (CoreDNS is recommended)
|
||||
- Tailscale **split DNS** so clients resolve `moltbot.internal` via that server
|
||||
|
||||
One-time setup helper (gateway host):
|
||||
|
||||
```bash
|
||||
clawdbot dns setup --apply
|
||||
moltbot dns setup --apply
|
||||
```
|
||||
|
||||
```json5
|
||||
|
||||
@@ -7,12 +7,12 @@ read_when:
|
||||
---
|
||||
# Discovery & transports
|
||||
|
||||
Clawdbot has two distinct problems that look similar on the surface:
|
||||
Moltbot has two distinct problems that look similar on the surface:
|
||||
|
||||
1) **Operator remote control**: the macOS menu bar app controlling a gateway running elsewhere.
|
||||
2) **Node pairing**: iOS/Android (and future nodes) finding a gateway and pairing securely.
|
||||
|
||||
The design goal is to keep all network discovery/advertising in the **Node Gateway** (`clawd` / `clawdbot gateway`) and keep clients (mac app, iOS) as consumers.
|
||||
The design goal is to keep all network discovery/advertising in the **Node Gateway** (`clawd` / `moltbot gateway`) and keep clients (mac app, iOS) as consumers.
|
||||
|
||||
## Terms
|
||||
|
||||
@@ -52,7 +52,7 @@ Troubleshooting and beacon details: [Bonjour](/gateway/bonjour).
|
||||
#### Service beacon details
|
||||
|
||||
- Service types:
|
||||
- `_clawdbot-gw._tcp` (gateway transport beacon)
|
||||
- `_moltbot-gw._tcp` (gateway transport beacon)
|
||||
- TXT keys (non-secret):
|
||||
- `role=gateway`
|
||||
- `lanHost=<hostname>.local`
|
||||
@@ -60,13 +60,13 @@ Troubleshooting and beacon details: [Bonjour](/gateway/bonjour).
|
||||
- `gatewayPort=18789` (Gateway WS + HTTP)
|
||||
- `gatewayTls=1` (only when TLS is enabled)
|
||||
- `gatewayTlsSha256=<sha256>` (only when TLS is enabled and fingerprint is available)
|
||||
- `canvasPort=18793` (default canvas host port; serves `/__clawdbot__/canvas/`)
|
||||
- `cliPath=<path>` (optional; absolute path to a runnable `clawdbot` entrypoint or binary)
|
||||
- `canvasPort=18793` (default canvas host port; serves `/__moltbot__/canvas/`)
|
||||
- `cliPath=<path>` (optional; absolute path to a runnable `moltbot` entrypoint or binary)
|
||||
- `tailnetDns=<magicdns>` (optional hint; auto-detected when Tailscale is available)
|
||||
|
||||
Disable/override:
|
||||
- `CLAWDBOT_DISABLE_BONJOUR=1` disables advertising.
|
||||
- `gateway.bind` in `~/.clawdbot/clawdbot.json` controls the Gateway bind mode.
|
||||
- `gateway.bind` in `~/.clawdbot/moltbot.json` controls the Gateway bind mode.
|
||||
- `CLAWDBOT_SSH_PORT` overrides the SSH port advertised in TXT (defaults to 22).
|
||||
- `CLAWDBOT_TAILNET_DNS` publishes a `tailnetDns` hint (MagicDNS).
|
||||
- `CLAWDBOT_CLI_PATH` overrides the advertised CLI path.
|
||||
|
||||
@@ -6,44 +6,44 @@ read_when:
|
||||
---
|
||||
# Doctor
|
||||
|
||||
`clawdbot doctor` is the repair + migration tool for Clawdbot. It fixes stale
|
||||
`moltbot doctor` is the repair + migration tool for Moltbot. It fixes stale
|
||||
config/state, checks health, and provides actionable repair steps.
|
||||
|
||||
## Quick start
|
||||
|
||||
```bash
|
||||
clawdbot doctor
|
||||
moltbot doctor
|
||||
```
|
||||
|
||||
### Headless / automation
|
||||
|
||||
```bash
|
||||
clawdbot doctor --yes
|
||||
moltbot doctor --yes
|
||||
```
|
||||
|
||||
Accept defaults without prompting (including restart/service/sandbox repair steps when applicable).
|
||||
|
||||
```bash
|
||||
clawdbot doctor --repair
|
||||
moltbot doctor --repair
|
||||
```
|
||||
|
||||
Apply recommended repairs without prompting (repairs + restarts where safe).
|
||||
|
||||
```bash
|
||||
clawdbot doctor --repair --force
|
||||
moltbot doctor --repair --force
|
||||
```
|
||||
|
||||
Apply aggressive repairs too (overwrites custom supervisor configs).
|
||||
|
||||
```bash
|
||||
clawdbot doctor --non-interactive
|
||||
moltbot doctor --non-interactive
|
||||
```
|
||||
|
||||
Run without prompts and only apply safe migrations (config normalization + on-disk state moves). Skips restart/service/sandbox actions that require human confirmation.
|
||||
Legacy state migrations run automatically when detected.
|
||||
|
||||
```bash
|
||||
clawdbot doctor --deep
|
||||
moltbot doctor --deep
|
||||
```
|
||||
|
||||
Scan system services for extra gateway installs (launchd/systemd/schtasks).
|
||||
@@ -51,7 +51,7 @@ Scan system services for extra gateway installs (launchd/systemd/schtasks).
|
||||
If you want to review changes before writing, open the config file first:
|
||||
|
||||
```bash
|
||||
cat ~/.clawdbot/clawdbot.json
|
||||
cat ~/.clawdbot/moltbot.json
|
||||
```
|
||||
|
||||
## What it does (summary)
|
||||
@@ -65,7 +65,7 @@ cat ~/.clawdbot/clawdbot.json
|
||||
- State integrity and permissions checks (sessions, transcripts, state dir).
|
||||
- Config file permission checks (chmod 600) when running locally.
|
||||
- Model auth health: checks OAuth expiry, can refresh expiring tokens, and reports auth-profile cooldown/disabled states.
|
||||
- Extra workspace dir detection (`~/clawdbot`).
|
||||
- Extra workspace dir detection (`~/moltbot`).
|
||||
- Sandbox image repair when sandboxing is enabled.
|
||||
- Legacy service migration and extra gateway detection.
|
||||
- Gateway runtime checks (service installed but not running; cached launchd label).
|
||||
@@ -92,12 +92,12 @@ schema.
|
||||
|
||||
### 2) Legacy config key migrations
|
||||
When the config contains deprecated keys, other commands refuse to run and ask
|
||||
you to run `clawdbot doctor`.
|
||||
you to run `moltbot doctor`.
|
||||
|
||||
Doctor will:
|
||||
- Explain which legacy keys were found.
|
||||
- Show the migration it applied.
|
||||
- Rewrite `~/.clawdbot/clawdbot.json` with the updated schema.
|
||||
- Rewrite `~/.clawdbot/moltbot.json` with the updated schema.
|
||||
|
||||
The Gateway also auto-runs doctor migrations on startup when it detects a
|
||||
legacy config format, so stale configs are repaired without manual intervention.
|
||||
@@ -138,7 +138,7 @@ These migrations are best-effort and idempotent; doctor will emit warnings when
|
||||
it leaves any legacy folders behind as backups. The Gateway/CLI also auto-migrates
|
||||
the legacy sessions + agent dir on startup so history/auth/models land in the
|
||||
per-agent path without a manual doctor run. WhatsApp auth is intentionally only
|
||||
migrated via `clawdbot doctor`.
|
||||
migrated via `moltbot doctor`.
|
||||
|
||||
### 4) State integrity checks (session persistence, routing, and safety)
|
||||
The state directory is the operational brainstem. If it vanishes, you lose
|
||||
@@ -160,7 +160,7 @@ Doctor checks:
|
||||
split between installs).
|
||||
- **Remote mode reminder**: if `gateway.mode=remote`, doctor reminds you to run
|
||||
it on the remote host (the state lives there).
|
||||
- **Config file permissions**: warns if `~/.clawdbot/clawdbot.json` is
|
||||
- **Config file permissions**: warns if `~/.clawdbot/moltbot.json` is
|
||||
group/world readable and offers to tighten to `600`.
|
||||
|
||||
### 5) Model auth health (OAuth expiry)
|
||||
@@ -184,9 +184,9 @@ switch to legacy names if the current image is missing.
|
||||
|
||||
### 8) Gateway service migrations and cleanup hints
|
||||
Doctor detects legacy gateway services (launchd/systemd/schtasks) and
|
||||
offers to remove them and install the Clawdbot service using the current gateway
|
||||
offers to remove them and install the Moltbot service using the current gateway
|
||||
port. It can also scan for extra gateway-like services and print cleanup hints.
|
||||
Profile-named Clawdbot gateway services are considered first-class and are not
|
||||
Profile-named Moltbot gateway services are considered first-class and are not
|
||||
flagged as "extra."
|
||||
|
||||
### 9) Security warnings
|
||||
@@ -203,7 +203,7 @@ workspace.
|
||||
|
||||
### 12) Gateway auth checks (local token)
|
||||
Doctor warns when `gateway.auth` is missing on a local gateway and offers to
|
||||
generate a token. Use `clawdbot doctor --generate-gateway-token` to force token
|
||||
generate a token. Use `moltbot doctor --generate-gateway-token` to force token
|
||||
creation in automation.
|
||||
|
||||
### 13) Gateway health check + restart
|
||||
@@ -221,11 +221,11 @@ restart delay). When it finds a mismatch, it recommends an update and can
|
||||
rewrite the service file/task to the current defaults.
|
||||
|
||||
Notes:
|
||||
- `clawdbot doctor` prompts before rewriting supervisor config.
|
||||
- `clawdbot doctor --yes` accepts the default repair prompts.
|
||||
- `clawdbot doctor --repair` applies recommended fixes without prompts.
|
||||
- `clawdbot doctor --repair --force` overwrites custom supervisor configs.
|
||||
- You can always force a full rewrite via `clawdbot gateway install --force`.
|
||||
- `moltbot doctor` prompts before rewriting supervisor config.
|
||||
- `moltbot doctor --yes` accepts the default repair prompts.
|
||||
- `moltbot doctor --repair` applies recommended fixes without prompts.
|
||||
- `moltbot doctor --repair --force` overwrites custom supervisor configs.
|
||||
- You can always force a full rewrite via `moltbot gateway install --force`.
|
||||
|
||||
### 16) Gateway runtime + port diagnostics
|
||||
Doctor inspects the service runtime (PID, last exit status) and warns when the
|
||||
|
||||
@@ -24,5 +24,5 @@ Last updated: 2025-12-11
|
||||
- Other bind failures surface as `GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:<port>: …")`.
|
||||
|
||||
## Operational notes
|
||||
- If the port is occupied by *another* process, the error is the same; free the port or choose another with `clawdbot gateway --port <port>`.
|
||||
- If the port is occupied by *another* process, the error is the same; free the port or choose another with `moltbot gateway --port <port>`.
|
||||
- The macOS app still maintains its own lightweight PID guard before spawning the gateway; the runtime lock is enforced by the WebSocket bind.
|
||||
|
||||
@@ -8,22 +8,22 @@ read_when:
|
||||
Short guide to verify channel connectivity without guessing.
|
||||
|
||||
## Quick checks
|
||||
- `clawdbot status` — local summary: gateway reachability/mode, update hint, linked channel auth age, sessions + recent activity.
|
||||
- `clawdbot status --all` — full local diagnosis (read-only, color, safe to paste for debugging).
|
||||
- `clawdbot status --deep` — also probes the running Gateway (per-channel probes when supported).
|
||||
- `clawdbot health --json` — asks the running Gateway for a full health snapshot (WS-only; no direct Baileys socket).
|
||||
- `moltbot status` — local summary: gateway reachability/mode, update hint, linked channel auth age, sessions + recent activity.
|
||||
- `moltbot status --all` — full local diagnosis (read-only, color, safe to paste for debugging).
|
||||
- `moltbot status --deep` — also probes the running Gateway (per-channel probes when supported).
|
||||
- `moltbot health --json` — asks the running Gateway for a full health snapshot (WS-only; no direct Baileys socket).
|
||||
- Send `/status` as a standalone message in WhatsApp/WebChat to get a status reply without invoking the agent.
|
||||
- Logs: tail `/tmp/clawdbot/clawdbot-*.log` and filter for `web-heartbeat`, `web-reconnect`, `web-auto-reply`, `web-inbound`.
|
||||
- Logs: tail `/tmp/moltbot/moltbot-*.log` and filter for `web-heartbeat`, `web-reconnect`, `web-auto-reply`, `web-inbound`.
|
||||
|
||||
## Deep diagnostics
|
||||
- Creds on disk: `ls -l ~/.clawdbot/credentials/whatsapp/<accountId>/creds.json` (mtime should be recent).
|
||||
- Session store: `ls -l ~/.clawdbot/agents/<agentId>/sessions/sessions.json` (path can be overridden in config). Count and recent recipients are surfaced via `status`.
|
||||
- Relink flow: `clawdbot channels logout && clawdbot channels login --verbose` when status codes 409–515 or `loggedOut` appear in logs. (Note: the QR login flow auto-restarts once for status 515 after pairing.)
|
||||
- Relink flow: `moltbot channels logout && moltbot channels login --verbose` when status codes 409–515 or `loggedOut` appear in logs. (Note: the QR login flow auto-restarts once for status 515 after pairing.)
|
||||
|
||||
## When something fails
|
||||
- `logged out` or status 409–515 → relink with `clawdbot channels logout` then `clawdbot channels login`.
|
||||
- Gateway unreachable → start it: `clawdbot gateway --port 18789` (use `--force` if the port is busy).
|
||||
- `logged out` or status 409–515 → relink with `moltbot channels logout` then `moltbot channels login`.
|
||||
- Gateway unreachable → start it: `moltbot gateway --port 18789` (use `--force` if the port is busy).
|
||||
- No inbound messages → confirm linked phone is online and the sender is allowed (`channels.whatsapp.allowFrom`); for group chats, ensure allowlist + mention rules match (`channels.whatsapp.groups`, `agents.list[].groupChat.mentionPatterns`).
|
||||
|
||||
## Dedicated "health" command
|
||||
`clawdbot health --json` asks the running Gateway for its health snapshot (no direct channel sockets from the CLI). It reports linked creds/auth age when available, per-channel probe summaries, session-store summary, and a probe duration. It exits non-zero if the Gateway is unreachable or the probe fails/timeouts. Use `--timeout <ms>` to override the 10s default.
|
||||
`moltbot health --json` asks the running Gateway for its health snapshot (no direct channel sockets from the CLI). It reports linked creds/auth age when available, per-channel probe summaries, session-store summary, and a probe duration. It exits non-zero if the Gateway is unreachable or the probe fails/timeouts. Use `--timeout <ms>` to override the 10s default.
|
||||
|
||||
@@ -62,7 +62,7 @@ stats” or “verify gateway health”), set `agents.defaults.heartbeat.prompt`
|
||||
## Response contract
|
||||
|
||||
- If nothing needs attention, reply with **`HEARTBEAT_OK`**.
|
||||
- During heartbeat runs, Clawdbot treats `HEARTBEAT_OK` as an ack when it appears
|
||||
- During heartbeat runs, Moltbot treats `HEARTBEAT_OK` as an ack when it appears
|
||||
at the **start or end** of the reply. The token is stripped and the reply is
|
||||
dropped if the remaining content is **≤ `ackMaxChars`** (default: 300).
|
||||
- If `HEARTBEAT_OK` appears in the **middle** of a reply, it is not treated
|
||||
@@ -140,7 +140,7 @@ Example: two agents, only the second agent runs heartbeats.
|
||||
- `includeReasoning`: when enabled, also deliver the separate `Reasoning:` message when available (same shape as `/reasoning on`).
|
||||
- `session`: optional session key for heartbeat runs.
|
||||
- `main` (default): agent main session.
|
||||
- Explicit session key (copy from `clawdbot sessions --json` or the [sessions CLI](/cli/sessions)).
|
||||
- Explicit session key (copy from `moltbot sessions --json` or the [sessions CLI](/cli/sessions)).
|
||||
- Session key formats: see [Sessions](/concepts/session) and [Groups](/concepts/groups).
|
||||
- `target`:
|
||||
- `last` (default): deliver to the last used external channel.
|
||||
@@ -194,7 +194,7 @@ Precedence: per-account → per-channel → channel defaults → built-in defaul
|
||||
- `showAlerts`: sends the alert content when the model returns a non-OK reply.
|
||||
- `useIndicator`: emits indicator events for UI status surfaces.
|
||||
|
||||
If **all three** are false, Clawdbot skips the heartbeat run entirely (no model call).
|
||||
If **all three** are false, Moltbot skips the heartbeat run entirely (no model call).
|
||||
|
||||
### Per-channel vs per-account examples
|
||||
|
||||
@@ -233,7 +233,7 @@ agent to read it. Think of it as your “heartbeat checklist”: small, stable,
|
||||
safe to include every 30 minutes.
|
||||
|
||||
If `HEARTBEAT.md` exists but is effectively empty (only blank lines and markdown
|
||||
headers like `# Heading`), Clawdbot skips the heartbeat run to save API calls.
|
||||
headers like `# Heading`), Moltbot skips the heartbeat run to save API calls.
|
||||
If the file is missing, the heartbeat still runs and the model decides what to do.
|
||||
|
||||
Keep it tiny (short checklist or reminders) to avoid prompt bloat.
|
||||
@@ -269,7 +269,7 @@ Safety note: don’t put secrets (API keys, phone numbers, private tokens) into
|
||||
You can enqueue a system event and trigger an immediate heartbeat with:
|
||||
|
||||
```bash
|
||||
clawdbot system event --text "Check for urgent follow-ups" --mode now
|
||||
moltbot system event --text "Check for urgent follow-ups" --mode now
|
||||
```
|
||||
|
||||
If multiple agents have `heartbeat` configured, a manual wake runs each of those
|
||||
|
||||
@@ -9,20 +9,20 @@ Last updated: 2025-12-09
|
||||
|
||||
## What it is
|
||||
- The always-on process that owns the single Baileys/Telegram connection and the control/event plane.
|
||||
- Replaces the legacy `gateway` command. CLI entry point: `clawdbot gateway`.
|
||||
- Replaces the legacy `gateway` command. CLI entry point: `moltbot gateway`.
|
||||
- Runs until stopped; exits non-zero on fatal errors so the supervisor restarts it.
|
||||
|
||||
## How to run (local)
|
||||
```bash
|
||||
clawdbot gateway --port 18789
|
||||
moltbot gateway --port 18789
|
||||
# for full debug/trace logs in stdio:
|
||||
clawdbot gateway --port 18789 --verbose
|
||||
moltbot gateway --port 18789 --verbose
|
||||
# if the port is busy, terminate listeners then start:
|
||||
clawdbot gateway --force
|
||||
moltbot gateway --force
|
||||
# dev loop (auto-reload on TS changes):
|
||||
pnpm gateway:watch
|
||||
```
|
||||
- Config hot reload watches `~/.clawdbot/clawdbot.json` (or `CLAWDBOT_CONFIG_PATH`).
|
||||
- Config hot reload watches `~/.clawdbot/moltbot.json` (or `CLAWDBOT_CONFIG_PATH`).
|
||||
- Default mode: `gateway.reload.mode="hybrid"` (hot-apply safe changes, restart on critical).
|
||||
- Hot reload uses in-process restart via **SIGUSR1** when needed.
|
||||
- Disable with `gateway.reload.mode="off"`.
|
||||
@@ -31,7 +31,7 @@ pnpm gateway:watch
|
||||
- OpenAI Chat Completions (HTTP): [`/v1/chat/completions`](/gateway/openai-http-api).
|
||||
- OpenResponses (HTTP): [`/v1/responses`](/gateway/openresponses-http-api).
|
||||
- Tools Invoke (HTTP): [`/tools/invoke`](/gateway/tools-invoke-http-api).
|
||||
- Starts a Canvas file server by default on `canvasHost.port` (default `18793`), serving `http://<gateway-host>:18793/__clawdbot__/canvas/` from `~/clawd/canvas`. Disable with `canvasHost.enabled=false` or `CLAWDBOT_SKIP_CANVAS_HOST=1`.
|
||||
- Starts a Canvas file server by default on `canvasHost.port` (default `18793`), serving `http://<gateway-host>:18793/__moltbot__/canvas/` from `~/clawd/canvas`. Disable with `canvasHost.enabled=false` or `CLAWDBOT_SKIP_CANVAS_HOST=1`.
|
||||
- Logs to stdout; use launchd/systemd to keep it alive and rotate logs.
|
||||
- Pass `--verbose` to mirror debug logging (handshakes, req/res, events) from the log file into stdio when troubleshooting.
|
||||
- `--force` uses `lsof` to find listeners on the chosen port, sends SIGTERM, logs what it killed, then starts the gateway (fails fast if `lsof` is missing).
|
||||
@@ -57,11 +57,11 @@ Supported if you isolate state + config and use unique ports. Full guide: [Multi
|
||||
|
||||
Service names are profile-aware:
|
||||
- macOS: `com.clawdbot.<profile>`
|
||||
- Linux: `clawdbot-gateway-<profile>.service`
|
||||
- Windows: `Clawdbot Gateway (<profile>)`
|
||||
- Linux: `moltbot-gateway-<profile>.service`
|
||||
- Windows: `Moltbot Gateway (<profile>)`
|
||||
|
||||
Install metadata is embedded in the service config:
|
||||
- `CLAWDBOT_SERVICE_MARKER=clawdbot`
|
||||
- `CLAWDBOT_SERVICE_MARKER=moltbot`
|
||||
- `CLAWDBOT_SERVICE_KIND=gateway`
|
||||
- `CLAWDBOT_SERVICE_VERSION=<version>`
|
||||
|
||||
@@ -72,16 +72,16 @@ Rescue-Bot Pattern: keep a second Gateway isolated with its own profile, state d
|
||||
Fast path: run a fully-isolated dev instance (config/state/workspace) without touching your primary setup.
|
||||
|
||||
```bash
|
||||
clawdbot --dev setup
|
||||
clawdbot --dev gateway --allow-unconfigured
|
||||
moltbot --dev setup
|
||||
moltbot --dev gateway --allow-unconfigured
|
||||
# then target the dev instance:
|
||||
clawdbot --dev status
|
||||
clawdbot --dev health
|
||||
moltbot --dev status
|
||||
moltbot --dev health
|
||||
```
|
||||
|
||||
Defaults (can be overridden via env/flags/config):
|
||||
- `CLAWDBOT_STATE_DIR=~/.clawdbot-dev`
|
||||
- `CLAWDBOT_CONFIG_PATH=~/.clawdbot-dev/clawdbot.json`
|
||||
- `CLAWDBOT_CONFIG_PATH=~/.clawdbot-dev/moltbot.json`
|
||||
- `CLAWDBOT_GATEWAY_PORT=19001` (Gateway WS + HTTP)
|
||||
- browser control service port = `19003` (derived: `gateway.port+2`, loopback only)
|
||||
- `canvasHost.port=19005` (derived: `gateway.port+4`)
|
||||
@@ -102,14 +102,14 @@ Checklist per instance:
|
||||
|
||||
Service install per profile:
|
||||
```bash
|
||||
clawdbot --profile main gateway install
|
||||
clawdbot --profile rescue gateway install
|
||||
moltbot --profile main gateway install
|
||||
moltbot --profile rescue gateway install
|
||||
```
|
||||
|
||||
Example:
|
||||
```bash
|
||||
CLAWDBOT_CONFIG_PATH=~/.clawdbot/a.json CLAWDBOT_STATE_DIR=~/.clawdbot-a clawdbot gateway --port 19001
|
||||
CLAWDBOT_CONFIG_PATH=~/.clawdbot/b.json CLAWDBOT_STATE_DIR=~/.clawdbot-b clawdbot gateway --port 19002
|
||||
CLAWDBOT_CONFIG_PATH=~/.clawdbot/a.json CLAWDBOT_STATE_DIR=~/.clawdbot-a moltbot gateway --port 19001
|
||||
CLAWDBOT_CONFIG_PATH=~/.clawdbot/b.json CLAWDBOT_STATE_DIR=~/.clawdbot-b moltbot gateway --port 19002
|
||||
```
|
||||
|
||||
## Protocol (operator view)
|
||||
@@ -123,7 +123,7 @@ CLAWDBOT_CONFIG_PATH=~/.clawdbot/b.json CLAWDBOT_STATE_DIR=~/.clawdbot-b clawdbo
|
||||
- `agent` responses are two-stage: first `res` ack `{runId,status:"accepted"}`, then a final `res` `{runId,status:"ok"|"error",summary}` after the run finishes; streamed output arrives as `event:"agent"`.
|
||||
|
||||
## Methods (initial set)
|
||||
- `health` — full health snapshot (same shape as `clawdbot health --json`).
|
||||
- `health` — full health snapshot (same shape as `moltbot health --json`).
|
||||
- `status` — short summary.
|
||||
- `system-presence` — current presence list.
|
||||
- `system-event` — post a presence/system note (structured).
|
||||
@@ -175,26 +175,26 @@ See also: [Presence](/concepts/presence) for how presence is produced/deduped an
|
||||
|
||||
## Supervision (macOS example)
|
||||
- Use launchd to keep the service alive:
|
||||
- Program: path to `clawdbot`
|
||||
- Program: path to `moltbot`
|
||||
- Arguments: `gateway`
|
||||
- KeepAlive: true
|
||||
- StandardOut/Err: file paths or `syslog`
|
||||
- On failure, launchd restarts; fatal misconfig should keep exiting so the operator notices.
|
||||
- LaunchAgents are per-user and require a logged-in session; for headless setups use a custom LaunchDaemon (not shipped).
|
||||
- `clawdbot gateway install` writes `~/Library/LaunchAgents/com.clawdbot.gateway.plist`
|
||||
- `moltbot gateway install` writes `~/Library/LaunchAgents/com.clawdbot.gateway.plist`
|
||||
(or `com.clawdbot.<profile>.plist`).
|
||||
- `clawdbot doctor` audits the LaunchAgent config and can update it to current defaults.
|
||||
- `moltbot doctor` audits the LaunchAgent config and can update it to current defaults.
|
||||
|
||||
## Gateway service management (CLI)
|
||||
|
||||
Use the Gateway CLI for install/start/stop/restart/status:
|
||||
|
||||
```bash
|
||||
clawdbot gateway status
|
||||
clawdbot gateway install
|
||||
clawdbot gateway stop
|
||||
clawdbot gateway restart
|
||||
clawdbot logs --follow
|
||||
moltbot gateway status
|
||||
moltbot gateway install
|
||||
moltbot gateway stop
|
||||
moltbot gateway restart
|
||||
moltbot logs --follow
|
||||
```
|
||||
|
||||
Notes:
|
||||
@@ -206,37 +206,37 @@ Notes:
|
||||
- `gateway status` prints config path + probe target to avoid “localhost vs LAN bind” confusion and profile mismatches.
|
||||
- `gateway status` includes the last gateway error line when the service looks running but the port is closed.
|
||||
- `logs` tails the Gateway file log via RPC (no manual `tail`/`grep` needed).
|
||||
- If other gateway-like services are detected, the CLI warns unless they are Clawdbot profile services.
|
||||
- If other gateway-like services are detected, the CLI warns unless they are Moltbot profile services.
|
||||
We still recommend **one gateway per machine** for most setups; use isolated profiles/ports for redundancy or a rescue bot. See [Multiple gateways](/gateway/multiple-gateways).
|
||||
- Cleanup: `clawdbot gateway uninstall` (current service) and `clawdbot doctor` (legacy migrations).
|
||||
- `gateway install` is a no-op when already installed; use `clawdbot gateway install --force` to reinstall (profile/env/path changes).
|
||||
- Cleanup: `moltbot gateway uninstall` (current service) and `moltbot doctor` (legacy migrations).
|
||||
- `gateway install` is a no-op when already installed; use `moltbot gateway install --force` to reinstall (profile/env/path changes).
|
||||
|
||||
Bundled mac app:
|
||||
- Clawdbot.app can bundle a Node-based gateway relay and install a per-user LaunchAgent labeled
|
||||
- Moltbot.app can bundle a Node-based gateway relay and install a per-user LaunchAgent labeled
|
||||
`com.clawdbot.gateway` (or `com.clawdbot.<profile>`).
|
||||
- To stop it cleanly, use `clawdbot gateway stop` (or `launchctl bootout gui/$UID/com.clawdbot.gateway`).
|
||||
- To restart, use `clawdbot gateway restart` (or `launchctl kickstart -k gui/$UID/com.clawdbot.gateway`).
|
||||
- `launchctl` only works if the LaunchAgent is installed; otherwise use `clawdbot gateway install` first.
|
||||
- To stop it cleanly, use `moltbot gateway stop` (or `launchctl bootout gui/$UID/com.clawdbot.gateway`).
|
||||
- To restart, use `moltbot gateway restart` (or `launchctl kickstart -k gui/$UID/com.clawdbot.gateway`).
|
||||
- `launchctl` only works if the LaunchAgent is installed; otherwise use `moltbot gateway install` first.
|
||||
- Replace the label with `com.clawdbot.<profile>` when running a named profile.
|
||||
|
||||
## Supervision (systemd user unit)
|
||||
Clawdbot installs a **systemd user service** by default on Linux/WSL2. We
|
||||
Moltbot installs a **systemd user service** by default on Linux/WSL2. We
|
||||
recommend user services for single-user machines (simpler env, per-user config).
|
||||
Use a **system service** for multi-user or always-on servers (no lingering
|
||||
required, shared supervision).
|
||||
|
||||
`clawdbot gateway install` writes the user unit. `clawdbot doctor` audits the
|
||||
`moltbot gateway install` writes the user unit. `moltbot doctor` audits the
|
||||
unit and can update it to match the current recommended defaults.
|
||||
|
||||
Create `~/.config/systemd/user/clawdbot-gateway[-<profile>].service`:
|
||||
Create `~/.config/systemd/user/moltbot-gateway[-<profile>].service`:
|
||||
```
|
||||
[Unit]
|
||||
Description=Clawdbot Gateway (profile: <profile>, v<version>)
|
||||
Description=Moltbot Gateway (profile: <profile>, v<version>)
|
||||
After=network-online.target
|
||||
Wants=network-online.target
|
||||
|
||||
[Service]
|
||||
ExecStart=/usr/local/bin/clawdbot gateway --port 18789
|
||||
ExecStart=/usr/local/bin/moltbot gateway --port 18789
|
||||
Restart=always
|
||||
RestartSec=5
|
||||
Environment=CLAWDBOT_GATEWAY_TOKEN=
|
||||
@@ -252,16 +252,16 @@ sudo loginctl enable-linger youruser
|
||||
Onboarding runs this on Linux/WSL2 (may prompt for sudo; writes `/var/lib/systemd/linger`).
|
||||
Then enable the service:
|
||||
```
|
||||
systemctl --user enable --now clawdbot-gateway[-<profile>].service
|
||||
systemctl --user enable --now moltbot-gateway[-<profile>].service
|
||||
```
|
||||
|
||||
**Alternative (system service)** - for always-on or multi-user servers, you can
|
||||
install a systemd **system** unit instead of a user unit (no lingering needed).
|
||||
Create `/etc/systemd/system/clawdbot-gateway[-<profile>].service` (copy the unit above,
|
||||
Create `/etc/systemd/system/moltbot-gateway[-<profile>].service` (copy the unit above,
|
||||
switch `WantedBy=multi-user.target`, set `User=` + `WorkingDirectory=`), then:
|
||||
```
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable --now clawdbot-gateway[-<profile>].service
|
||||
sudo systemctl enable --now moltbot-gateway[-<profile>].service
|
||||
```
|
||||
|
||||
## Windows (WSL2)
|
||||
@@ -280,13 +280,13 @@ Windows installs should use **WSL2** and follow the Linux systemd section above.
|
||||
- Graceful shutdown: emit `shutdown` event before closing; clients must handle close + reconnect.
|
||||
|
||||
## CLI helpers
|
||||
- `clawdbot gateway health|status` — request health/status over the Gateway WS.
|
||||
- `clawdbot message send --target <num> --message "hi" [--media ...]` — send via Gateway (idempotent for WhatsApp).
|
||||
- `clawdbot agent --message "hi" --to <num>` — run an agent turn (waits for final by default).
|
||||
- `clawdbot gateway call <method> --params '{"k":"v"}'` — raw method invoker for debugging.
|
||||
- `clawdbot gateway stop|restart` — stop/restart the supervised gateway service (launchd/systemd).
|
||||
- `moltbot gateway health|status` — request health/status over the Gateway WS.
|
||||
- `moltbot message send --target <num> --message "hi" [--media ...]` — send via Gateway (idempotent for WhatsApp).
|
||||
- `moltbot agent --message "hi" --to <num>` — run an agent turn (waits for final by default).
|
||||
- `moltbot gateway call <method> --params '{"k":"v"}'` — raw method invoker for debugging.
|
||||
- `moltbot gateway stop|restart` — stop/restart the supervised gateway service (launchd/systemd).
|
||||
- Gateway helper subcommands assume a running gateway on `--url`; they no longer auto-spawn one.
|
||||
|
||||
## Migration guidance
|
||||
- Retire uses of `clawdbot gateway` and the legacy TCP control port.
|
||||
- Retire uses of `moltbot gateway` and the legacy TCP control port.
|
||||
- Update clients to speak the WS protocol with mandatory connect and structured presence.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
summary: "Run Clawdbot on local LLMs (LM Studio, vLLM, LiteLLM, custom OpenAI endpoints)"
|
||||
summary: "Run Moltbot on local LLMs (LM Studio, vLLM, LiteLLM, custom OpenAI endpoints)"
|
||||
read_when:
|
||||
- You want to serve models from your own GPU box
|
||||
- You are wiring LM Studio or an OpenAI-compatible proxy
|
||||
@@ -7,7 +7,7 @@ read_when:
|
||||
---
|
||||
# Local models
|
||||
|
||||
Local is doable, but Clawdbot expects large context + strong defenses against prompt injection. Small cards truncate context and leak safety. Aim high: **≥2 maxed-out Mac Studios or equivalent GPU rig (~$30k+)**. A single **24 GB** GPU works only for lighter prompts with higher latency. Use the **largest / full-size model variant you can run**; aggressively quantized or “small” checkpoints raise prompt-injection risk (see [Security](/gateway/security)).
|
||||
Local is doable, but Moltbot expects large context + strong defenses against prompt injection. Small cards truncate context and leak safety. Aim high: **≥2 maxed-out Mac Studios or equivalent GPU rig (~$30k+)**. A single **24 GB** GPU works only for lighter prompts with higher latency. Use the **largest / full-size model variant you can run**; aggressively quantized or “small” checkpoints raise prompt-injection risk (see [Security](/gateway/security)).
|
||||
|
||||
## Recommended: LM Studio + MiniMax M2.1 (Responses API, full-size)
|
||||
|
||||
|
||||
@@ -9,16 +9,16 @@ read_when:
|
||||
|
||||
For a user-facing overview (CLI + Control UI + config), see [/logging](/logging).
|
||||
|
||||
Clawdbot has two log “surfaces”:
|
||||
Moltbot has two log “surfaces”:
|
||||
|
||||
- **Console output** (what you see in the terminal / Debug UI).
|
||||
- **File logs** (JSON lines) written by the gateway logger.
|
||||
|
||||
## File-based logger
|
||||
|
||||
- Default rolling log file is under `/tmp/clawdbot/` (one file per day): `clawdbot-YYYY-MM-DD.log`
|
||||
- Default rolling log file is under `/tmp/moltbot/` (one file per day): `moltbot-YYYY-MM-DD.log`
|
||||
- Date uses the gateway host's local timezone.
|
||||
- The log file path and level can be configured via `~/.clawdbot/clawdbot.json`:
|
||||
- The log file path and level can be configured via `~/.clawdbot/moltbot.json`:
|
||||
- `logging.file`
|
||||
- `logging.level`
|
||||
|
||||
@@ -28,7 +28,7 @@ The Control UI Logs tab tails this file via the gateway (`logs.tail`).
|
||||
CLI can do the same:
|
||||
|
||||
```bash
|
||||
clawdbot logs --follow
|
||||
moltbot logs --follow
|
||||
```
|
||||
|
||||
**Verbose vs. log levels**
|
||||
@@ -72,7 +72,7 @@ The gateway prints WebSocket protocol logs in two modes:
|
||||
|
||||
### WS log style
|
||||
|
||||
`clawdbot gateway` supports a per-gateway style switch:
|
||||
`moltbot gateway` supports a per-gateway style switch:
|
||||
|
||||
- `--ws-log auto` (default): normal mode is optimized; verbose mode uses compact output
|
||||
- `--ws-log compact`: compact output (paired request/response) when verbose
|
||||
@@ -83,13 +83,13 @@ Examples:
|
||||
|
||||
```bash
|
||||
# optimized (only errors/slow)
|
||||
clawdbot gateway
|
||||
moltbot gateway
|
||||
|
||||
# show all WS traffic (paired)
|
||||
clawdbot gateway --verbose --ws-log compact
|
||||
moltbot gateway --verbose --ws-log compact
|
||||
|
||||
# show all WS traffic (full meta)
|
||||
clawdbot gateway --verbose --ws-log full
|
||||
moltbot gateway --verbose --ws-log full
|
||||
```
|
||||
|
||||
## Console formatting (subsystem logging)
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
summary: "Run multiple Clawdbot Gateways on one host (isolation, ports, and profiles)"
|
||||
summary: "Run multiple Moltbot Gateways on one host (isolation, ports, and profiles)"
|
||||
read_when:
|
||||
- Running more than one Gateway on the same machine
|
||||
- You need isolated config/state/ports per Gateway
|
||||
@@ -23,18 +23,18 @@ Profiles auto-scope `CLAWDBOT_STATE_DIR` + `CLAWDBOT_CONFIG_PATH` and suffix ser
|
||||
|
||||
```bash
|
||||
# main
|
||||
clawdbot --profile main setup
|
||||
clawdbot --profile main gateway --port 18789
|
||||
moltbot --profile main setup
|
||||
moltbot --profile main gateway --port 18789
|
||||
|
||||
# rescue
|
||||
clawdbot --profile rescue setup
|
||||
clawdbot --profile rescue gateway --port 19001
|
||||
moltbot --profile rescue setup
|
||||
moltbot --profile rescue gateway --port 19001
|
||||
```
|
||||
|
||||
Per-profile services:
|
||||
```bash
|
||||
clawdbot --profile main gateway install
|
||||
clawdbot --profile rescue gateway install
|
||||
moltbot --profile main gateway install
|
||||
moltbot --profile rescue gateway install
|
||||
```
|
||||
|
||||
## Rescue-bot guide
|
||||
@@ -54,11 +54,11 @@ Port spacing: leave at least 20 ports between base ports so the derived browser/
|
||||
```bash
|
||||
# Main bot (existing or fresh, without --profile param)
|
||||
# Runs on port 18789 + Chrome CDC/Canvas/... Ports
|
||||
clawdbot onboard
|
||||
clawdbot gateway install
|
||||
moltbot onboard
|
||||
moltbot gateway install
|
||||
|
||||
# Rescue bot (isolated profile + ports)
|
||||
clawdbot --profile rescue onboard
|
||||
moltbot --profile rescue onboard
|
||||
# Notes:
|
||||
# - workspace name will be postfixed with -rescue per default
|
||||
# - Port should be at least 18789 + 20 Ports,
|
||||
@@ -66,7 +66,7 @@ clawdbot --profile rescue onboard
|
||||
# - rest of the onboarding is the same as normal
|
||||
|
||||
# To install the service (if not happened automatically during onboarding)
|
||||
clawdbot --profile rescue gateway install
|
||||
moltbot --profile rescue gateway install
|
||||
```
|
||||
|
||||
## Port mapping (derived)
|
||||
@@ -91,17 +91,17 @@ If you override any of these in config or env, you must keep them unique per ins
|
||||
```bash
|
||||
CLAWDBOT_CONFIG_PATH=~/.clawdbot/main.json \
|
||||
CLAWDBOT_STATE_DIR=~/.clawdbot-main \
|
||||
clawdbot gateway --port 18789
|
||||
moltbot gateway --port 18789
|
||||
|
||||
CLAWDBOT_CONFIG_PATH=~/.clawdbot/rescue.json \
|
||||
CLAWDBOT_STATE_DIR=~/.clawdbot-rescue \
|
||||
clawdbot gateway --port 19001
|
||||
moltbot gateway --port 19001
|
||||
```
|
||||
|
||||
## Quick checks
|
||||
|
||||
```bash
|
||||
clawdbot --profile main status
|
||||
clawdbot --profile rescue status
|
||||
clawdbot --profile rescue browser status
|
||||
moltbot --profile main status
|
||||
moltbot --profile rescue status
|
||||
moltbot --profile rescue browser status
|
||||
```
|
||||
|
||||
@@ -5,14 +5,14 @@ read_when:
|
||||
---
|
||||
# OpenAI Chat Completions (HTTP)
|
||||
|
||||
Clawdbot’s Gateway can serve a small OpenAI-compatible Chat Completions endpoint.
|
||||
Moltbot’s Gateway can serve a small OpenAI-compatible Chat Completions endpoint.
|
||||
|
||||
This endpoint is **disabled by default**. Enable it in config first.
|
||||
|
||||
- `POST /v1/chat/completions`
|
||||
- Same port as the Gateway (WS + HTTP multiplex): `http://<gateway-host>:<port>/v1/chat/completions`
|
||||
|
||||
Under the hood, requests are executed as a normal Gateway agent run (same codepath as `clawdbot agent`), so routing/permissions/config match your Gateway.
|
||||
Under the hood, requests are executed as a normal Gateway agent run (same codepath as `moltbot agent`), so routing/permissions/config match your Gateway.
|
||||
|
||||
## Authentication
|
||||
|
||||
@@ -28,15 +28,15 @@ Notes:
|
||||
|
||||
No custom headers required: encode the agent id in the OpenAI `model` field:
|
||||
|
||||
- `model: "clawdbot:<agentId>"` (example: `"clawdbot:main"`, `"clawdbot:beta"`)
|
||||
- `model: "moltbot:<agentId>"` (example: `"moltbot:main"`, `"moltbot:beta"`)
|
||||
- `model: "agent:<agentId>"` (alias)
|
||||
|
||||
Or target a specific Clawdbot agent by header:
|
||||
Or target a specific Moltbot agent by header:
|
||||
|
||||
- `x-clawdbot-agent-id: <agentId>` (default: `main`)
|
||||
- `x-moltbot-agent-id: <agentId>` (default: `main`)
|
||||
|
||||
Advanced:
|
||||
- `x-clawdbot-session-key: <sessionKey>` to fully control session routing.
|
||||
- `x-moltbot-session-key: <sessionKey>` to fully control session routing.
|
||||
|
||||
## Enabling the endpoint
|
||||
|
||||
@@ -91,9 +91,9 @@ Non-streaming:
|
||||
curl -sS http://127.0.0.1:18789/v1/chat/completions \
|
||||
-H 'Authorization: Bearer YOUR_TOKEN' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'x-clawdbot-agent-id: main' \
|
||||
-H 'x-moltbot-agent-id: main' \
|
||||
-d '{
|
||||
"model": "clawdbot",
|
||||
"model": "moltbot",
|
||||
"messages": [{"role":"user","content":"hi"}]
|
||||
}'
|
||||
```
|
||||
@@ -103,9 +103,9 @@ Streaming:
|
||||
curl -N http://127.0.0.1:18789/v1/chat/completions \
|
||||
-H 'Authorization: Bearer YOUR_TOKEN' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'x-clawdbot-agent-id: main' \
|
||||
-H 'x-moltbot-agent-id: main' \
|
||||
-d '{
|
||||
"model": "clawdbot",
|
||||
"model": "moltbot",
|
||||
"stream": true,
|
||||
"messages": [{"role":"user","content":"hi"}]
|
||||
}'
|
||||
|
||||
@@ -6,7 +6,7 @@ read_when:
|
||||
---
|
||||
# OpenResponses API (HTTP)
|
||||
|
||||
Clawdbot’s Gateway can serve an OpenResponses-compatible `POST /v1/responses` endpoint.
|
||||
Moltbot’s Gateway can serve an OpenResponses-compatible `POST /v1/responses` endpoint.
|
||||
|
||||
This endpoint is **disabled by default**. Enable it in config first.
|
||||
|
||||
@@ -14,7 +14,7 @@ This endpoint is **disabled by default**. Enable it in config first.
|
||||
- Same port as the Gateway (WS + HTTP multiplex): `http://<gateway-host>:<port>/v1/responses`
|
||||
|
||||
Under the hood, requests are executed as a normal Gateway agent run (same codepath as
|
||||
`clawdbot agent`), so routing/permissions/config match your Gateway.
|
||||
`moltbot agent`), so routing/permissions/config match your Gateway.
|
||||
|
||||
## Authentication
|
||||
|
||||
@@ -30,15 +30,15 @@ Notes:
|
||||
|
||||
No custom headers required: encode the agent id in the OpenResponses `model` field:
|
||||
|
||||
- `model: "clawdbot:<agentId>"` (example: `"clawdbot:main"`, `"clawdbot:beta"`)
|
||||
- `model: "moltbot:<agentId>"` (example: `"moltbot:main"`, `"moltbot:beta"`)
|
||||
- `model: "agent:<agentId>"` (alias)
|
||||
|
||||
Or target a specific Clawdbot agent by header:
|
||||
Or target a specific Moltbot agent by header:
|
||||
|
||||
- `x-clawdbot-agent-id: <agentId>` (default: `main`)
|
||||
- `x-moltbot-agent-id: <agentId>` (default: `main`)
|
||||
|
||||
Advanced:
|
||||
- `x-clawdbot-session-key: <sessionKey>` to fully control session routing.
|
||||
- `x-moltbot-session-key: <sessionKey>` to fully control session routing.
|
||||
|
||||
## Enabling the endpoint
|
||||
|
||||
@@ -277,9 +277,9 @@ Non-streaming:
|
||||
curl -sS http://127.0.0.1:18789/v1/responses \
|
||||
-H 'Authorization: Bearer YOUR_TOKEN' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'x-clawdbot-agent-id: main' \
|
||||
-H 'x-moltbot-agent-id: main' \
|
||||
-d '{
|
||||
"model": "clawdbot",
|
||||
"model": "moltbot",
|
||||
"input": "hi"
|
||||
}'
|
||||
```
|
||||
@@ -289,9 +289,9 @@ Streaming:
|
||||
curl -N http://127.0.0.1:18789/v1/responses \
|
||||
-H 'Authorization: Bearer YOUR_TOKEN' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'x-clawdbot-agent-id: main' \
|
||||
-H 'x-moltbot-agent-id: main' \
|
||||
-d '{
|
||||
"model": "clawdbot",
|
||||
"model": "moltbot",
|
||||
"stream": true,
|
||||
"input": "hi"
|
||||
}'
|
||||
|
||||
@@ -35,11 +35,11 @@ Pending requests expire automatically after **5 minutes**.
|
||||
## CLI workflow (headless friendly)
|
||||
|
||||
```bash
|
||||
clawdbot nodes pending
|
||||
clawdbot nodes approve <requestId>
|
||||
clawdbot nodes reject <requestId>
|
||||
clawdbot nodes status
|
||||
clawdbot nodes rename --node <id|name|ip> --name "Living Room iPad"
|
||||
moltbot nodes pending
|
||||
moltbot nodes approve <requestId>
|
||||
moltbot nodes reject <requestId>
|
||||
moltbot nodes status
|
||||
moltbot nodes rename --node <id|name|ip> --name "Living Room iPad"
|
||||
```
|
||||
|
||||
`nodes status` shows paired/connected nodes and their capabilities.
|
||||
|
||||
@@ -9,7 +9,7 @@ read_when:
|
||||
# Gateway protocol (WebSocket)
|
||||
|
||||
The Gateway WS protocol is the **single control plane + node transport** for
|
||||
Clawdbot. All clients (CLI, web UI, macOS app, iOS/Android nodes, headless
|
||||
Moltbot. All clients (CLI, web UI, macOS app, iOS/Android nodes, headless
|
||||
nodes) connect over WebSocket and declare their **role** + **scope** at
|
||||
handshake time.
|
||||
|
||||
@@ -53,7 +53,7 @@ Client → Gateway:
|
||||
"permissions": {},
|
||||
"auth": { "token": "…" },
|
||||
"locale": "en-US",
|
||||
"userAgent": "clawdbot-cli/1.2.3",
|
||||
"userAgent": "moltbot-cli/1.2.3",
|
||||
"device": {
|
||||
"id": "device_fingerprint",
|
||||
"publicKey": "…",
|
||||
@@ -111,7 +111,7 @@ When a device token is issued, `hello-ok` also includes:
|
||||
"permissions": { "camera.capture": true, "screen.record": false },
|
||||
"auth": { "token": "…" },
|
||||
"locale": "en-US",
|
||||
"userAgent": "clawdbot-ios/1.2.3",
|
||||
"userAgent": "moltbot-ios/1.2.3",
|
||||
"device": {
|
||||
"id": "device_fingerprint",
|
||||
"publicKey": "…",
|
||||
|
||||
@@ -1,11 +1,11 @@
|
||||
---
|
||||
summary: "SSH tunnel setup for Clawdbot.app connecting to a remote gateway"
|
||||
summary: "SSH tunnel setup for Moltbot.app connecting to a remote gateway"
|
||||
read_when: "Connecting the macOS app to a remote gateway over SSH"
|
||||
---
|
||||
|
||||
# Running Clawdbot.app with a Remote Gateway
|
||||
# Running Moltbot.app with a Remote Gateway
|
||||
|
||||
Clawdbot.app uses SSH tunneling to connect to a remote gateway. This guide shows you how to set it up.
|
||||
Moltbot.app uses SSH tunneling to connect to a remote gateway. This guide shows you how to set it up.
|
||||
|
||||
## Overview
|
||||
|
||||
@@ -13,7 +13,7 @@ Clawdbot.app uses SSH tunneling to connect to a remote gateway. This guide shows
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Client Machine │
|
||||
│ │
|
||||
│ Clawdbot.app ──► ws://127.0.0.1:18789 (local port) │
|
||||
│ Moltbot.app ──► ws://127.0.0.1:18789 (local port) │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ SSH Tunnel ────────────────────────────────────────────────│
|
||||
@@ -65,11 +65,11 @@ launchctl setenv CLAWDBOT_GATEWAY_TOKEN "<your-token>"
|
||||
ssh -N remote-gateway &
|
||||
```
|
||||
|
||||
### Step 5: Restart Clawdbot.app
|
||||
### Step 5: Restart Moltbot.app
|
||||
|
||||
```bash
|
||||
# Quit Clawdbot.app (⌘Q), then reopen:
|
||||
open /path/to/Clawdbot.app
|
||||
# Quit Moltbot.app (⌘Q), then reopen:
|
||||
open /path/to/Moltbot.app
|
||||
```
|
||||
|
||||
The app will now connect to the remote gateway through the SSH tunnel.
|
||||
@@ -150,4 +150,4 @@ launchctl bootout gui/$UID/com.clawdbot.ssh-tunnel
|
||||
| `KeepAlive` | Automatically restarts tunnel if it crashes |
|
||||
| `RunAtLoad` | Starts tunnel when the agent loads |
|
||||
|
||||
Clawdbot.app connects to `ws://127.0.0.1:18789` on your client machine. The SSH tunnel forwards that connection to port 18789 on the remote machine where the Gateway is running.
|
||||
Moltbot.app connects to `ws://127.0.0.1:18789` on your client machine. The SSH tunnel forwards that connection to port 18789 on the remote machine where the Gateway is running.
|
||||
|
||||
@@ -34,7 +34,7 @@ This is ideal when your laptop sleeps often but you want the agent always-on.
|
||||
|
||||
The laptop does **not** run the agent. It connects remotely:
|
||||
|
||||
- Use the macOS app’s **Remote over SSH** mode (Settings → General → “Clawdbot runs”).
|
||||
- Use the macOS app’s **Remote over SSH** mode (Settings → General → “Moltbot runs”).
|
||||
- The app opens and manages the tunnel, so WebChat + health checks “just work.”
|
||||
|
||||
Runbook: [macOS remote access](/platforms/mac/remote).
|
||||
@@ -71,8 +71,8 @@ ssh -N -L 18789:127.0.0.1:18789 user@host
|
||||
```
|
||||
|
||||
With the tunnel up:
|
||||
- `clawdbot health` and `clawdbot status --deep` now reach the remote gateway via `ws://127.0.0.1:18789`.
|
||||
- `clawdbot gateway {status,health,send,agent,call}` can also target the forwarded URL via `--url` when needed.
|
||||
- `moltbot health` and `moltbot status --deep` now reach the remote gateway via `ws://127.0.0.1:18789`.
|
||||
- `moltbot gateway {status,health,send,agent,call}` can also target the forwarded URL via `--url` when needed.
|
||||
|
||||
Note: replace `18789` with your configured `gateway.port` (or `--port`/`CLAWDBOT_GATEWAY_PORT`).
|
||||
|
||||
|
||||
@@ -7,7 +7,7 @@ status: active
|
||||
|
||||
# Sandbox vs Tool Policy vs Elevated
|
||||
|
||||
Clawdbot has three related (but different) controls:
|
||||
Moltbot has three related (but different) controls:
|
||||
|
||||
1. **Sandbox** (`agents.defaults.sandbox.*` / `agents.list[].sandbox.*`) decides **where tools run** (Docker vs host).
|
||||
2. **Tool policy** (`tools.*`, `tools.sandbox.tools.*`, `agents.list[].tools.*`) decides **which tools are available/allowed**.
|
||||
@@ -15,13 +15,13 @@ Clawdbot has three related (but different) controls:
|
||||
|
||||
## Quick debug
|
||||
|
||||
Use the inspector to see what Clawdbot is *actually* doing:
|
||||
Use the inspector to see what Moltbot is *actually* doing:
|
||||
|
||||
```bash
|
||||
clawdbot sandbox explain
|
||||
clawdbot sandbox explain --session agent:main:main
|
||||
clawdbot sandbox explain --agent work
|
||||
clawdbot sandbox explain --json
|
||||
moltbot sandbox explain
|
||||
moltbot sandbox explain --session agent:main:main
|
||||
moltbot sandbox explain --agent work
|
||||
moltbot sandbox explain --json
|
||||
```
|
||||
|
||||
It prints:
|
||||
@@ -88,7 +88,7 @@ Available groups:
|
||||
- `group:automation`: `cron`, `gateway`
|
||||
- `group:messaging`: `message`
|
||||
- `group:nodes`: `nodes`
|
||||
- `group:clawdbot`: all built-in Clawdbot tools (excludes provider plugins)
|
||||
- `group:moltbot`: all built-in Moltbot tools (excludes provider plugins)
|
||||
|
||||
## Elevated: exec-only “run on host”
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
summary: "How Clawdbot sandboxing works: modes, scopes, workspace access, and images"
|
||||
summary: "How Moltbot sandboxing works: modes, scopes, workspace access, and images"
|
||||
title: Sandboxing
|
||||
read_when: "You want a dedicated explanation of sandboxing or need to tune agents.defaults.sandbox."
|
||||
status: active
|
||||
@@ -7,7 +7,7 @@ status: active
|
||||
|
||||
# Sandboxing
|
||||
|
||||
Clawdbot can run **tools inside Docker containers** to reduce blast radius.
|
||||
Moltbot can run **tools inside Docker containers** to reduce blast radius.
|
||||
This is **optional** and controlled by configuration (`agents.defaults.sandbox` or
|
||||
`agents.list[].sandbox`). If sandboxing is off, tools run on the host.
|
||||
The Gateway stays on the host; tool execution runs in an isolated sandbox
|
||||
@@ -52,7 +52,7 @@ Group/channel sessions use their own keys, so they count as non-main and will be
|
||||
|
||||
Inbound media is copied into the active sandbox workspace (`media/inbound/*`).
|
||||
Skills note: the `read` tool is sandbox-rooted. With `workspaceAccess: "none"`,
|
||||
Clawdbot mirrors eligible skills into the sandbox workspace (`.../skills`) so
|
||||
Moltbot mirrors eligible skills into the sandbox workspace (`.../skills`) so
|
||||
they can be read. With `"rw"`, workspace skills are readable from
|
||||
`/workspace/skills`.
|
||||
|
||||
@@ -98,7 +98,7 @@ Security notes:
|
||||
- See [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) for how binds interact with tool policy and elevated exec.
|
||||
|
||||
## Images + setup
|
||||
Default image: `clawdbot-sandbox:bookworm-slim`
|
||||
Default image: `moltbot-sandbox:bookworm-slim`
|
||||
|
||||
Build it once:
|
||||
```bash
|
||||
@@ -146,7 +146,7 @@ globally or per-agent, sandboxing doesn’t bring it back.
|
||||
`exec`, use tool policy deny (see [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated)).
|
||||
|
||||
Debugging:
|
||||
- Use `clawdbot sandbox explain` to inspect effective sandbox mode, tool policy, and fix-it config keys.
|
||||
- Use `moltbot sandbox explain` to inspect effective sandbox mode, tool policy, and fix-it config keys.
|
||||
- See [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) for the “why is this blocked?” mental model.
|
||||
Keep it locked down.
|
||||
|
||||
|
||||
@@ -1,14 +1,14 @@
|
||||
---
|
||||
title: Formal Verification (Security Models)
|
||||
summary: Machine-checked security models for Clawdbot’s highest-risk paths.
|
||||
summary: Machine-checked security models for Moltbot’s highest-risk paths.
|
||||
permalink: /gateway/security/formal-verification/
|
||||
---
|
||||
|
||||
# Formal Verification (Security Models)
|
||||
|
||||
This page tracks Clawdbot’s **formal security models** (TLA+/TLC today; more as needed).
|
||||
This page tracks Moltbot’s **formal security models** (TLA+/TLC today; more as needed).
|
||||
|
||||
**Goal (north star):** provide a machine-checked argument that Clawdbot enforces its
|
||||
**Goal (north star):** provide a machine-checked argument that Moltbot enforces its
|
||||
intended security policy (authorization, session isolation, tool gating, and
|
||||
misconfiguration safety), under explicit assumptions.
|
||||
|
||||
@@ -16,11 +16,11 @@ misconfiguration safety), under explicit assumptions.
|
||||
- Each claim has a runnable model-check over a finite state space.
|
||||
- Many claims have a paired **negative model** that produces a counterexample trace for a realistic bug class.
|
||||
|
||||
**What this is not (yet):** a proof that “Clawdbot is secure in all respects” or that the full TypeScript implementation is correct.
|
||||
**What this is not (yet):** a proof that “Moltbot is secure in all respects” or that the full TypeScript implementation is correct.
|
||||
|
||||
## Where the models live
|
||||
|
||||
Models are maintained in a separate repo: [vignesh07/clawdbot-formal-models](https://github.com/vignesh07/clawdbot-formal-models).
|
||||
Models are maintained in a separate repo: [vignesh07/moltbot-formal-models](https://github.com/vignesh07/moltbot-formal-models).
|
||||
|
||||
## Important caveats
|
||||
|
||||
@@ -37,8 +37,8 @@ Today, results are reproduced by cloning the models repo locally and running TLC
|
||||
Getting started:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/vignesh07/clawdbot-formal-models
|
||||
cd clawdbot-formal-models
|
||||
git clone https://github.com/vignesh07/moltbot-formal-models
|
||||
cd moltbot-formal-models
|
||||
|
||||
# Java 11+ required (TLC runs on the JVM).
|
||||
# The repo vendors a pinned `tla2tools.jar` (TLA+ tools) and provides `bin/tlc` + Make targets.
|
||||
|
||||
@@ -5,16 +5,16 @@ read_when:
|
||||
---
|
||||
# Security 🔒
|
||||
|
||||
## Quick check: `clawdbot security audit`
|
||||
## Quick check: `moltbot security audit`
|
||||
|
||||
See also: [Formal Verification (Security Models)](/security/formal-verification/)
|
||||
|
||||
Run this regularly (especially after changing config or exposing network surfaces):
|
||||
|
||||
```bash
|
||||
clawdbot security audit
|
||||
clawdbot security audit --deep
|
||||
clawdbot security audit --fix
|
||||
moltbot security audit
|
||||
moltbot security audit --deep
|
||||
moltbot security audit --fix
|
||||
```
|
||||
|
||||
It flags common footguns (Gateway auth exposure, browser control exposure, elevated allowlists, filesystem permissions).
|
||||
@@ -26,7 +26,7 @@ It flags common footguns (Gateway auth exposure, browser control exposure, eleva
|
||||
|
||||
Running an AI agent with shell access on your machine is... *spicy*. Here’s how to not get pwned.
|
||||
|
||||
Clawdbot is both a product and an experiment: you’re wiring frontier-model behavior into real messaging surfaces and real tools. **There is no “perfectly secure” setup.** The goal is to be deliberate about:
|
||||
Moltbot is both a product and an experiment: you’re wiring frontier-model behavior into real messaging surfaces and real tools. **There is no “perfectly secure” setup.** The goal is to be deliberate about:
|
||||
- who can talk to your bot
|
||||
- where the bot is allowed to act
|
||||
- what the bot can touch
|
||||
@@ -43,7 +43,7 @@ Start with the smallest access that still works, then widen it as you gain confi
|
||||
- **Plugins** (extensions exist without an explicit allowlist).
|
||||
- **Model hygiene** (warn when configured models look legacy; not a hard block).
|
||||
|
||||
If you run `--deep`, Clawdbot also attempts a best-effort live Gateway probe.
|
||||
If you run `--deep`, Moltbot also attempts a best-effort live Gateway probe.
|
||||
|
||||
## Credential storage map
|
||||
|
||||
@@ -79,7 +79,7 @@ For break-glass scenarios only, `gateway.controlUi.dangerouslyDisableDeviceAuth`
|
||||
disables device identity checks entirely. This is a severe security downgrade;
|
||||
keep it off unless you are actively debugging and can revert quickly.
|
||||
|
||||
`clawdbot security audit` warns when this setting is enabled.
|
||||
`moltbot security audit` warns when this setting is enabled.
|
||||
|
||||
## Reverse Proxy Configuration
|
||||
|
||||
@@ -100,7 +100,7 @@ When `trustedProxies` is configured, the Gateway will use `X-Forwarded-For` head
|
||||
|
||||
## Local session logs live on disk
|
||||
|
||||
Clawdbot stores session transcripts on disk under `~/.clawdbot/agents/<agentId>/sessions/*.jsonl`.
|
||||
Moltbot stores session transcripts on disk under `~/.clawdbot/agents/<agentId>/sessions/*.jsonl`.
|
||||
This is required for session continuity and (optionally) session memory indexing, but it also means
|
||||
**any process/user with filesystem access can read those logs**. Treat disk access as the trust
|
||||
boundary and lock down permissions on `~/.clawdbot` (see the audit section below). If you need
|
||||
@@ -116,7 +116,7 @@ If a macOS node is paired, the Gateway can invoke `system.run` on that node. Thi
|
||||
|
||||
## Dynamic skills (watcher / remote nodes)
|
||||
|
||||
Clawdbot can refresh the skills list mid-session:
|
||||
Moltbot can refresh the skills list mid-session:
|
||||
- **Skills watcher**: changes to `SKILL.md` can update the skills snapshot on the next agent turn.
|
||||
- **Remote nodes**: connecting a macOS node can make macOS-only skills eligible (based on bin probing).
|
||||
|
||||
@@ -139,7 +139,7 @@ People who message you can:
|
||||
|
||||
Most failures here are not fancy exploits — they’re “someone messaged the bot and the bot did what they asked.”
|
||||
|
||||
Clawdbot’s stance:
|
||||
Moltbot’s stance:
|
||||
- **Identity first:** decide who can talk to the bot (DM pairing / allowlists / explicit “open”).
|
||||
- **Scope next:** decide where the bot is allowed to act (group allowlists + mention gating, tools, sandboxing, device permissions).
|
||||
- **Model last:** assume the model can be manipulated; design so manipulation has limited blast radius.
|
||||
@@ -162,9 +162,9 @@ Plugins run **in-process** with the Gateway. Treat them as trusted code:
|
||||
- Prefer explicit `plugins.allow` allowlists.
|
||||
- Review plugin config before enabling.
|
||||
- Restart the Gateway after plugin changes.
|
||||
- If you install plugins from npm (`clawdbot plugins install <npm-spec>`), treat it like running untrusted code:
|
||||
- If you install plugins from npm (`moltbot plugins install <npm-spec>`), treat it like running untrusted code:
|
||||
- The install path is `~/.clawdbot/extensions/<pluginId>/` (or `$CLAWDBOT_STATE_DIR/extensions/<pluginId>/`).
|
||||
- Clawdbot uses `npm pack` and then runs `npm install --omit=dev` in that directory (npm lifecycle scripts can execute code during install).
|
||||
- Moltbot uses `npm pack` and then runs `npm install --omit=dev` in that directory (npm lifecycle scripts can execute code during install).
|
||||
- Prefer pinned, exact versions (`@scope/pkg@1.2.3`), and inspect the unpacked code on disk before enabling.
|
||||
|
||||
Details: [Plugins](/plugin)
|
||||
@@ -181,15 +181,15 @@ All current DM-capable channels support a DM policy (`dmPolicy` or `*.dm.policy`
|
||||
Approve via CLI:
|
||||
|
||||
```bash
|
||||
clawdbot pairing list <channel>
|
||||
clawdbot pairing approve <channel> <code>
|
||||
moltbot pairing list <channel>
|
||||
moltbot pairing approve <channel> <code>
|
||||
```
|
||||
|
||||
Details + files on disk: [Pairing](/start/pairing)
|
||||
|
||||
## DM session isolation (multi-user mode)
|
||||
|
||||
By default, Clawdbot routes **all DMs into the main session** so your assistant has continuity across devices and channels. If **multiple people** can DM the bot (open DMs or a multi-person allowlist), consider isolating DM sessions:
|
||||
By default, Moltbot routes **all DMs into the main session** so your assistant has continuity across devices and channels. If **multiple people** can DM the bot (open DMs or a multi-person allowlist), consider isolating DM sessions:
|
||||
|
||||
```json5
|
||||
{
|
||||
@@ -201,7 +201,7 @@ This prevents cross-user context leakage while keeping group chats isolated. If
|
||||
|
||||
## Allowlists (DM + groups) — terminology
|
||||
|
||||
Clawdbot has two separate “who can trigger me?” layers:
|
||||
Moltbot has two separate “who can trigger me?” layers:
|
||||
|
||||
- **DM allowlist** (`allowFrom` / `channels.discord.dm.allowFrom` / `channels.slack.dm.allowFrom`): who is allowed to talk to the bot in direct messages.
|
||||
- When `dmPolicy="pairing"`, approvals are written to `~/.clawdbot/credentials/<channel>-allowFrom.json` (merged with config allowlists).
|
||||
@@ -285,7 +285,7 @@ Assume “compromised” means: someone got into a room that can trigger the bot
|
||||
- Check Gateway logs and recent sessions/transcripts for unexpected tool calls.
|
||||
- Review `extensions/` and remove anything you don’t fully trust.
|
||||
4. **Re-run audit**
|
||||
- `clawdbot security audit --deep` and confirm the report is clean.
|
||||
- `moltbot security audit --deep` and confirm the report is clean.
|
||||
|
||||
## Lessons Learned (The Hard Way)
|
||||
|
||||
@@ -308,10 +308,10 @@ This is social engineering 101. Create distrust, encourage snooping.
|
||||
### 0) File permissions
|
||||
|
||||
Keep config + state private on the gateway host:
|
||||
- `~/.clawdbot/clawdbot.json`: `600` (user read/write only)
|
||||
- `~/.clawdbot/moltbot.json`: `600` (user read/write only)
|
||||
- `~/.clawdbot`: `700` (user only)
|
||||
|
||||
`clawdbot doctor` can warn and offer to tighten these permissions.
|
||||
`moltbot doctor` can warn and offer to tighten these permissions.
|
||||
|
||||
### 0.4) Network exposure (bind + port + firewall)
|
||||
|
||||
@@ -330,7 +330,7 @@ Rules of thumb:
|
||||
|
||||
### 0.4.1) mDNS/Bonjour discovery (information disclosure)
|
||||
|
||||
The Gateway broadcasts its presence via mDNS (`_clawdbot-gw._tcp` on port 5353) for local device discovery. In full mode, this includes TXT records that may expose operational details:
|
||||
The Gateway broadcasts its presence via mDNS (`_moltbot-gw._tcp` on port 5353) for local device discovery. In full mode, this includes TXT records that may expose operational details:
|
||||
|
||||
- `cliPath`: full filesystem path to the CLI binary (reveals username and install location)
|
||||
- `sshPort`: advertises SSH availability on the host
|
||||
@@ -389,7 +389,7 @@ Set a token so **all** WS clients must authenticate:
|
||||
}
|
||||
```
|
||||
|
||||
Doctor can generate one for you: `clawdbot doctor --generate-gateway-token`.
|
||||
Doctor can generate one for you: `moltbot doctor --generate-gateway-token`.
|
||||
|
||||
Note: `gateway.remote.token` is **only** for remote CLI calls; it does not
|
||||
protect local WS access.
|
||||
@@ -413,9 +413,9 @@ Rotation checklist (token/password):
|
||||
|
||||
### 0.6) Tailscale Serve identity headers
|
||||
|
||||
When `gateway.auth.allowTailscale` is `true` (default for Serve), Clawdbot
|
||||
When `gateway.auth.allowTailscale` is `true` (default for Serve), Moltbot
|
||||
accepts Tailscale Serve identity headers (`tailscale-user-login`) as
|
||||
authentication. Clawdbot verifies the identity by resolving the
|
||||
authentication. Moltbot verifies the identity by resolving the
|
||||
`x-forwarded-for` address through the local Tailscale daemon (`tailscale whois`)
|
||||
and matching it to the header. This only triggers for requests that hit loopback
|
||||
and include `x-forwarded-for`, `x-forwarded-proto`, and `x-forwarded-host` as
|
||||
@@ -427,7 +427,7 @@ you terminate TLS or proxy in front of the gateway, disable
|
||||
|
||||
Trusted proxies:
|
||||
- If you terminate TLS in front of the Gateway, set `gateway.trustedProxies` to your proxy IPs.
|
||||
- Clawdbot will trust `x-forwarded-for` (or `x-real-ip`) from those IPs to determine the client IP for local pairing checks and HTTP auth/local checks.
|
||||
- Moltbot will trust `x-forwarded-for` (or `x-real-ip`) from those IPs to determine the client IP for local pairing checks and HTTP auth/local checks.
|
||||
- Ensure your proxy **overwrites** `x-forwarded-for` and blocks direct access to the Gateway port.
|
||||
|
||||
See [Tailscale](/gateway/tailscale) and [Web overview](/web).
|
||||
@@ -450,7 +450,7 @@ Avoid:
|
||||
|
||||
Assume anything under `~/.clawdbot/` (or `$CLAWDBOT_STATE_DIR/`) may contain secrets or private data:
|
||||
|
||||
- `clawdbot.json`: config may include tokens (gateway, remote gateway), provider settings, and allowlists.
|
||||
- `moltbot.json`: config may include tokens (gateway, remote gateway), provider settings, and allowlists.
|
||||
- `credentials/**`: channel credentials (example: WhatsApp creds), pairing allowlists, legacy OAuth imports.
|
||||
- `agents/<agentId>/agent/auth-profiles.json`: API keys + OAuth tokens (imported from legacy `credentials/oauth.json`).
|
||||
- `agents/<agentId>/sessions/**`: session transcripts (`*.jsonl`) + routing metadata (`sessions.json`) that can contain private messages and tool output.
|
||||
@@ -471,7 +471,7 @@ Logs and transcripts can leak sensitive info even when access controls are corre
|
||||
Recommendations:
|
||||
- Keep tool summary redaction on (`logging.redactSensitive: "tools"`; default).
|
||||
- Add custom patterns for your environment via `logging.redactPatterns` (tokens, hostnames, internal URLs).
|
||||
- When sharing diagnostics, prefer `clawdbot status --all` (pasteable, secrets redacted) over raw logs.
|
||||
- When sharing diagnostics, prefer `moltbot status --all` (pasteable, secrets redacted) over raw logs.
|
||||
- Prune old session transcripts and log files if you don’t need long retention.
|
||||
|
||||
Details: [Logging](/gateway/logging)
|
||||
@@ -678,7 +678,7 @@ If your AI does something bad:
|
||||
|
||||
### Contain
|
||||
|
||||
1. **Stop it:** stop the macOS app (if it supervises the Gateway) or terminate your `clawdbot gateway` process.
|
||||
1. **Stop it:** stop the macOS app (if it supervises the Gateway) or terminate your `moltbot gateway` process.
|
||||
2. **Close exposure:** set `gateway.bind: "loopback"` (or disable Tailscale Funnel/Serve) until you understand what happened.
|
||||
3. **Freeze access:** switch risky DMs/groups to `dmPolicy: "disabled"` / require mentions, and remove `"*"` allow-all entries if you had them.
|
||||
|
||||
@@ -690,13 +690,13 @@ If your AI does something bad:
|
||||
|
||||
### Audit
|
||||
|
||||
1. Check Gateway logs: `/tmp/clawdbot/clawdbot-YYYY-MM-DD.log` (or `logging.file`).
|
||||
1. Check Gateway logs: `/tmp/moltbot/moltbot-YYYY-MM-DD.log` (or `logging.file`).
|
||||
2. Review the relevant transcript(s): `~/.clawdbot/agents/<agentId>/sessions/*.jsonl`.
|
||||
3. Review recent config changes (anything that could have widened access: `gateway.bind`, `gateway.auth`, dm/group policies, `tools.elevated`, plugin changes).
|
||||
|
||||
### Collect for a report
|
||||
|
||||
- Timestamp, gateway host OS + Clawdbot version
|
||||
- Timestamp, gateway host OS + Moltbot version
|
||||
- The session transcript(s) + a short log tail (after redacting)
|
||||
- What the attacker sent + what the agent did
|
||||
- Whether the Gateway was exposed beyond loopback (LAN/Tailscale Funnel/Serve)
|
||||
@@ -748,7 +748,7 @@ Mario asking for find ~
|
||||
|
||||
## Reporting Security Issues
|
||||
|
||||
Found a vulnerability in Clawdbot? Please report responsibly:
|
||||
Found a vulnerability in Moltbot? Please report responsibly:
|
||||
|
||||
1. Email: security@molt.bot
|
||||
2. Don't post publicly until fixed
|
||||
|
||||
@@ -6,14 +6,14 @@ read_when:
|
||||
---
|
||||
# Tailscale (Gateway dashboard)
|
||||
|
||||
Clawdbot can auto-configure Tailscale **Serve** (tailnet) or **Funnel** (public) for the
|
||||
Moltbot can auto-configure Tailscale **Serve** (tailnet) or **Funnel** (public) for the
|
||||
Gateway dashboard and WebSocket port. This keeps the Gateway bound to loopback while
|
||||
Tailscale provides HTTPS, routing, and (for Serve) identity headers.
|
||||
|
||||
## Modes
|
||||
|
||||
- `serve`: Tailnet-only Serve via `tailscale serve`. The gateway stays on `127.0.0.1`.
|
||||
- `funnel`: Public HTTPS via `tailscale funnel`. Clawdbot requires a shared password.
|
||||
- `funnel`: Public HTTPS via `tailscale funnel`. Moltbot requires a shared password.
|
||||
- `off`: Default (no Tailscale automation).
|
||||
|
||||
## Auth
|
||||
@@ -25,10 +25,10 @@ Set `gateway.auth.mode` to control the handshake:
|
||||
|
||||
When `tailscale.mode = "serve"` and `gateway.auth.allowTailscale` is `true`,
|
||||
valid Serve proxy requests can authenticate via Tailscale identity headers
|
||||
(`tailscale-user-login`) without supplying a token/password. Clawdbot verifies
|
||||
(`tailscale-user-login`) without supplying a token/password. Moltbot verifies
|
||||
the identity by resolving the `x-forwarded-for` address via the local Tailscale
|
||||
daemon (`tailscale whois`) and matching it to the header before accepting it.
|
||||
Clawdbot only treats a request as Serve when it arrives from loopback with
|
||||
Moltbot only treats a request as Serve when it arrives from loopback with
|
||||
Tailscale’s `x-forwarded-for`, `x-forwarded-proto`, and `x-forwarded-host`
|
||||
headers.
|
||||
To require explicit credentials, set `gateway.auth.allowTailscale: false` or
|
||||
@@ -85,15 +85,15 @@ Prefer `CLAWDBOT_GATEWAY_PASSWORD` over committing a password to disk.
|
||||
## CLI examples
|
||||
|
||||
```bash
|
||||
clawdbot gateway --tailscale serve
|
||||
clawdbot gateway --tailscale funnel --auth password
|
||||
moltbot gateway --tailscale serve
|
||||
moltbot gateway --tailscale funnel --auth password
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- Tailscale Serve/Funnel requires the `tailscale` CLI to be installed and logged in.
|
||||
- `tailscale.mode: "funnel"` refuses to start unless auth mode is `password` to avoid public exposure.
|
||||
- Set `gateway.tailscale.resetOnExit` if you want Clawdbot to undo `tailscale serve`
|
||||
- Set `gateway.tailscale.resetOnExit` if you want Moltbot to undo `tailscale serve`
|
||||
or `tailscale funnel` configuration on shutdown.
|
||||
- `gateway.bind: "tailnet"` is a direct Tailnet bind (no HTTPS, no Serve/Funnel).
|
||||
- `gateway.bind: "auto"` prefers loopback; use `tailnet` if you want Tailnet-only.
|
||||
|
||||
@@ -6,7 +6,7 @@ read_when:
|
||||
---
|
||||
# Tools Invoke (HTTP)
|
||||
|
||||
Clawdbot’s Gateway exposes a simple HTTP endpoint for invoking a single tool directly. It is always enabled, but gated by Gateway auth and tool policy.
|
||||
Moltbot’s Gateway exposes a simple HTTP endpoint for invoking a single tool directly. It is always enabled, but gated by Gateway auth and tool policy.
|
||||
|
||||
- `POST /tools/invoke`
|
||||
- Same port as the Gateway (WS + HTTP multiplex): `http://<gateway-host>:<port>/tools/invoke`
|
||||
@@ -54,8 +54,8 @@ Tool availability is filtered through the same policy chain used by Gateway agen
|
||||
If a tool is not allowed by policy, the endpoint returns **404**.
|
||||
|
||||
To help group policies resolve context, you can optionally set:
|
||||
- `x-clawdbot-message-channel: <channel>` (example: `slack`, `telegram`)
|
||||
- `x-clawdbot-account-id: <accountId>` (when multiple accounts exist)
|
||||
- `x-moltbot-message-channel: <channel>` (example: `slack`, `telegram`)
|
||||
- `x-moltbot-account-id: <accountId>` (when multiple accounts exist)
|
||||
|
||||
## Responses
|
||||
|
||||
|
||||
@@ -1,11 +1,11 @@
|
||||
---
|
||||
summary: "Quick troubleshooting guide for common Clawdbot failures"
|
||||
summary: "Quick troubleshooting guide for common Moltbot failures"
|
||||
read_when:
|
||||
- Investigating runtime issues or failures
|
||||
---
|
||||
# Troubleshooting 🔧
|
||||
|
||||
When Clawdbot misbehaves, here's how to fix it.
|
||||
When Moltbot misbehaves, here's how to fix it.
|
||||
|
||||
Start with the FAQ’s [First 60 seconds](/help/faq#first-60-seconds-if-somethings-broken) if you just want a quick triage recipe. This page goes deeper on runtime failures and diagnostics.
|
||||
|
||||
@@ -17,15 +17,15 @@ Quick triage commands (in order):
|
||||
|
||||
| Command | What it tells you | When to use it |
|
||||
|---|---|---|
|
||||
| `clawdbot status` | Local summary: OS + update, gateway reachability/mode, service, agents/sessions, provider config state | First check, quick overview |
|
||||
| `clawdbot status --all` | Full local diagnosis (read-only, pasteable, safe-ish) incl. log tail | When you need to share a debug report |
|
||||
| `clawdbot status --deep` | Runs gateway health checks (incl. provider probes; requires reachable gateway) | When “configured” doesn’t mean “working” |
|
||||
| `clawdbot gateway probe` | Gateway discovery + reachability (local + remote targets) | When you suspect you’re probing the wrong gateway |
|
||||
| `clawdbot channels status --probe` | Asks the running gateway for channel status (and optionally probes) | When gateway is reachable but channels misbehave |
|
||||
| `clawdbot gateway status` | Supervisor state (launchd/systemd/schtasks), runtime PID/exit, last gateway error | When the service “looks loaded” but nothing runs |
|
||||
| `clawdbot logs --follow` | Live logs (best signal for runtime issues) | When you need the actual failure reason |
|
||||
| `moltbot status` | Local summary: OS + update, gateway reachability/mode, service, agents/sessions, provider config state | First check, quick overview |
|
||||
| `moltbot status --all` | Full local diagnosis (read-only, pasteable, safe-ish) incl. log tail | When you need to share a debug report |
|
||||
| `moltbot status --deep` | Runs gateway health checks (incl. provider probes; requires reachable gateway) | When “configured” doesn’t mean “working” |
|
||||
| `moltbot gateway probe` | Gateway discovery + reachability (local + remote targets) | When you suspect you’re probing the wrong gateway |
|
||||
| `moltbot channels status --probe` | Asks the running gateway for channel status (and optionally probes) | When gateway is reachable but channels misbehave |
|
||||
| `moltbot gateway status` | Supervisor state (launchd/systemd/schtasks), runtime PID/exit, last gateway error | When the service “looks loaded” but nothing runs |
|
||||
| `moltbot logs --follow` | Live logs (best signal for runtime issues) | When you need the actual failure reason |
|
||||
|
||||
**Sharing output:** prefer `clawdbot status --all` (it redacts tokens). If you paste `clawdbot status`, consider setting `CLAWDBOT_SHOW_SECRETS=0` first (token previews).
|
||||
**Sharing output:** prefer `moltbot status --all` (it redacts tokens). If you paste `moltbot status`, consider setting `CLAWDBOT_SHOW_SECRETS=0` first (token previews).
|
||||
|
||||
See also: [Health checks](/gateway/health) and [Logging](/logging).
|
||||
|
||||
@@ -40,13 +40,13 @@ Fix options:
|
||||
- Re-run onboarding and choose **Anthropic** for that agent.
|
||||
- Or paste a setup-token on the **gateway host**:
|
||||
```bash
|
||||
clawdbot models auth setup-token --provider anthropic
|
||||
moltbot models auth setup-token --provider anthropic
|
||||
```
|
||||
- Or copy `auth-profiles.json` from the main agent dir to the new agent dir.
|
||||
|
||||
Verify:
|
||||
```bash
|
||||
clawdbot models status
|
||||
moltbot models status
|
||||
```
|
||||
|
||||
### OAuth token refresh failed (Anthropic Claude subscription)
|
||||
@@ -59,15 +59,15 @@ switch to a **Claude Code setup-token** and paste it on the **gateway host**.
|
||||
|
||||
```bash
|
||||
# Run on the gateway host (paste the setup-token)
|
||||
clawdbot models auth setup-token --provider anthropic
|
||||
clawdbot models status
|
||||
moltbot models auth setup-token --provider anthropic
|
||||
moltbot models status
|
||||
```
|
||||
|
||||
If you generated the token elsewhere:
|
||||
|
||||
```bash
|
||||
clawdbot models auth paste-token --provider anthropic
|
||||
clawdbot models status
|
||||
moltbot models auth paste-token --provider anthropic
|
||||
moltbot models status
|
||||
```
|
||||
|
||||
More detail: [Anthropic](/providers/anthropic) and [OAuth](/concepts/oauth).
|
||||
@@ -97,18 +97,18 @@ can appear “loaded” while nothing is running.
|
||||
|
||||
**Check:**
|
||||
```bash
|
||||
clawdbot gateway status
|
||||
clawdbot doctor
|
||||
moltbot gateway status
|
||||
moltbot doctor
|
||||
```
|
||||
|
||||
Doctor/service will show runtime state (PID/last exit) and log hints.
|
||||
|
||||
**Logs:**
|
||||
- Preferred: `clawdbot logs --follow`
|
||||
- File logs (always): `/tmp/clawdbot/clawdbot-YYYY-MM-DD.log` (or your configured `logging.file`)
|
||||
- Preferred: `moltbot logs --follow`
|
||||
- File logs (always): `/tmp/moltbot/moltbot-YYYY-MM-DD.log` (or your configured `logging.file`)
|
||||
- macOS LaunchAgent (if installed): `$CLAWDBOT_STATE_DIR/logs/gateway.log` and `gateway.err.log`
|
||||
- Linux systemd (if installed): `journalctl --user -u clawdbot-gateway[-<profile>].service -n 200 --no-pager`
|
||||
- Windows: `schtasks /Query /TN "Clawdbot Gateway (<profile>)" /V /FO LIST`
|
||||
- Linux systemd (if installed): `journalctl --user -u moltbot-gateway[-<profile>].service -n 200 --no-pager`
|
||||
- Windows: `schtasks /Query /TN "Moltbot Gateway (<profile>)" /V /FO LIST`
|
||||
|
||||
**Enable more logging:**
|
||||
- Bump file log detail (persisted JSONL):
|
||||
@@ -131,24 +131,24 @@ Gateway refuses to start.
|
||||
**Fix (recommended):**
|
||||
- Run the wizard and set the Gateway run mode to **Local**:
|
||||
```bash
|
||||
clawdbot configure
|
||||
moltbot configure
|
||||
```
|
||||
- Or set it directly:
|
||||
```bash
|
||||
clawdbot config set gateway.mode local
|
||||
moltbot config set gateway.mode local
|
||||
```
|
||||
|
||||
**If you meant to run a remote Gateway instead:**
|
||||
- Set a remote URL and keep `gateway.mode=remote`:
|
||||
```bash
|
||||
clawdbot config set gateway.mode remote
|
||||
clawdbot config set gateway.remote.url "wss://gateway.example.com"
|
||||
moltbot config set gateway.mode remote
|
||||
moltbot config set gateway.remote.url "wss://gateway.example.com"
|
||||
```
|
||||
|
||||
**Ad-hoc/dev only:** pass `--allow-unconfigured` to start the gateway without
|
||||
`gateway.mode=local`.
|
||||
|
||||
**No config file yet?** Run `clawdbot setup` to create a starter config, then rerun
|
||||
**No config file yet?** Run `moltbot setup` to create a starter config, then rerun
|
||||
the gateway.
|
||||
|
||||
### Service Environment (PATH + runtime)
|
||||
@@ -166,7 +166,7 @@ so missing tools usually mean your shell init isn’t exporting them (or set
|
||||
`tools.exec.pathPrepend`). See [/tools/exec](/tools/exec).
|
||||
|
||||
WhatsApp + Telegram channels require **Node**; Bun is unsupported. If your
|
||||
service was installed with Bun or a version-managed Node path, run `clawdbot doctor`
|
||||
service was installed with Bun or a version-managed Node path, run `moltbot doctor`
|
||||
to migrate to a system Node install.
|
||||
|
||||
### Skill missing API key in sandbox
|
||||
@@ -178,7 +178,7 @@ to migrate to a system Node install.
|
||||
**Fix:**
|
||||
- set `agents.defaults.sandbox.docker.env` (or per-agent `agents.list[].sandbox.docker.env`)
|
||||
- or bake the key into your custom sandbox image
|
||||
- then run `clawdbot sandbox recreate --agent <id>` (or `--all`)
|
||||
- then run `moltbot sandbox recreate --agent <id>` (or `--all`)
|
||||
|
||||
### Service Running but Port Not Listening
|
||||
|
||||
@@ -191,28 +191,28 @@ the Gateway likely refused to bind.
|
||||
- Always trust `Probe target:` + `Config (service):` as the “what did we actually try?” lines.
|
||||
|
||||
**Check:**
|
||||
- `gateway.mode` must be `local` for `clawdbot gateway` and the service.
|
||||
- If you set `gateway.mode=remote`, the **CLI defaults** to a remote URL. The service can still be running locally, but your CLI may be probing the wrong place. Use `clawdbot gateway status` to see the service’s resolved port + probe target (or pass `--url`).
|
||||
- `clawdbot gateway status` and `clawdbot doctor` surface the **last gateway error** from logs when the service looks running but the port is closed.
|
||||
- `gateway.mode` must be `local` for `moltbot gateway` and the service.
|
||||
- If you set `gateway.mode=remote`, the **CLI defaults** to a remote URL. The service can still be running locally, but your CLI may be probing the wrong place. Use `moltbot gateway status` to see the service’s resolved port + probe target (or pass `--url`).
|
||||
- `moltbot gateway status` and `moltbot doctor` surface the **last gateway error** from logs when the service looks running but the port is closed.
|
||||
- Non-loopback binds (`lan`/`tailnet`/`custom`, or `auto` when loopback is unavailable) require auth:
|
||||
`gateway.auth.token` (or `CLAWDBOT_GATEWAY_TOKEN`).
|
||||
- `gateway.remote.token` is for remote CLI calls only; it does **not** enable local auth.
|
||||
- `gateway.token` is ignored; use `gateway.auth.token`.
|
||||
|
||||
**If `clawdbot gateway status` shows a config mismatch**
|
||||
**If `moltbot gateway status` shows a config mismatch**
|
||||
- `Config (cli): ...` and `Config (service): ...` should normally match.
|
||||
- If they don’t, you’re almost certainly editing one config while the service is running another.
|
||||
- Fix: rerun `clawdbot gateway install --force` from the same `--profile` / `CLAWDBOT_STATE_DIR` you want the service to use.
|
||||
- Fix: rerun `moltbot gateway install --force` from the same `--profile` / `CLAWDBOT_STATE_DIR` you want the service to use.
|
||||
|
||||
**If `clawdbot gateway status` reports service config issues**
|
||||
**If `moltbot gateway status` reports service config issues**
|
||||
- The supervisor config (launchd/systemd/schtasks) is missing current defaults.
|
||||
- Fix: run `clawdbot doctor` to update it (or `clawdbot gateway install --force` for a full rewrite).
|
||||
- Fix: run `moltbot doctor` to update it (or `moltbot gateway install --force` for a full rewrite).
|
||||
|
||||
**If `Last gateway error:` mentions “refusing to bind … without auth”**
|
||||
- You set `gateway.bind` to a non-loopback mode (`lan`/`tailnet`/`custom`, or `auto` when loopback is unavailable) but didn’t configure auth.
|
||||
- Fix: set `gateway.auth.mode` + `gateway.auth.token` (or export `CLAWDBOT_GATEWAY_TOKEN`) and restart the service.
|
||||
|
||||
**If `clawdbot gateway status` says `bind=tailnet` but no tailnet interface was found**
|
||||
**If `moltbot gateway status` says `bind=tailnet` but no tailnet interface was found**
|
||||
- The gateway tried to bind to a Tailscale IP (100.64.0.0/10) but none were detected on the host.
|
||||
- Fix: bring up Tailscale on that machine (or change `gateway.bind` to `loopback`/`lan`).
|
||||
|
||||
@@ -226,7 +226,7 @@ This means something is already listening on the gateway port.
|
||||
|
||||
**Check:**
|
||||
```bash
|
||||
clawdbot gateway status
|
||||
moltbot gateway status
|
||||
```
|
||||
|
||||
It will show the listener(s) and likely causes (gateway already running, SSH tunnel).
|
||||
@@ -234,7 +234,7 @@ If needed, stop the service or pick a different port.
|
||||
|
||||
### Extra Workspace Folders Detected
|
||||
|
||||
If you upgraded from older installs, you might still have `~/clawdbot` on disk.
|
||||
If you upgraded from older installs, you might still have `~/moltbot` on disk.
|
||||
Multiple workspace directories can cause confusing auth or state drift because
|
||||
only one workspace is active.
|
||||
|
||||
@@ -267,14 +267,14 @@ The agent was interrupted mid-response.
|
||||
|
||||
### "Agent failed before reply: Unknown model: anthropic/claude-haiku-3-5"
|
||||
|
||||
Clawdbot intentionally rejects **older/insecure models** (especially those more
|
||||
Moltbot intentionally rejects **older/insecure models** (especially those more
|
||||
vulnerable to prompt injection). If you see this error, the model name is no
|
||||
longer supported.
|
||||
|
||||
**Fix:**
|
||||
- Pick a **latest** model for the provider and update your config or model alias.
|
||||
- If you’re unsure which models are available, run `clawdbot models list` or
|
||||
`clawdbot models scan` and choose a supported one.
|
||||
- If you’re unsure which models are available, run `moltbot models list` or
|
||||
`moltbot models scan` and choose a supported one.
|
||||
- Check gateway logs for the detailed failure reason.
|
||||
|
||||
See also: [Models CLI](/cli/models) and [Model providers](/concepts/model-providers).
|
||||
@@ -283,7 +283,7 @@ See also: [Models CLI](/cli/models) and [Model providers](/concepts/model-provid
|
||||
|
||||
**Check 1:** Is the sender allowlisted?
|
||||
```bash
|
||||
clawdbot status
|
||||
moltbot status
|
||||
```
|
||||
Look for `AllowFrom: ...` in the output.
|
||||
|
||||
@@ -292,14 +292,14 @@ Look for `AllowFrom: ...` in the output.
|
||||
# The message must match mentionPatterns or explicit mentions; defaults live in channel groups/guilds.
|
||||
# Multi-agent: `agents.list[].groupChat.mentionPatterns` overrides global patterns.
|
||||
grep -n "agents\\|groupChat\\|mentionPatterns\\|channels\\.whatsapp\\.groups\\|channels\\.telegram\\.groups\\|channels\\.imessage\\.groups\\|channels\\.discord\\.guilds" \
|
||||
"${CLAWDBOT_CONFIG_PATH:-$HOME/.clawdbot/clawdbot.json}"
|
||||
"${CLAWDBOT_CONFIG_PATH:-$HOME/.clawdbot/moltbot.json}"
|
||||
```
|
||||
|
||||
**Check 3:** Check the logs
|
||||
```bash
|
||||
clawdbot logs --follow
|
||||
moltbot logs --follow
|
||||
# or if you want quick filters:
|
||||
tail -f "$(ls -t /tmp/clawdbot/clawdbot-*.log | head -1)" | grep "blocked\\|skip\\|unauthorized"
|
||||
tail -f "$(ls -t /tmp/moltbot/moltbot-*.log | head -1)" | grep "blocked\\|skip\\|unauthorized"
|
||||
```
|
||||
|
||||
### Pairing Code Not Arriving
|
||||
@@ -308,14 +308,14 @@ If `dmPolicy` is `pairing`, unknown senders should receive a code and their mess
|
||||
|
||||
**Check 1:** Is a pending request already waiting?
|
||||
```bash
|
||||
clawdbot pairing list <channel>
|
||||
moltbot pairing list <channel>
|
||||
```
|
||||
|
||||
Pending DM pairing requests are capped at **3 per channel** by default. If the list is full, new requests won’t generate a code until one is approved or expires.
|
||||
|
||||
**Check 2:** Did the request get created but no reply was sent?
|
||||
```bash
|
||||
clawdbot logs --follow | grep "pairing request"
|
||||
moltbot logs --follow | grep "pairing request"
|
||||
```
|
||||
|
||||
**Check 3:** Confirm `dmPolicy` isn’t `open`/`allowlist` for that channel.
|
||||
@@ -368,26 +368,26 @@ Or use the `process` tool to background long commands.
|
||||
|
||||
```bash
|
||||
# Check local status (creds, sessions, queued events)
|
||||
clawdbot status
|
||||
moltbot status
|
||||
# Probe the running gateway + channels (WA connect + Telegram + Discord APIs)
|
||||
clawdbot status --deep
|
||||
moltbot status --deep
|
||||
|
||||
# View recent connection events
|
||||
clawdbot logs --limit 200 | grep "connection\\|disconnect\\|logout"
|
||||
moltbot logs --limit 200 | grep "connection\\|disconnect\\|logout"
|
||||
```
|
||||
|
||||
**Fix:** Usually reconnects automatically once the Gateway is running. If you’re stuck, restart the Gateway process (however you supervise it), or run it manually with verbose output:
|
||||
|
||||
```bash
|
||||
clawdbot gateway --verbose
|
||||
moltbot gateway --verbose
|
||||
```
|
||||
|
||||
If you’re logged out / unlinked:
|
||||
|
||||
```bash
|
||||
clawdbot channels logout
|
||||
moltbot channels logout
|
||||
trash "${CLAWDBOT_STATE_DIR:-$HOME/.clawdbot}/credentials" # if logout can't cleanly remove everything
|
||||
clawdbot channels login --verbose # re-scan QR
|
||||
moltbot channels login --verbose # re-scan QR
|
||||
```
|
||||
|
||||
### Media Send Failing
|
||||
@@ -404,12 +404,12 @@ ls -la /path/to/your/image.jpg
|
||||
|
||||
**Check 3:** Check media logs
|
||||
```bash
|
||||
grep "media\\|fetch\\|download" "$(ls -t /tmp/clawdbot/clawdbot-*.log | head -1)" | tail -20
|
||||
grep "media\\|fetch\\|download" "$(ls -t /tmp/moltbot/moltbot-*.log | head -1)" | tail -20
|
||||
```
|
||||
|
||||
### High Memory Usage
|
||||
|
||||
Clawdbot keeps conversation history in memory.
|
||||
Moltbot keeps conversation history in memory.
|
||||
|
||||
**Fix:** Restart periodically or set session limits:
|
||||
```json
|
||||
@@ -424,26 +424,26 @@ Clawdbot keeps conversation history in memory.
|
||||
|
||||
### “Gateway won’t start — configuration invalid”
|
||||
|
||||
Clawdbot now refuses to start when the config contains unknown keys, malformed values, or invalid types.
|
||||
Moltbot now refuses to start when the config contains unknown keys, malformed values, or invalid types.
|
||||
This is intentional for safety.
|
||||
|
||||
Fix it with Doctor:
|
||||
```bash
|
||||
clawdbot doctor
|
||||
clawdbot doctor --fix
|
||||
moltbot doctor
|
||||
moltbot doctor --fix
|
||||
```
|
||||
|
||||
Notes:
|
||||
- `clawdbot doctor` reports every invalid entry.
|
||||
- `clawdbot doctor --fix` applies migrations/repairs and rewrites the config.
|
||||
- Diagnostic commands like `clawdbot logs`, `clawdbot health`, `clawdbot status`, `clawdbot gateway status`, and `clawdbot gateway probe` still run even if the config is invalid.
|
||||
- `moltbot doctor` reports every invalid entry.
|
||||
- `moltbot doctor --fix` applies migrations/repairs and rewrites the config.
|
||||
- Diagnostic commands like `moltbot logs`, `moltbot health`, `moltbot status`, `moltbot gateway status`, and `moltbot gateway probe` still run even if the config is invalid.
|
||||
|
||||
### “All models failed” — what should I check first?
|
||||
|
||||
- **Credentials** present for the provider(s) being tried (auth profiles + env vars).
|
||||
- **Model routing**: confirm `agents.defaults.model.primary` and fallbacks are models you can access.
|
||||
- **Gateway logs** in `/tmp/clawdbot/…` for the exact provider error.
|
||||
- **Model status**: use `/model status` (chat) or `clawdbot models status` (CLI).
|
||||
- **Gateway logs** in `/tmp/moltbot/…` for the exact provider error.
|
||||
- **Model status**: use `/model status` (chat) or `moltbot models status` (CLI).
|
||||
|
||||
### I’m running on my personal WhatsApp number — why is self-chat weird?
|
||||
|
||||
@@ -468,13 +468,13 @@ See [WhatsApp setup](/channels/whatsapp).
|
||||
Run the login command again and scan the QR code:
|
||||
|
||||
```bash
|
||||
clawdbot channels login
|
||||
moltbot channels login
|
||||
```
|
||||
|
||||
### Build errors on `main` — what’s the standard fix path?
|
||||
|
||||
1) `git pull origin main && pnpm install`
|
||||
2) `clawdbot doctor`
|
||||
2) `moltbot doctor`
|
||||
3) Check GitHub issues or Discord
|
||||
4) Temporary workaround: check out an older commit
|
||||
|
||||
@@ -488,8 +488,8 @@ Typical recovery:
|
||||
git status # ensure you’re in the repo root
|
||||
pnpm install
|
||||
pnpm build
|
||||
clawdbot doctor
|
||||
clawdbot gateway restart
|
||||
moltbot doctor
|
||||
moltbot gateway restart
|
||||
```
|
||||
|
||||
Why: pnpm is the configured package manager for this repo.
|
||||
@@ -513,8 +513,8 @@ Notes:
|
||||
- The git flow only rebases if the repo is clean. Commit or stash changes first.
|
||||
- After switching, run:
|
||||
```bash
|
||||
clawdbot doctor
|
||||
clawdbot gateway restart
|
||||
moltbot doctor
|
||||
moltbot gateway restart
|
||||
```
|
||||
|
||||
### Telegram block streaming isn’t splitting text between tool calls. Why?
|
||||
@@ -546,19 +546,19 @@ Fix checklist:
|
||||
3) Put `requireMention: false` **under** `channels.discord.guilds` (global or per‑channel).
|
||||
Top‑level `channels.discord.requireMention` is not a supported key.
|
||||
4) Ensure the bot has **Message Content Intent** and channel permissions.
|
||||
5) Run `clawdbot channels status --probe` for audit hints.
|
||||
5) Run `moltbot channels status --probe` for audit hints.
|
||||
|
||||
Docs: [Discord](/channels/discord), [Channels troubleshooting](/channels/troubleshooting).
|
||||
|
||||
### Cloud Code Assist API error: invalid tool schema (400). What now?
|
||||
|
||||
This is almost always a **tool schema compatibility** issue. The Cloud Code Assist
|
||||
endpoint accepts a strict subset of JSON Schema. Clawdbot scrubs/normalizes tool
|
||||
endpoint accepts a strict subset of JSON Schema. Moltbot scrubs/normalizes tool
|
||||
schemas in current `main`, but the fix is not in the last release yet (as of
|
||||
January 13, 2026).
|
||||
|
||||
Fix checklist:
|
||||
1) **Update Clawdbot**:
|
||||
1) **Update Moltbot**:
|
||||
- If you can run from source, pull `main` and restart the gateway.
|
||||
- Otherwise, wait for the next release that includes the schema scrubber.
|
||||
2) Avoid unsupported keywords like `anyOf/oneOf/allOf`, `patternProperties`,
|
||||
@@ -580,7 +580,7 @@ tccutil reset All com.clawdbot.mac.debug
|
||||
```
|
||||
|
||||
**Fix 2: Force New Bundle ID**
|
||||
If resetting doesn't work, change the `BUNDLE_ID` in [`scripts/package-mac-app.sh`](https://github.com/clawdbot/clawdbot/blob/main/scripts/package-mac-app.sh) (e.g., add a `.test` suffix) and rebuild. This forces macOS to treat it as a new app.
|
||||
If resetting doesn't work, change the `BUNDLE_ID` in [`scripts/package-mac-app.sh`](https://github.com/moltbot/moltbot/blob/main/scripts/package-mac-app.sh) (e.g., add a `.test` suffix) and rebuild. This forces macOS to treat it as a new app.
|
||||
|
||||
### Gateway stuck on "Starting..."
|
||||
|
||||
@@ -589,8 +589,8 @@ The app connects to a local gateway on port `18789`. If it stays stuck:
|
||||
**Fix 1: Stop the supervisor (preferred)**
|
||||
If the gateway is supervised by launchd, killing the PID will just respawn it. Stop the supervisor first:
|
||||
```bash
|
||||
clawdbot gateway status
|
||||
clawdbot gateway stop
|
||||
moltbot gateway status
|
||||
moltbot gateway stop
|
||||
# Or: launchctl bootout gui/$UID/com.clawdbot.gateway (replace with com.clawdbot.<profile> if needed)
|
||||
```
|
||||
|
||||
@@ -607,10 +607,10 @@ kill -9 <PID> # last resort
|
||||
```
|
||||
|
||||
**Fix 3: Check the CLI install**
|
||||
Ensure the global `clawdbot` CLI is installed and matches the app version:
|
||||
Ensure the global `moltbot` CLI is installed and matches the app version:
|
||||
```bash
|
||||
clawdbot --version
|
||||
npm install -g clawdbot@<version>
|
||||
moltbot --version
|
||||
npm install -g moltbot@<version>
|
||||
```
|
||||
|
||||
## Debug Mode
|
||||
@@ -619,19 +619,19 @@ Get verbose logging:
|
||||
|
||||
```bash
|
||||
# Turn on trace logging in config:
|
||||
# ${CLAWDBOT_CONFIG_PATH:-$HOME/.clawdbot/clawdbot.json} -> { logging: { level: "trace" } }
|
||||
# ${CLAWDBOT_CONFIG_PATH:-$HOME/.clawdbot/moltbot.json} -> { logging: { level: "trace" } }
|
||||
#
|
||||
# Then run verbose commands to mirror debug output to stdout:
|
||||
clawdbot gateway --verbose
|
||||
clawdbot channels login --verbose
|
||||
moltbot gateway --verbose
|
||||
moltbot channels login --verbose
|
||||
```
|
||||
|
||||
## Log Locations
|
||||
|
||||
| Log | Location |
|
||||
|-----|----------|
|
||||
| Gateway file logs (structured) | `/tmp/clawdbot/clawdbot-YYYY-MM-DD.log` (or `logging.file`) |
|
||||
| Gateway service logs (supervisor) | macOS: `$CLAWDBOT_STATE_DIR/logs/gateway.log` + `gateway.err.log` (default: `~/.clawdbot/logs/...`; profiles use `~/.clawdbot-<profile>/logs/...`)<br />Linux: `journalctl --user -u clawdbot-gateway[-<profile>].service -n 200 --no-pager`<br />Windows: `schtasks /Query /TN "Clawdbot Gateway (<profile>)" /V /FO LIST` |
|
||||
| Gateway file logs (structured) | `/tmp/moltbot/moltbot-YYYY-MM-DD.log` (or `logging.file`) |
|
||||
| Gateway service logs (supervisor) | macOS: `$CLAWDBOT_STATE_DIR/logs/gateway.log` + `gateway.err.log` (default: `~/.clawdbot/logs/...`; profiles use `~/.clawdbot-<profile>/logs/...`)<br />Linux: `journalctl --user -u moltbot-gateway[-<profile>].service -n 200 --no-pager`<br />Windows: `schtasks /Query /TN "Moltbot Gateway (<profile>)" /V /FO LIST` |
|
||||
| Session files | `$CLAWDBOT_STATE_DIR/agents/<agentId>/sessions/` |
|
||||
| Media cache | `$CLAWDBOT_STATE_DIR/media/` |
|
||||
| Credentials | `$CLAWDBOT_STATE_DIR/credentials/` |
|
||||
@@ -640,22 +640,22 @@ clawdbot channels login --verbose
|
||||
|
||||
```bash
|
||||
# Supervisor + probe target + config paths
|
||||
clawdbot gateway status
|
||||
moltbot gateway status
|
||||
# Include system-level scans (legacy/extra services, port listeners)
|
||||
clawdbot gateway status --deep
|
||||
moltbot gateway status --deep
|
||||
|
||||
# Is the gateway reachable?
|
||||
clawdbot health --json
|
||||
moltbot health --json
|
||||
# If it fails, rerun with connection details:
|
||||
clawdbot health --verbose
|
||||
moltbot health --verbose
|
||||
|
||||
# Is something listening on the default port?
|
||||
lsof -nP -iTCP:18789 -sTCP:LISTEN
|
||||
|
||||
# Recent activity (RPC log tail)
|
||||
clawdbot logs --follow
|
||||
moltbot logs --follow
|
||||
# Fallback if RPC is down
|
||||
tail -20 /tmp/clawdbot/clawdbot-*.log
|
||||
tail -20 /tmp/moltbot/moltbot-*.log
|
||||
```
|
||||
|
||||
## Reset Everything
|
||||
@@ -663,23 +663,23 @@ tail -20 /tmp/clawdbot/clawdbot-*.log
|
||||
Nuclear option:
|
||||
|
||||
```bash
|
||||
clawdbot gateway stop
|
||||
moltbot gateway stop
|
||||
# If you installed a service and want a clean install:
|
||||
# clawdbot gateway uninstall
|
||||
# moltbot gateway uninstall
|
||||
|
||||
trash "${CLAWDBOT_STATE_DIR:-$HOME/.clawdbot}"
|
||||
clawdbot channels login # re-pair WhatsApp
|
||||
clawdbot gateway restart # or: clawdbot gateway
|
||||
moltbot channels login # re-pair WhatsApp
|
||||
moltbot gateway restart # or: moltbot gateway
|
||||
```
|
||||
|
||||
⚠️ This loses all sessions and requires re-pairing WhatsApp.
|
||||
|
||||
## Getting Help
|
||||
|
||||
1. Check logs first: `/tmp/clawdbot/` (default: `clawdbot-YYYY-MM-DD.log`, or your configured `logging.file`)
|
||||
1. Check logs first: `/tmp/moltbot/` (default: `moltbot-YYYY-MM-DD.log`, or your configured `logging.file`)
|
||||
2. Search existing issues on GitHub
|
||||
3. Open a new issue with:
|
||||
- Clawdbot version
|
||||
- Moltbot version
|
||||
- Relevant log snippets
|
||||
- Steps to reproduce
|
||||
- Your config (redact secrets!)
|
||||
|
||||
Reference in New Issue
Block a user