ouyang/clawdbot
1
0
Fork 0
mirror of https://github.com/clawdbot/clawdbot.git synced 2026-01-31 19:37:45 +01:00
Code Issues Packages Projects Releases Wiki Activity

refactor: rename to openclaw

Browse Source
This commit is contained in:
Peter Steinberger
2026-01-30 03:15:10 +01:00
parent 4583f88626
commit 9a7160786a
2357 changed files with 16688 additions and 16788 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
docs/gateway/authentication.md
View File

@@ -6,7 +6,7 @@ read_when:
---
# Authentication
Moltbot supports OAuth and API keys for model providers. For Anthropic
OpenClaw 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,18 +18,18 @@ 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 `moltbot gateway`).
2) Put it on the **gateway host** (the machine running `openclaw gateway`).
```bash
export ANTHROPIC_API_KEY="..."
moltbot models status
openclaw models status
```
3) If the Gateway runs under systemd/launchd, prefer putting the key in
`~/.clawdbot/.env` so the daemon can read it:
`~/.openclaw/.env` so the daemon can read it:
```bash
cat >> ~/.clawdbot/.env <<'EOF'
cat >> ~/.openclaw/.env <<'EOF'
ANTHROPIC_API_KEY=...
EOF
```
@@ -37,15 +37,15 @@ EOF
Then restart the daemon (or restart your Gateway process) and re-check:
```bash
moltbot models status
moltbot doctor
openclaw models status
openclaw doctor
```
If you’d rather not manage env vars yourself, the onboarding wizard can store
API keys for daemon use: `moltbot onboard`.
API keys for daemon use: `openclaw onboard`.
See [Help](/help) for details on env inheritance (`env.shellEnv`,
`~/.clawdbot/.env`, systemd/launchd).
`~/.openclaw/.env`, systemd/launchd).
## Anthropic: setup-token (subscription auth)
@@ -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 Moltbot:
Then paste it into OpenClaw:
```bash
moltbot models auth setup-token --provider anthropic
openclaw models auth setup-token --provider anthropic
```
If the token was created on another machine, paste it manually:
```bash
moltbot models auth paste-token --provider anthropic
openclaw 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
moltbot models auth paste-token --provider anthropic
moltbot models auth paste-token --provider openrouter
openclaw models auth paste-token --provider anthropic
openclaw models auth paste-token --provider openrouter
```
Automation-friendly check (exit `1` when expired/missing, `2` when expiring):
```bash
moltbot models status --check
openclaw 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
moltbot models status
moltbot doctor
openclaw models status
openclaw 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
moltbot models auth order get --provider anthropic
moltbot models auth order set --provider anthropic anthropic:default
moltbot models auth order clear --provider anthropic
openclaw models auth order get --provider anthropic
openclaw models auth order set --provider anthropic anthropic:default
openclaw 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
moltbot models status
openclaw models status
```
### Token expiring/expired
Run `moltbot models status` to confirm which profile is expiring. If the profile
Run `openclaw models status` to confirm which profile is expiring. If the profile
is missing, rerun `claude setup-token` and paste the token again.
## Requirements

4
docs/gateway/background-process.md
View File

@@ -7,7 +7,7 @@ read_when:
# Background Exec + Process Tool
Moltbot runs shell commands through the `exec` tool and keeps long‑running tasks in memory. The `process` tool manages those background sessions.
OpenClaw runs shell commands through the `exec` tool and keeps long‑running tasks in memory. The `process` tool manages those background sessions.
## exec tool
@@ -33,7 +33,7 @@ When spawning long-running child processes outside the exec/process tools (for e
Environment overrides:
- `PI_BASH_YIELD_MS`: default yield (ms)
- `PI_BASH_MAX_OUTPUT_CHARS`: in‑memory output cap (chars)
- `CLAWDBOT_BASH_PENDING_MAX_OUTPUT_CHARS`: pending stdout/stderr cap per stream (chars)
- `OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS`: pending stdout/stderr cap per stream (chars)
- `PI_BASH_JOB_TTL_MS`: TTL for finished sessions (ms, bounded to 1m–3h)
Config (preferred):

50
docs/gateway/bonjour.md
View File

@@ -6,7 +6,7 @@ read_when:
---
# Bonjour / mDNS discovery
Moltbot uses Bonjour (mDNS / DNS‑SD) as a **LAN‑only convenience** to discover
OpenClaw 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 `_moltbot-gw._tcp` under a dedicated zone
(example: `moltbot.internal.`).
3) Configure Tailscale **split DNS** so `moltbot.internal` resolves via that
2) Publish DNS‑SD records for `_openclaw-gw._tcp` under a dedicated zone
(example: `openclaw.internal.`).
3) Configure Tailscale **split DNS** so your chosen domain resolves via that
DNS server for clients (including iOS).
Moltbot standardizes on `moltbot.internal.` for this mode. iOS/Android nodes
browse both `local.` and `moltbot.internal.` automatically.
OpenClaw supports any discovery domain; `openclaw.internal.` is just an example.
iOS/Android nodes browse both `local.` and your configured wide‑area domain.
### Gateway config (recommended)
```json5
{
gateway: { bind: "tailnet" }, // tailnet-only (recommended)
discovery: { wideArea: { enabled: true } } // enables moltbot.internal DNS-SD publishing
discovery: { wideArea: { enabled: true } } // enables wide-area DNS-SD publishing
}
```
### One‑time DNS server setup (gateway host)
```bash
moltbot dns setup --apply
openclaw dns setup --apply
```
This installs CoreDNS and configures it to:
- listen on port 53 only on the gateway’s Tailscale interfaces
- serve `moltbot.internal.` from `~/.clawdbot/dns/moltbot.internal.db`
- serve your chosen domain (example: `openclaw.internal.`) from `~/.openclaw/dns/<domain>.db`
Validate from a tailnet‑connected machine:
```bash
dns-sd -B _moltbot-gw._tcp moltbot.internal.
dig @<TAILNET_IPV4> -p 53 _moltbot-gw._tcp.clawdbot.internal PTR +short
dns-sd -B _openclaw-gw._tcp openclaw.internal.
dig @<TAILNET_IPV4> -p 53 _openclaw-gw._tcp.openclaw.internal PTR +short
```
### Tailscale DNS settings
@@ -58,10 +58,10 @@ dig @<TAILNET_IPV4> -p 53 _moltbot-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 `moltbot.internal` uses that nameserver.
- Add split DNS so your discovery domain uses that nameserver.
Once clients accept tailnet DNS, iOS nodes can browse
`_moltbot-gw._tcp` in `moltbot.internal.` without multicast.
`_openclaw-gw._tcp` in your discovery domain 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/moltbot.json`.
- Set `gateway.bind: "tailnet"` in `~/.openclaw/openclaw.json`.
- Restart the Gateway (or restart the macOS menubar app).
## What advertises
Only the Gateway advertises `_moltbot-gw._tcp`.
Only the Gateway advertises `_openclaw-gw._tcp`.
## Service types
- `_moltbot-gw._tcp` — gateway transport beacon (used by macOS/iOS/Android nodes).
- `_openclaw-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 `moltbot` entrypoint)
- `cliPath=<path>` (optional; absolute path to a runnable `openclaw` 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 _moltbot-gw._tcp local.
dns-sd -B _openclaw-gw._tcp local.
```
- Resolve one instance (replace `<instance>`):
```bash
dns-sd -L "<instance>" _moltbot-gw._tcp local.
dns-sd -L "<instance>" _openclaw-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 `_moltbot-gw._tcp`.
The iOS node uses `NWBrowser` to discover `_openclaw-gw._tcp`.
To capture logs:
- Settings → Gateway → Advanced → **Discovery Debug Logs**
@@ -150,11 +150,11 @@ sequences (e.g. spaces become `\032`).
## Disabling / configuration
- `CLAWDBOT_DISABLE_BONJOUR=1` disables advertising.
- `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.
- `OPENCLAW_DISABLE_BONJOUR=1` disables advertising (legacy: `OPENCLAW_DISABLE_BONJOUR`).
- `gateway.bind` in `~/.openclaw/openclaw.json` controls the Gateway bind mode.
- `OPENCLAW_SSH_PORT` overrides the SSH port advertised in TXT (legacy: `OPENCLAW_SSH_PORT`).
- `OPENCLAW_TAILNET_DNS` publishes a MagicDNS hint in TXT (legacy: `OPENCLAW_TAILNET_DNS`).
- `OPENCLAW_CLI_PATH` overrides the advertised CLI path (legacy: `OPENCLAW_CLI_PATH`).
## Related docs

4
docs/gateway/bridge-protocol.md
View File

@@ -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 Moltbot builds no longer ship the TCP bridge listener; this document is kept for historical reference.
**Note:** Current OpenClaw 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/moltbot.json`.
`~/.openclaw/openclaw.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.

24
docs/gateway/cli-backends.md
View File

@@ -7,7 +7,7 @@ read_when:
---
# CLI backends (fallback runtime)
Moltbot can run **local AI CLIs** as a **text-only fallback** when API providers are down,
OpenClaw 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** (Moltbot ships a built-in default):
You can use Claude Code CLI **without any config** (OpenClaw ships a built-in default):
```bash
moltbot agent --message "hi" --model claude-cli/opus-4.5
openclaw agent --message "hi" --model claude-cli/opus-4.5
```
Codex CLI also works out of the box:
```bash
moltbot agent --message "hi" --model codex-cli/gpt-5.2-codex
openclaw 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), Moltbot will
- If the primary provider fails (auth, rate limits, timeouts), OpenClaw 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 Moltbot prompt + workspace context.
2) **Builds a system prompt** using the same OpenClaw 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"
```
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
OpenClaw will write base64 images to temp files. If `imageArg` is set, those
paths are passed as CLI args. If `imageArg` is missing, OpenClaw 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)
Moltbot ships a default for `claude-cli`:
OpenClaw ships a default for `claude-cli`:
- `command: "claude"`
- `args: ["-p", "--output-format", "json", "--dangerously-skip-permissions"]`
@@ -189,7 +189,7 @@ Moltbot ships a default for `claude-cli`:
- `systemPromptWhen: "first"`
- `sessionMode: "always"`
Moltbot also ships a default for `codex-cli`:
OpenClaw 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 Moltbot tools** (the CLI backend never receives tool calls). Some CLIs
- **No OpenClaw 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. Moltbot sessions still work
structured than the initial `--json` run. OpenClaw sessions still work
normally.
## Troubleshooting

48
docs/gateway/configuration-examples.md
View File

@@ -1,9 +1,9 @@
---
summary: "Schema-accurate configuration examples for common Moltbot setups"
summary: "Schema-accurate configuration examples for common OpenClaw setups"
read_when:
- Learning how to configure Moltbot
- Learning how to configure OpenClaw
- Looking for configuration examples
- Setting up Moltbot for the first time
- Setting up OpenClaw for the first time
---
# Configuration Examples
@@ -14,12 +14,12 @@ Examples below are aligned with the current config schema. For the exhaustive re
### Absolute minimum
```json5
{
agent: { workspace: "~/clawd" },
agent: { workspace: "~/.openclaw/workspace" },
channels: { whatsapp: { allowFrom: ["+15555550123"] } }
}
```
Save to `~/.clawdbot/moltbot.json` and you can DM the bot from that number.
Save to `~/.openclaw/openclaw.json` and you can DM the bot from that number.
### Recommended starter
```json5
@@ -30,7 +30,7 @@ Save to `~/.clawdbot/moltbot.json` and you can DM the bot from that number.
emoji: "🦞"
},
agent: {
workspace: "~/clawd",
workspace: "~/.openclaw/workspace",
model: { primary: "anthropic/claude-sonnet-4-5" }
},
channels: {
@@ -85,7 +85,7 @@ Save to `~/.clawdbot/moltbot.json` and you can DM the bot from that number.
// Logging
logging: {
level: "info",
file: "/tmp/moltbot/moltbot.log",
file: "/tmp/openclaw/openclaw.log",
consoleLevel: "info",
consoleStyle: "pretty",
redactSensitive: "tools"
@@ -93,7 +93,7 @@ Save to `~/.clawdbot/moltbot.json` and you can DM the bot from that number.
// Message formatting
messages: {
messagePrefix: "[moltbot]",
messagePrefix: "[openclaw]",
responsePrefix: ">",
ackReaction: "👀",
ackReactionScope: "group-mentions"
@@ -102,7 +102,7 @@ Save to `~/.clawdbot/moltbot.json` and you can DM the bot from that number.
// Routing + queue
routing: {
groupChat: {
mentionPatterns: ["@clawd", "moltbot"],
mentionPatterns: ["@openclaw", "openclaw"],
historyLimit: 50
},
queue: {
@@ -155,7 +155,7 @@ Save to `~/.clawdbot/moltbot.json` and you can DM the bot from that number.
discord: { mode: "idle", idleMinutes: 10080 }
},
resetTriggers: ["/new", "/reset"],
store: "~/.clawdbot/agents/default/sessions/sessions.json",
store: "~/.openclaw/agents/default/sessions/sessions.json",
typingIntervalSeconds: 5,
sendPolicy: {
default: "allow",
@@ -190,7 +190,7 @@ Save to `~/.clawdbot/moltbot.json` and you can DM the bot from that number.
dm: { enabled: true, allowFrom: ["steipete"] },
guilds: {
"123456789012345678": {
slug: "friends-of-clawd",
slug: "friends-of-openclaw",
requireMention: false,
channels: {
general: { allow: true },
@@ -210,7 +210,7 @@ Save to `~/.clawdbot/moltbot.json` and you can DM the bot from that number.
dm: { enabled: true, allowFrom: ["U123"] },
slashCommand: {
enabled: true,
name: "clawd",
name: "openclaw",
sessionPrefix: "slack:slash",
ephemeral: true
}
@@ -220,7 +220,7 @@ Save to `~/.clawdbot/moltbot.json` and you can DM the bot from that number.
// Agent runtime
agents: {
defaults: {
workspace: "~/clawd",
workspace: "~/.openclaw/workspace",
userTimezone: "America/Chicago",
model: {
primary: "anthropic/claude-sonnet-4-5",
@@ -273,9 +273,9 @@ Save to `~/.clawdbot/moltbot.json` and you can DM the bot from that number.
sandbox: {
mode: "non-main",
perSession: true,
workspaceRoot: "~/.clawdbot/sandboxes",
workspaceRoot: "~/.openclaw/sandboxes",
docker: {
image: "moltbot-sandbox:bookworm-slim",
image: "openclaw-sandbox:bookworm-slim",
workdir: "/workspace",
readOnlyRoot: true,
tmpfs: ["/tmp", "/var/tmp", "/run"],
@@ -340,7 +340,7 @@ Save to `~/.clawdbot/moltbot.json` and you can DM the bot from that number.
// Cron jobs
cron: {
enabled: true,
store: "~/.clawdbot/cron/cron.json",
store: "~/.openclaw/cron/cron.json",
maxConcurrentRuns: 2
},
@@ -350,7 +350,7 @@ Save to `~/.clawdbot/moltbot.json` and you can DM the bot from that number.
path: "/hooks",
token: "shared-secret",
presets: ["gmail"],
transformsDir: "~/.clawdbot/hooks",
transformsDir: "~/.openclaw/hooks",
mappings: [
{
id: "gmail-hook",
@@ -370,7 +370,7 @@ Save to `~/.clawdbot/moltbot.json` and you can DM the bot from that number.
}
],
gmail: {
account: "moltbot@gmail.com",
account: "openclaw@gmail.com",
label: "INBOX",
topic: "projects/<project-id>/topics/gog-gmail-watch",
subscription: "gog-gmail-watch-push",
@@ -389,7 +389,7 @@ Save to `~/.clawdbot/moltbot.json` and you can DM the bot from that number.
mode: "local",
port: 18789,
bind: "loopback",
controlUi: { enabled: true, basePath: "/moltbot" },
controlUi: { enabled: true, basePath: "/openclaw" },
auth: {
mode: "token",
token: "gateway-token",
@@ -426,7 +426,7 @@ Save to `~/.clawdbot/moltbot.json` and you can DM the bot from that number.
### Multi-platform setup
```json5
{
agent: { workspace: "~/clawd" },
agent: { workspace: "~/.openclaw/workspace" },
channels: {
whatsapp: { allowFrom: ["+15555550123"] },
telegram: {
@@ -463,7 +463,7 @@ Save to `~/.clawdbot/moltbot.json` and you can DM the bot from that number.
}
},
agent: {
workspace: "~/clawd",
workspace: "~/.openclaw/workspace",
model: {
primary: "anthropic/claude-sonnet-4-5",
fallbacks: ["anthropic/claude-opus-4-5"]
@@ -501,7 +501,7 @@ Save to `~/.clawdbot/moltbot.json` and you can DM the bot from that number.
}
},
agent: {
workspace: "~/clawd",
workspace: "~/.openclaw/workspace",
model: {
primary: "anthropic/claude-opus-4-5",
fallbacks: ["minimax/MiniMax-M2.1"]
@@ -518,7 +518,7 @@ Save to `~/.clawdbot/moltbot.json` and you can DM the bot from that number.
theme: "professional assistant"
},
agent: {
workspace: "~/work-clawd",
workspace: "~/work-openclaw",
elevated: { enabled: false }
},
channels: {
@@ -538,7 +538,7 @@ Save to `~/.clawdbot/moltbot.json` and you can DM the bot from that number.
```json5
{
agent: {
workspace: "~/clawd",
workspace: "~/.openclaw/workspace",
model: { primary: "lmstudio/minimax-m2.1-gs32" }
},
models: {

295
docs/gateway/configuration.md
View File

@@ -1,13 +1,13 @@
---
summary: "All configuration options for ~/.clawdbot/moltbot.json with examples"
summary: "All configuration options for ~/.openclaw/openclaw.json with examples"
read_when:
- Adding or modifying config fields
---
# Configuration 🔧
Moltbot reads an optional **JSON5** config from `~/.clawdbot/moltbot.json` (comments + trailing commas allowed).
OpenClaw reads an optional **JSON5** config from `~/.openclaw/openclaw.json` (comments + trailing commas allowed).
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:
If the file is missing, OpenClaw uses safe-ish defaults (embedded Pi agent + per-sender sessions + workspace `~/.openclaw/workspace`). 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, Moltbot uses safe-ish defaults (embedded Pi agent + per-
## Strict config validation
Moltbot only accepts configurations that fully match the schema.
OpenClaw 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: `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.
- Only diagnostic commands are allowed (for example: `openclaw doctor`, `openclaw logs`, `openclaw health`, `openclaw status`, `openclaw service`, `openclaw help`).
- Run `openclaw doctor` to see the exact issues.
- Run `openclaw 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 `moltbot config set`. Keep a backup of `~/.clawdbot/moltbot.json`.
use `config.patch` or `openclaw config set`. Keep a backup of `~/.openclaw/openclaw.json`.
Params:
- `raw` (string) — JSON5 payload for the entire config
@@ -59,9 +59,9 @@ Params:
Example (via `gateway call`):
```bash
moltbot gateway call config.get --params '{}' # capture payload.hash
moltbot gateway call config.apply --params '{
"raw": "{\\n agents: { defaults: { workspace: \\"~/clawd\\" } }\\n}\\n",
openclaw gateway call config.get --params '{}' # capture payload.hash
openclaw gateway call config.apply --params '{
"raw": "{\\n agents: { defaults: { workspace: \\"~/.openclaw/workspace\\" } }\\n}\\n",
"baseHash": "<hash-from-config.get>",
"sessionKey": "agent:main:whatsapp:dm:+15555550123",
"restartDelayMs": 1000
@@ -88,8 +88,8 @@ Params:
Example:
```bash
moltbot gateway call config.get --params '{}' # capture payload.hash
moltbot gateway call config.patch --params '{
openclaw gateway call config.get --params '{}' # capture payload.hash
openclaw 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",
@@ -101,7 +101,7 @@ moltbot gateway call config.patch --params '{
```json5
{
agents: { defaults: { workspace: "~/clawd" } },
agents: { defaults: { workspace: "~/.openclaw/workspace" } },
channels: { whatsapp: { allowFrom: ["+15555550123"] } }
}
```
@@ -118,11 +118,11 @@ To prevent the bot from responding to WhatsApp @-mentions in groups (only respon
```json5
{
agents: {
defaults: { workspace: "~/clawd" },
defaults: { workspace: "~/.openclaw/workspace" },
list: [
{
id: "main",
groupChat: { mentionPatterns: ["@clawd", "reisponde"] }
groupChat: { mentionPatterns: ["@openclaw", "reisponde"] }
}
]
},
@@ -146,7 +146,7 @@ Split your config into multiple files using the `$include` directive. This is us
### Basic usage
```json5
// ~/.clawdbot/moltbot.json
// ~/.openclaw/openclaw.json
{
gateway: { port: 18789 },
@@ -164,11 +164,11 @@ Split your config into multiple files using the `$include` directive. This is us
```
```json5
// ~/.clawdbot/agents.json5
// ~/.openclaw/agents.json5
{
defaults: { sandbox: { mode: "all", scope: "session" } },
list: [
{ id: "main", workspace: "~/clawd" }
{ id: "main", workspace: "~/.openclaw/workspace" }
]
}
```
@@ -208,7 +208,7 @@ Included files can themselves contain `$include` directives (up to 10 levels dee
```json5
{ "$include": "./sub/config.json5" } // relative
{ "$include": "/etc/moltbot/base.json5" } // absolute
{ "$include": "/etc/openclaw/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/moltbot.json
// ~/.openclaw/openclaw.json
{
gateway: { port: 18789, auth: { token: "secret" } },
@@ -248,7 +248,7 @@ Included files can themselves contain `$include` directives (up to 10 levels dee
```
```json5
// ~/.clawdbot/clients/mueller/agents.json5
// ~/.openclaw/clients/mueller/agents.json5
[
{ id: "mueller-transcribe", workspace: "~/clients/mueller/transcribe" },
{ id: "mueller-docs", workspace: "~/clients/mueller/docs" }
@@ -256,7 +256,7 @@ Included files can themselves contain `$include` directives (up to 10 levels dee
```
```json5
// ~/.clawdbot/clients/mueller/broadcast.json5
// ~/.openclaw/clients/mueller/broadcast.json5
{
"120363403215116621@g.us": ["mueller-transcribe", "mueller-docs"]
}
@@ -266,11 +266,11 @@ Included files can themselves contain `$include` directives (up to 10 levels dee
### Env vars + `.env`
Moltbot reads env vars from the parent process (shell, launchd/systemd, CI, etc.).
OpenClaw reads env vars from the parent process (shell, launchd/systemd, CI, etc.).
Additionally, it loads:
- `.env` from the current working directory (if present)
- a global fallback `.env` from `~/.clawdbot/.env` (aka `$CLAWDBOT_STATE_DIR/.env`)
- a global fallback `.env` from `~/.openclaw/.env` (aka `$OPENCLAW_STATE_DIR/.env`)
Neither `.env` file overrides existing env vars.
@@ -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, Moltbot 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, OpenClaw runs your login shell and imports only the missing expected keys (never overrides).
This effectively sources your shell profile.
```json5
@@ -307,8 +307,8 @@ This effectively sources your shell profile.
```
Env var equivalent:
- `CLAWDBOT_LOAD_SHELL_ENV=1`
- `CLAWDBOT_SHELL_ENV_TIMEOUT_MS=15000`
- `OPENCLAW_LOAD_SHELL_ENV=1`
- `OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000`
### Env var substitution in config
@@ -326,7 +326,7 @@ You can reference environment variables directly in any config string value usin
},
gateway: {
auth: {
token: "${CLAWDBOT_GATEWAY_TOKEN}"
token: "${OPENCLAW_GATEWAY_TOKEN}"
}
}
}
@@ -354,25 +354,25 @@ You can reference environment variables directly in any config string value usin
### Auth storage (OAuth + API keys)
Moltbot stores **per-agent** auth profiles (OAuth + API keys) in:
- `<agentDir>/auth-profiles.json` (default: `~/.clawdbot/agents/<agentId>/agent/auth-profiles.json`)
OpenClaw stores **per-agent** auth profiles (OAuth + API keys) in:
- `<agentDir>/auth-profiles.json` (default: `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`)
See also: [/concepts/oauth](/concepts/oauth)
Legacy OAuth imports:
- `~/.clawdbot/credentials/oauth.json` (or `$CLAWDBOT_STATE_DIR/credentials/oauth.json`)
- `~/.openclaw/credentials/oauth.json` (or `$OPENCLAW_STATE_DIR/credentials/oauth.json`)
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 `moltbot doctor` into `~/.clawdbot/agents/<defaultAgentId>/agent/*`)
- `~/.openclaw/agent/*` (migrated by `openclaw doctor` into `~/.openclaw/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)
- OAuth dir (legacy import only): `OPENCLAW_OAUTH_DIR`
- Agent dir (default agent root override): `OPENCLAW_AGENT_DIR` (preferred), `PI_CODING_AGENT_DIR` (legacy)
On first use, Moltbot imports `oauth.json` entries into `auth-profiles.json`.
On first use, OpenClaw 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, Moltbot derives defaults (only when you haven’t set them explicitly):
If set, OpenClaw 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/moltbot/moltbot-YYYY-MM-DD.log`
- If you want a stable path, set `logging.file` to `/tmp/moltbot/moltbot.log`.
- Default log file: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`
- If you want a stable path, set `logging.file` to `/tmp/openclaw/openclaw.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/moltbot/moltbot.log",
file: "/tmp/openclaw/openclaw.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:
- `moltbot pairing list whatsapp`
- `moltbot pairing approve whatsapp <code>`
- `openclaw pairing list whatsapp`
- `openclaw pairing approve whatsapp <code>`
### `channels.whatsapp.allowFrom`
@@ -532,8 +532,8 @@ Run multiple WhatsApp accounts in one gateway:
default: {}, // optional; keeps the default id stable
personal: {},
biz: {
// Optional override. Default: ~/.clawdbot/credentials/whatsapp/biz
// authDir: "~/.clawdbot/credentials/whatsapp/biz",
// Optional override. Default: ~/.openclaw/credentials/whatsapp/biz
// authDir: "~/.openclaw/credentials/whatsapp/biz",
}
}
}
@@ -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 `moltbot doctor` into `whatsapp/default`.
- The legacy single-account Baileys auth dir is migrated by `openclaw 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", "moltbot", "clawd"] } }
{ id: "main", groupChat: { mentionPatterns: ["@openclaw", "openclaw"] } }
]
}
}
@@ -652,7 +652,7 @@ To respond **only** to specific text triggers (ignoring native @-mentions):
id: "main",
groupChat: {
// Only these text patterns will trigger responses
mentionPatterns: ["reisponde", "@clawd"]
mentionPatterns: ["reisponde", "@openclaw"]
}
}
]
@@ -723,8 +723,8 @@ Inbound messages are routed to an agent via bindings.
- `default`: optional; when multiple are set, the first wins and a warning is logged.
If none are set, the **first entry** in the list is the default agent.
- `name`: display name for the agent.
- `workspace`: default `~/clawd-<agentId>` (for `main`, falls back to `agents.defaults.workspace`).
- `agentDir`: default `~/.clawdbot/agents/<agentId>/agent`.
- `workspace`: default `~/.openclaw/workspace-<agentId>` (for `main`, falls back to `agents.defaults.workspace`).
- `agentDir`: default `~/.openclaw/agents/<agentId>/agent`.
- `model`: per-agent default model, overrides `agents.defaults.model` for that agent.
- string form: `"provider/model"`, overrides only `agents.defaults.model.primary`
- object form: `{ primary, fallbacks }` (fallbacks override `agents.defaults.model.fallbacks`; `[]` disables global fallbacks for that agent)
@@ -779,7 +779,7 @@ Full access (no sandbox):
list: [
{
id: "personal",
workspace: "~/clawd-personal",
workspace: "~/.openclaw/workspace-personal",
sandbox: { mode: "off" }
}
]
@@ -794,7 +794,7 @@ Read-only tools + read-only workspace:
list: [
{
id: "family",
workspace: "~/clawd-family",
workspace: "~/.openclaw/workspace-family",
sandbox: {
mode: "all",
scope: "agent",
@@ -817,7 +817,7 @@ No filesystem access (messaging/session tools enabled):
list: [
{
id: "public",
workspace: "~/clawd-public",
workspace: "~/.openclaw/workspace-public",
sandbox: {
mode: "all",
scope: "agent",
@@ -839,8 +839,8 @@ Example: two WhatsApp accounts → two agents:
{
agents: {
list: [
{ id: "home", default: true, workspace: "~/clawd-home" },
{ id: "work", workspace: "~/clawd-work" }
{ id: "home", default: true, workspace: "~/.openclaw/workspace-home" },
{ id: "work", workspace: "~/.openclaw/workspace-work" }
]
},
bindings: [
@@ -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 `moltbot.json`).
- `commands.config: true` enables `/config` (reads/writes `openclaw.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)
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.
OpenClaw 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`).
@@ -1083,11 +1083,11 @@ Multi-account support lives under `channels.discord.accounts` (see the multi-acc
policy: "pairing", // pairing | allowlist | open | disabled
allowFrom: ["1234567890", "steipete"], // optional DM allowlist ("open" requires ["*"])
groupEnabled: false, // enable group DMs
groupChannels: ["clawd-dm"] // optional group DM allowlist
groupChannels: ["openclaw-dm"] // optional group DM allowlist
},
guilds: {
"123456789012345678": { // guild id (preferred) or slug
slug: "friends-of-clawd",
slug: "friends-of-openclaw",
requireMention: false, // per-guild default
reactionNotifications: "own", // off | own | all | allowlist
users: ["987654321098765432"], // optional per-guild user allowlist
@@ -1118,7 +1118,7 @@ Multi-account support lives under `channels.discord.accounts` (see the multi-acc
}
```
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.
OpenClaw 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:
@@ -1214,7 +1214,7 @@ Slack runs in Socket Mode and requires both a bot token and app token:
},
slashCommand: {
enabled: true,
name: "clawd",
name: "openclaw",
sessionPrefix: "slack:slash",
ephemeral: true
},
@@ -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.
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.
OpenClaw 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: `moltbot plugins install @moltbot/mattermost` (or `./extensions/mattermost` from a git checkout).
Install it first: `openclaw plugins install @openclaw/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:
}
```
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`).
OpenClaw 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)
Moltbot spawns `imsg rpc` (JSON-RPC over stdio). No daemon or port required.
OpenClaw spawns `imsg rpc` (JSON-RPC over stdio). No daemon or port required.
```json5
{
@@ -1356,11 +1356,11 @@ exec ssh -T gateway-host imsg "$@"
Sets the **single global workspace directory** used by the agent for file operations.
Default: `~/clawd`.
Default: `~/.openclaw/workspace`.
```json5
{
agents: { defaults: { workspace: "~/clawd" } }
agents: { defaults: { workspace: "~/.openclaw/workspace" } }
}
```
@@ -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, Moltbot
Optional repository root to show in the system prompt’s Runtime line. If unset, OpenClaw
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/moltbot" } }
agents: { defaults: { repoRoot: "~/Projects/openclaw" } }
}
```
@@ -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, Moltbot logs a warning and injects a truncated
When a file exceeds this limit, OpenClaw 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, Moltbot uses the host timezone at runtime.
message envelopes). If unset, OpenClaw 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
`[moltbot]`, so same-phone conversations stay legible.
`[openclaw]`, 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**: `"[moltbot]"` when
`messages.messagePrefix`). Default stays **unchanged**: `"[openclaw]"` when
`channels.whatsapp.allowFrom` is empty, otherwise `""` (no prefix). When using
`"[moltbot]"`, Moltbot will instead use `[{identity.name}]` when the routed
`"[openclaw]"`, OpenClaw 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, Moltbot generates audio
Enable text-to-speech for outbound replies. When on, OpenClaw generates audio
using ElevenLabs or OpenAI and attaches it to responses. Telegram uses Opus
voice notes; other channels send MP3 audio.
@@ -1514,7 +1514,7 @@ voice notes; other channels send MP3 audio.
},
maxTextLength: 4000,
timeoutMs: 30000,
prefsPath: "~/.clawdbot/settings/tts.json",
prefsPath: "~/.openclaw/settings/tts.json",
elevenlabs: {
apiKey: "elevenlabs_api_key",
baseUrl: "https://api.elevenlabs.io",
@@ -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.
Moltbot also ships a few built-in alias shorthands. Defaults only apply when the model
OpenClaw 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, Moltbot currently assumes `anthropic` as a temporary
If you omit the provider, OpenClaw 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 `moltbot configure --section web`, or use `BRAVE_API_KEY` env var)
- `tools.web.search.apiKey` (recommended: set via `openclaw 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:moltbot`: all built-in Moltbot tools (excludes provider plugins)
- `group:openclaw`: all built-in OpenClaw tools (excludes provider plugins)
`tools.elevated` controls elevated (host) exec access:
- `enabled`: allow elevated mode (default true)
@@ -2165,7 +2165,7 @@ Defaults (if enabled):
- scope: `"agent"` (one container + workspace per agent)
- Debian bookworm-slim based image
- agent workspace access: `workspaceAccess: "none"` (default)
- `"none"`: use a per-scope sandbox workspace under `~/.clawdbot/sandboxes`
- `"none"`: use a per-scope sandbox workspace under `~/.openclaw/sandboxes`
- `"ro"`: keep the sandbox workspace at `/workspace`, and mount the agent workspace read-only at `/agent` (disables `write`/`edit`/`apply_patch`)
- `"rw"`: mount the agent workspace read/write at `/workspace`
- auto-prune: idle > 24h OR age > 7d
@@ -2192,10 +2192,10 @@ For package installs, ensure network egress, a writable root FS, and a root user
mode: "non-main", // off | non-main | all
scope: "agent", // session | agent | shared (agent is default)
workspaceAccess: "none", // none | ro | rw
workspaceRoot: "~/.clawdbot/sandboxes",
workspaceRoot: "~/.openclaw/sandboxes",
docker: {
image: "moltbot-sandbox:bookworm-slim",
containerPrefix: "moltbot-sbx-",
image: "openclaw-sandbox:bookworm-slim",
containerPrefix: "openclaw-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: "moltbot-sandbox",
apparmorProfile: "openclaw-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: "moltbot-sandbox-browser:bookworm-slim",
containerPrefix: "moltbot-sbx-browser-",
image: "openclaw-sandbox-browser:bookworm-slim",
containerPrefix: "openclaw-sbx-browser-",
cdpPort: 9222,
vncPort: 5900,
noVncPort: 6080,
@@ -2289,14 +2289,14 @@ Defaults: all allowlists are unset (no restriction). `allowHostControl` defaults
### `models` (custom providers + base URLs)
Moltbot uses the **pi-coding-agent** model catalog. You can add custom providers
OpenClaw 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
Moltbot config under `models.providers`.
`~/.openclaw/agents/<agentId>/agent/models.json` or by defining the same schema inside your
OpenClaw config under `models.providers`.
Provider-by-provider overview + examples: [/concepts/model-providers](/concepts/model-providers).
When `models.providers` is present, Moltbot writes/merges a `models.json` into
`~/.clawdbot/agents/<agentId>/agent/` on startup:
When `models.providers` is present, OpenClaw writes/merges a `models.json` into
`~/.openclaw/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. Moltbot uses
OpenCode Zen is a multi-model gateway with per-model endpoints. OpenClaw 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: `moltbot onboard --auth-choice opencode-zen`.
- Shortcut: `openclaw 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: `moltbot onboard --auth-choice zai-api-key`.
Shortcut: `openclaw 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 `moltbot onboard --auth-choice moonshot-api-key`.
- Set `MOONSHOT_API_KEY` in the environment or use `openclaw onboard --auth-choice moonshot-api-key`.
- Model ref: `moonshot/kimi-k2.5`.
- 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 `moltbot onboard --auth-choice kimi-code-api-key`.
- Set `KIMICODE_API_KEY` in the environment or use `openclaw 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 `moltbot onboard --auth-choice synthetic-api-key`.
- Set `SYNTHETIC_API_KEY` or use `openclaw 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 `moltbot onboard --auth-choice minimax-api`.
- Set `MINIMAX_API_KEY` environment variable or use `openclaw onboard --auth-choice minimax-api`.
- Available model: `MiniMax-M2.1` (default).
- Update pricing in `models.json` if you need exact cost tracking.
@@ -2605,8 +2605,8 @@ Notes:
- Supported APIs: `openai-completions`, `openai-responses`, `anthropic-messages`,
`google-generative-ai`
- Use `authHeader: true` + `headers` for custom auth needs.
- Override the agent config root with `CLAWDBOT_AGENT_DIR` (or `PI_CODING_AGENT_DIR`)
if you want `models.json` stored elsewhere (default: `~/.clawdbot/agents/main/agent`).
- Override the agent config root with `OPENCLAW_AGENT_DIR` (or `PI_CODING_AGENT_DIR`)
if you want `models.json` stored elsewhere (default: `~/.openclaw/agents/main/agent`).
### `session`
@@ -2631,9 +2631,9 @@ Controls session scoping, reset policy, reset triggers, and where the session st
group: { mode: "idle", idleMinutes: 120 }
},
resetTriggers: ["/new", "/reset"],
// Default is already per-agent under ~/.clawdbot/agents/<agentId>/sessions/sessions.json
// Default is already per-agent under ~/.openclaw/agents/<agentId>/sessions/sessions.json
// You can override with {agentId} templating:
store: "~/.clawdbot/agents/{agentId}/sessions/sessions.json",
store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
// Direct chats collapse to agent:<agentId>:<mainKey> (default: "main").
mainKey: "main",
agentToAgent: {
@@ -2665,7 +2665,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`, Moltbot stays in idle-only mode for backward compatibility.
- If you only set legacy `session.idleMinutes` without any `reset`/`resetByType`, OpenClaw 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.
@@ -2674,7 +2674,7 @@ Fields:
### `skills` (skills config)
Controls bundled allowlist, install preferences, extra skill folders, and per-skill
overrides. Applies to **bundled** skills and `~/.clawdbot/skills` (workspace skills
overrides. Applies to **bundled** skills and `~/.openclaw/skills` (workspace skills
still win on name conflicts).
Fields:
@@ -2723,7 +2723,7 @@ Example:
### `plugins` (extensions)
Controls plugin discovery, allow/deny, and per-plugin config. Plugins are loaded
from `~/.clawdbot/extensions`, `<workspace>/.clawdbot/extensions`, plus any
from `~/.openclaw/extensions`, `<workspace>/.openclaw/extensions`, plus any
`plugins.load.paths` entries. **Config changes require a gateway restart.**
See [/plugin](/plugin) for full usage.
@@ -2758,9 +2758,9 @@ Example:
}
```
### `browser` (clawd-managed browser)
### `browser` (openclaw-managed browser)
Moltbot can start a **dedicated, isolated** Chrome/Brave/Edge/Chromium instance for clawd and expose a small loopback control service.
OpenClaw can start a **dedicated, isolated** Chrome/Brave/Edge/Chromium instance for openclaw 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).
@@ -2773,7 +2773,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 (Moltbot.app menubar, or `moltbot gateway`).
- Note: the control server is started by the running gateway (OpenClaw.app menubar, or `openclaw gateway`).
- Auto-detect order: default browser if Chromium-based; otherwise Chrome → Brave → Edge → Chromium → Chrome Canary.
```json5
@@ -2784,7 +2784,7 @@ Defaults:
// cdpUrl: "http://127.0.0.1:18792", // legacy single-profile override
defaultProfile: "chrome",
profiles: {
clawd: { cdpPort: 18800, color: "#FF4500" },
openclaw: { cdpPort: 18800, color: "#FF4500" },
work: { cdpPort: 18801, color: "#0066CC" },
remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" }
},
@@ -2811,7 +2811,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: "Moltbot",
name: "OpenClaw",
avatar: "CB" // emoji, short text, or image URL/data URI
}
}
@@ -2833,7 +2833,7 @@ Defaults:
mode: "local", // or "remote"
port: 18789, // WS + HTTP multiplex
bind: "loopback",
// controlUi: { enabled: true, basePath: "/moltbot" }
// controlUi: { enabled: true, basePath: "/openclaw" }
// auth: { mode: "token", token: "your-token" } // token gates WS + Control UI access
// tailscale: { mode: "off" | "serve" | "funnel" }
}
@@ -2842,7 +2842,7 @@ Defaults:
Control UI base path:
- `gateway.controlUi.basePath` sets the URL prefix where the Control UI is served.
- Examples: `"/ui"`, `"/moltbot"`, `"/apps/moltbot"`.
- Examples: `"/ui"`, `"/openclaw"`, `"/apps/openclaw"`.
- 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
@@ -2858,14 +2858,14 @@ 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, Moltbot 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, OpenClaw 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:
- `moltbot gateway` refuses to start unless `gateway.mode` is set to `local` (or you pass the override flag).
- `openclaw 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`.
- Precedence: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > default `18789`.
- Gateway auth is required by default (token/password or Tailscale Serve identity). Non-loopback binds require a shared token/password.
- The onboarding wizard generates a gateway token by default (even on loopback).
- `gateway.remote.token` is **only** for remote CLI calls; it does not enable local gateway auth. `gateway.token` is ignored.
@@ -2874,10 +2874,10 @@ Auth and Tailscale:
- `gateway.auth.mode` sets the handshake requirements (`token` or `password`). When unset, token auth is assumed.
- `gateway.auth.token` stores the shared token for token auth (used by the CLI on the same machine).
- When `gateway.auth.mode` is set, only that method is accepted (plus optional Tailscale headers).
- `gateway.auth.password` can be set here, or via `CLAWDBOT_GATEWAY_PASSWORD` (recommended).
- `gateway.auth.password` can be set here, or via `OPENCLAW_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`. Moltbot
with `x-forwarded-for`, `x-forwarded-proto`, and `x-forwarded-host`. OpenClaw
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
@@ -2893,7 +2893,7 @@ Remote client defaults (CLI):
- `gateway.remote.password` supplies the password for remote calls (leave unset for no auth).
macOS app behavior:
- Moltbot.app watches `~/.clawdbot/moltbot.json` and switches modes live when `gateway.mode` or `gateway.remote.url` changes.
- OpenClaw.app watches `~/.openclaw/openclaw.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.
@@ -2927,7 +2927,7 @@ Direct transport example (macOS app):
### `gateway.reload` (Config hot reload)
The Gateway watches `~/.clawdbot/moltbot.json` (or `CLAWDBOT_CONFIG_PATH`) and applies changes automatically.
The Gateway watches `~/.openclaw/openclaw.json` (or `OPENCLAW_CONFIG_PATH`) and applies changes automatically.
Modes:
- `hybrid` (default): hot-apply safe changes; restart the Gateway for critical changes.
@@ -2949,7 +2949,7 @@ Modes:
#### Hot reload matrix (files + impact)
Files watched:
- `~/.clawdbot/moltbot.json` (or `CLAWDBOT_CONFIG_PATH`)
- `~/.openclaw/openclaw.json` (or `OPENCLAW_CONFIG_PATH`)
Hot-applied (no full gateway restart):
- `hooks` (webhook auth/path/mappings) + `hooks.gmail` (Gmail watcher restarted)
@@ -2971,23 +2971,23 @@ Requires full Gateway restart:
### Multi-instance isolation
To run multiple gateways on one host (for redundancy or a rescue bot), isolate per-instance state + config and use unique ports:
- `CLAWDBOT_CONFIG_PATH` (per-instance config)
- `CLAWDBOT_STATE_DIR` (sessions/creds)
- `OPENCLAW_CONFIG_PATH` (per-instance config)
- `OPENCLAW_STATE_DIR` (sessions/creds)
- `agents.defaults.workspace` (memories)
- `gateway.port` (unique per instance)
Convenience flags (CLI):
- `moltbot --dev …` → uses `~/.clawdbot-dev` + shifts ports from base `19001`
- `moltbot --profile <name> …` → uses `~/.clawdbot-<name>` (port via config/env/flags)
- `openclaw --dev …` → uses `~/.openclaw-dev` + shifts ports from base `19001`
- `openclaw --profile <name> …` → uses `~/.openclaw-<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.
Example:
```bash
CLAWDBOT_CONFIG_PATH=~/.clawdbot/a.json \
CLAWDBOT_STATE_DIR=~/.clawdbot-a \
moltbot gateway --port 19001
OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
OPENCLAW_STATE_DIR=~/.openclaw-a \
openclaw gateway --port 19001
```
### `hooks` (Gateway webhooks)
@@ -3006,7 +3006,7 @@ Defaults:
token: "shared-secret",
path: "/hooks",
presets: ["gmail"],
transformsDir: "~/.clawdbot/hooks",
transformsDir: "~/.openclaw/hooks",
mappings: [
{
match: { path: "gmail" },
@@ -3027,7 +3027,7 @@ Defaults:
Requests must include the hook token:
- `Authorization: Bearer <token>` **or**
- `x-moltbot-token: <token>` **or**
- `x-openclaw-token: <token>` **or**
- `?token=<token>`
Endpoints:
@@ -3046,13 +3046,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 `moltbot webhooks gmail setup` / `run`):
Gmail helper config (used by `openclaw webhooks gmail setup` / `run`):
```json5
{
hooks: {
gmail: {
account: "moltbot@gmail.com",
account: "openclaw@gmail.com",
topic: "projects/<project-id>/topics/gog-gmail-watch",
subscription: "gog-gmail-watch-push",
pushToken: "shared-push-token",
@@ -3084,11 +3084,11 @@ Model override for Gmail hooks:
Gateway auto-start:
- If `hooks.enabled=true` and `hooks.gmail.account` is set, the Gateway starts
`gog gmail watch serve` on boot and auto-renews the watch.
- Set `CLAWDBOT_SKIP_GMAIL_WATCHER=1` to disable the auto-start (for manual runs).
- Set `OPENCLAW_SKIP_GMAIL_WATCHER=1` to disable the auto-start (for manual runs).
- 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, Moltbot defaults `serve.path` to `/` so
Note: when `tailscale.mode` is on, OpenClaw 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`).
@@ -3097,16 +3097,16 @@ If you need the backend to receive the prefixed path, set
The Gateway serves a directory of HTML/CSS/JS over HTTP so iOS/Android nodes can simply `canvas.navigate` to it.
Default root: `~/clawd/canvas`
Default port: `18793` (chosen to avoid the clawd browser CDP port `18792`)
Default root: `~/.openclaw/workspace/canvas`
Default port: `18793` (chosen to avoid the openclaw browser CDP port `18792`)
The server listens on the **gateway bind host** (LAN or Tailnet) so nodes can reach it.
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 `/__moltbot/ws`
- watches the directory and broadcasts reloads over a WebSocket endpoint at `/__openclaw__/ws`
- auto-creates a starter `index.html` when the directory is empty (so you see something immediately)
- also serves A2UI at `/__moltbot__/a2ui/` and is advertised to nodes as `canvasHostUrl`
- also serves A2UI at `/__openclaw__/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`:
@@ -3115,7 +3115,7 @@ Disable live reload (and file watching) if the directory is large or you hit `EM
```json5
{
canvasHost: {
root: "~/clawd/canvas",
root: "~/.openclaw/workspace/canvas",
port: 18793,
liveReload: true
}
@@ -3126,7 +3126,7 @@ Changes to `canvasHost.*` require a gateway restart (config reload will restart)
Disable with:
- config: `canvasHost: { enabled: false }`
- env: `CLAWDBOT_SKIP_CANVAS_HOST=1`
- env: `OPENCLAW_SKIP_CANVAS_HOST=1`
### `bridge` (legacy TCP bridge, removed)
@@ -3166,9 +3166,9 @@ Auto-generated certs require `openssl` on PATH; if generation fails, the bridge
bind: "tailnet",
tls: {
enabled: true,
// Uses ~/.clawdbot/bridge/tls/bridge-{cert,key}.pem when omitted.
// certPath: "~/.clawdbot/bridge/tls/bridge-cert.pem",
// keyPath: "~/.clawdbot/bridge/tls/bridge-key.pem"
// Uses ~/.openclaw/bridge/tls/bridge-{cert,key}.pem when omitted.
// certPath: "~/.openclaw/bridge/tls/bridge-cert.pem",
// keyPath: "~/.openclaw/bridge/tls/bridge-key.pem"
}
}
}
@@ -3176,11 +3176,12 @@ Auto-generated certs require `openssl` on PATH; if generation fails, the bridge
### `discovery.mdns` (Bonjour / mDNS broadcast mode)
Controls LAN mDNS discovery broadcasts (`_moltbot-gw._tcp`).
Controls LAN mDNS discovery broadcasts (`_openclaw-gw._tcp`).
- `minimal` (default): omit `cliPath` + `sshPort` from TXT records
- `full`: include `cliPath` + `sshPort` in TXT records
- `off`: disable mDNS broadcasts entirely
- Hostname: defaults to `openclaw` (advertises `openclaw.local`). Override with `OPENCLAW_MDNS_HOSTNAME`.
```json5
{
@@ -3190,16 +3191,16 @@ Controls LAN mDNS discovery broadcasts (`_moltbot-gw._tcp`).
### `discovery.wideArea` (Wide-Area Bonjour / unicast DNS‑SD)
When enabled, the Gateway writes a unicast DNS-SD zone for `_moltbot-bridge._tcp` under `~/.clawdbot/dns/` using the standard discovery domain `moltbot.internal.`
When enabled, the Gateway writes a unicast DNS-SD zone for `_openclaw-gw._tcp` under `~/.openclaw/dns/` using the configured discovery domain (example: `openclaw.internal.`).
To make iOS/Android discover across networks (Vienna ⇄ London), pair this with:
- a DNS server on the gateway host serving `moltbot.internal.` (CoreDNS is recommended)
- Tailscale **split DNS** so clients resolve `moltbot.internal` via that server
- a DNS server on the gateway host serving your chosen domain (CoreDNS is recommended)
- Tailscale **split DNS** so clients resolve that domain via the gateway DNS server
One-time setup helper (gateway host):
```bash
moltbot dns setup --apply
openclaw dns setup --apply
```
```json5

20
docs/gateway/discovery.md
View File

@@ -7,12 +7,12 @@ read_when:
---
# Discovery & transports
Moltbot has two distinct problems that look similar on the surface:
OpenClaw 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` / `moltbot gateway`) and keep clients (mac app, iOS) as consumers.
The design goal is to keep all network discovery/advertising in the **Node Gateway** (`openclaw 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:
- `_moltbot-gw._tcp` (gateway transport beacon)
- `_openclaw-gw._tcp` (gateway transport beacon)
- TXT keys (non-secret):
- `role=gateway`
- `lanHost=<hostname>.local`
@@ -60,16 +60,16 @@ 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 `/__moltbot__/canvas/`)
- `cliPath=<path>` (optional; absolute path to a runnable `moltbot` entrypoint or binary)
- `canvasPort=18793` (default canvas host port; serves `/__openclaw__/canvas/`)
- `cliPath=<path>` (optional; absolute path to a runnable `openclaw` 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/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.
- `OPENCLAW_DISABLE_BONJOUR=1` disables advertising.
- `gateway.bind` in `~/.openclaw/openclaw.json` controls the Gateway bind mode.
- `OPENCLAW_SSH_PORT` overrides the SSH port advertised in TXT (defaults to 22).
- `OPENCLAW_TAILNET_DNS` publishes a `tailnetDns` hint (MagicDNS).
- `OPENCLAW_CLI_PATH` overrides the advertised CLI path.
### 2) Tailnet (cross-network)

54
docs/gateway/doctor.md
View File

@@ -6,44 +6,44 @@ read_when:
---
# Doctor
`moltbot doctor` is the repair + migration tool for Moltbot. It fixes stale
`openclaw doctor` is the repair + migration tool for OpenClaw. It fixes stale
config/state, checks health, and provides actionable repair steps.
## Quick start
```bash
moltbot doctor
openclaw doctor
```
### Headless / automation
```bash
moltbot doctor --yes
openclaw doctor --yes
```
Accept defaults without prompting (including restart/service/sandbox repair steps when applicable).
```bash
moltbot doctor --repair
openclaw doctor --repair
```
Apply recommended repairs without prompting (repairs + restarts where safe).
```bash
moltbot doctor --repair --force
openclaw doctor --repair --force
```
Apply aggressive repairs too (overwrites custom supervisor configs).
```bash
moltbot doctor --non-interactive
openclaw 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
moltbot doctor --deep
openclaw 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/moltbot.json
cat ~/.openclaw/openclaw.json
```
## What it does (summary)
@@ -65,7 +65,7 @@ cat ~/.clawdbot/moltbot.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 (`~/moltbot`).
- Extra workspace dir detection (`~/openclaw`).
- 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 `moltbot doctor`.
you to run `openclaw doctor`.
Doctor will:
- Explain which legacy keys were found.
- Show the migration it applied.
- Rewrite `~/.clawdbot/moltbot.json` with the updated schema.
- Rewrite `~/.openclaw/openclaw.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.
@@ -127,18 +127,18 @@ remove the override and restore per-model API routing + costs.
### 3) Legacy state migrations (disk layout)
Doctor can migrate older on-disk layouts into the current structure:
- Sessions store + transcripts:
- from `~/.clawdbot/sessions/` to `~/.clawdbot/agents/<agentId>/sessions/`
- from `~/.openclaw/sessions/` to `~/.openclaw/agents/<agentId>/sessions/`
- Agent dir:
- from `~/.clawdbot/agent/` to `~/.clawdbot/agents/<agentId>/agent/`
- from `~/.openclaw/agent/` to `~/.openclaw/agents/<agentId>/agent/`
- WhatsApp auth state (Baileys):
- from legacy `~/.clawdbot/credentials/*.json` (except `oauth.json`)
- to `~/.clawdbot/credentials/whatsapp/<accountId>/...` (default account id: `default`)
- from legacy `~/.openclaw/credentials/*.json` (except `oauth.json`)
- to `~/.openclaw/credentials/whatsapp/<accountId>/...` (default account id: `default`)
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 `moltbot doctor`.
migrated via `openclaw doctor`.
### 4) State integrity checks (session persistence, routing, and safety)
The state directory is the operational brainstem. If it vanishes, you lose
@@ -155,12 +155,12 @@ Doctor checks:
transcript files.
- **Main session “1-line JSONL”**: flags when the main transcript has only one
line (history is not accumulating).
- **Multiple state dirs**: warns when multiple `~/.clawdbot` folders exist across
home directories or when `CLAWDBOT_STATE_DIR` points elsewhere (history can
- **Multiple state dirs**: warns when multiple `~/.openclaw` folders exist across
home directories or when `OPENCLAW_STATE_DIR` points elsewhere (history can
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/moltbot.json` is
- **Config file permissions**: warns if `~/.openclaw/openclaw.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 Moltbot service using the current gateway
offers to remove them and install the OpenClaw service using the current gateway
port. It can also scan for extra gateway-like services and print cleanup hints.
Profile-named Moltbot gateway services are considered first-class and are not
Profile-named OpenClaw 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 `moltbot doctor --generate-gateway-token` to force token
generate a token. Use `openclaw 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:
- `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`.
- `openclaw doctor` prompts before rewriting supervisor config.
- `openclaw doctor --yes` accepts the default repair prompts.
- `openclaw doctor --repair` applies recommended fixes without prompts.
- `openclaw doctor --repair --force` overwrites custom supervisor configs.
- You can always force a full rewrite via `openclaw gateway install --force`.
### 16) Gateway runtime + port diagnostics
Doctor inspects the service runtime (PID, last exit status) and warns when the

2
docs/gateway/gateway-lock.md
View File

@@ -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 `moltbot gateway --port <port>`.
- If the port is occupied by *another* process, the error is the same; free the port or choose another with `openclaw 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.

22
docs/gateway/health.md
View File

@@ -8,22 +8,22 @@ read_when:
Short guide to verify channel connectivity without guessing.
## Quick checks
- `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).
- `openclaw status` — local summary: gateway reachability/mode, update hint, linked channel auth age, sessions + recent activity.
- `openclaw status --all` — full local diagnosis (read-only, color, safe to paste for debugging).
- `openclaw status --deep` — also probes the running Gateway (per-channel probes when supported).
- `openclaw 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/moltbot/moltbot-*.log` and filter for `web-heartbeat`, `web-reconnect`, `web-auto-reply`, `web-inbound`.
- Logs: tail `/tmp/openclaw/openclaw-*.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: `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.)
- Creds on disk: `ls -l ~/.openclaw/credentials/whatsapp/<accountId>/creds.json` (mtime should be recent).
- Session store: `ls -l ~/.openclaw/agents/<agentId>/sessions/sessions.json` (path can be overridden in config). Count and recent recipients are surfaced via `status`.
- Relink flow: `openclaw channels logout && openclaw 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 `moltbot channels logout` then `moltbot channels login`.
- Gateway unreachable → start it: `moltbot gateway --port 18789` (use `--force` if the port is busy).
- `logged out` or status 409–515 → relink with `openclaw channels logout` then `openclaw channels login`.
- Gateway unreachable → start it: `openclaw 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
`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.
`openclaw 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.

10
docs/gateway/heartbeat.md
View File

@@ -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, Moltbot treats `HEARTBEAT_OK` as an ack when it appears
- During heartbeat runs, OpenClaw 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 `moltbot sessions --json` or the [sessions CLI](/cli/sessions)).
- Explicit session key (copy from `openclaw 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, Moltbot skips the heartbeat run entirely (no model call).
If **all three** are false, OpenClaw 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`), Moltbot skips the heartbeat run to save API calls.
headers like `# Heading`), OpenClaw 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
moltbot system event --text "Check for urgent follow-ups" --mode now
openclaw system event --text "Check for urgent follow-ups" --mode now
```
If multiple agents have `heartbeat` configured, a manual wake runs each of those

126
docs/gateway/index.md
View File

@@ -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: `moltbot gateway`.
- Replaces the legacy `gateway` command. CLI entry point: `openclaw gateway`.
- Runs until stopped; exits non-zero on fatal errors so the supervisor restarts it.
## How to run (local)
```bash
moltbot gateway --port 18789
openclaw gateway --port 18789
# for full debug/trace logs in stdio:
moltbot gateway --port 18789 --verbose
openclaw gateway --port 18789 --verbose
# if the port is busy, terminate listeners then start:
moltbot gateway --force
openclaw gateway --force
# dev loop (auto-reload on TS changes):
pnpm gateway:watch
```
- Config hot reload watches `~/.clawdbot/moltbot.json` (or `CLAWDBOT_CONFIG_PATH`).
- Config hot reload watches `~/.openclaw/openclaw.json` (or `OPENCLAW_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,15 +31,15 @@ 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/__moltbot__/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/__openclaw__/canvas/` from `~/.openclaw/workspace/canvas`. Disable with `canvasHost.enabled=false` or `OPENCLAW_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).
- If you run under a supervisor (launchd/systemd/mac app child-process mode), a stop/restart typically sends **SIGTERM**; older builds may surface this as `pnpm` `ELIFECYCLE` exit code **143** (SIGTERM), which is a normal shutdown, not a crash.
- **SIGUSR1** triggers an in-process restart when authorized (gateway tool/config apply/update, or enable `commands.restart` for manual restarts).
- Gateway auth is required by default: set `gateway.auth.token` (or `CLAWDBOT_GATEWAY_TOKEN`) or `gateway.auth.password`. Clients must send `connect.params.auth.token/password` unless using Tailscale Serve identity.
- Gateway auth is required by default: set `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`) or `gateway.auth.password`. Clients must send `connect.params.auth.token/password` unless using Tailscale Serve identity.
- The wizard now generates a token by default, even on loopback.
- Port precedence: `--port` > `CLAWDBOT_GATEWAY_PORT` > `gateway.port` > default `18789`.
- Port precedence: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > default `18789`.
## Remote access
- Tailscale/VPN preferred; otherwise SSH tunnel:
@@ -56,14 +56,14 @@ Usually unnecessary: one Gateway can serve multiple messaging channels and agent
Supported if you isolate state + config and use unique ports. Full guide: [Multiple gateways](/gateway/multiple-gateways).
Service names are profile-aware:
- macOS: `bot.molt.<profile>` (legacy `com.clawdbot.*` may still exist)
- Linux: `moltbot-gateway-<profile>.service`
- Windows: `Moltbot Gateway (<profile>)`
- macOS: `bot.molt.<profile>` (legacy `com.openclaw.*` may still exist)
- Linux: `openclaw-gateway-<profile>.service`
- Windows: `OpenClaw Gateway (<profile>)`
Install metadata is embedded in the service config:
- `CLAWDBOT_SERVICE_MARKER=moltbot`
- `CLAWDBOT_SERVICE_KIND=gateway`
- `CLAWDBOT_SERVICE_VERSION=<version>`
- `OPENCLAW_SERVICE_MARKER=openclaw`
- `OPENCLAW_SERVICE_KIND=gateway`
- `OPENCLAW_SERVICE_VERSION=<version>`
Rescue-Bot Pattern: keep a second Gateway isolated with its own profile, state dir, workspace, and base port spacing. Full guide: [Rescue-bot guide](/gateway/multiple-gateways#rescue-bot-guide).
@@ -72,44 +72,44 @@ 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
moltbot --dev setup
moltbot --dev gateway --allow-unconfigured
openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
# then target the dev instance:
moltbot --dev status
moltbot --dev health
openclaw --dev status
openclaw --dev health
```
Defaults (can be overridden via env/flags/config):
- `CLAWDBOT_STATE_DIR=~/.clawdbot-dev`
- `CLAWDBOT_CONFIG_PATH=~/.clawdbot-dev/moltbot.json`
- `CLAWDBOT_GATEWAY_PORT=19001` (Gateway WS + HTTP)
- `OPENCLAW_STATE_DIR=~/.openclaw-dev`
- `OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json`
- `OPENCLAW_GATEWAY_PORT=19001` (Gateway WS + HTTP)
- browser control service port = `19003` (derived: `gateway.port+2`, loopback only)
- `canvasHost.port=19005` (derived: `gateway.port+4`)
- `agents.defaults.workspace` default becomes `~/clawd-dev` when you run `setup`/`onboard` under `--dev`.
- `agents.defaults.workspace` default becomes `~/.openclaw/workspace-dev` when you run `setup`/`onboard` under `--dev`.
Derived ports (rules of thumb):
- Base port = `gateway.port` (or `CLAWDBOT_GATEWAY_PORT` / `--port`)
- Base port = `gateway.port` (or `OPENCLAW_GATEWAY_PORT` / `--port`)
- browser control service port = base + 2 (loopback only)
- `canvasHost.port = base + 4` (or `CLAWDBOT_CANVAS_HOST_PORT` / config override)
- `canvasHost.port = base + 4` (or `OPENCLAW_CANVAS_HOST_PORT` / config override)
- Browser profile CDP ports auto-allocate from `browser.controlPort + 9 .. + 108` (persisted per profile).
Checklist per instance:
- unique `gateway.port`
- unique `CLAWDBOT_CONFIG_PATH`
- unique `CLAWDBOT_STATE_DIR`
- unique `OPENCLAW_CONFIG_PATH`
- unique `OPENCLAW_STATE_DIR`
- unique `agents.defaults.workspace`
- separate WhatsApp numbers (if using WA)
Service install per profile:
```bash
moltbot --profile main gateway install
moltbot --profile rescue gateway install
openclaw --profile main gateway install
openclaw --profile rescue gateway install
```
Example:
```bash
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
OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a openclaw gateway --port 19001
OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002
```
## Protocol (operator view)
@@ -123,7 +123,7 @@ CLAWDBOT_CONFIG_PATH=~/.clawdbot/b.json CLAWDBOT_STATE_DIR=~/.clawdbot-b moltbot
- `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 `moltbot health --json`).
- `health` — full health snapshot (same shape as `openclaw 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 `moltbot`
- Program: path to `openclaw`
- 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).
- `moltbot gateway install` writes `~/Library/LaunchAgents/bot.molt.gateway.plist`
(or `bot.molt.<profile>.plist`; legacy `com.clawdbot.*` is cleaned up).
- `moltbot doctor` audits the LaunchAgent config and can update it to current defaults.
- `openclaw gateway install` writes `~/Library/LaunchAgents/bot.molt.gateway.plist`
(or `bot.molt.<profile>.plist`; legacy `com.openclaw.*` is cleaned up).
- `openclaw 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
moltbot gateway status
moltbot gateway install
moltbot gateway stop
moltbot gateway restart
moltbot logs --follow
openclaw gateway status
openclaw gateway install
openclaw gateway stop
openclaw gateway restart
openclaw logs --follow
```
Notes:
@@ -206,40 +206,40 @@ 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 Moltbot profile services.
- If other gateway-like services are detected, the CLI warns unless they are OpenClaw 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: `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).
- Cleanup: `openclaw gateway uninstall` (current service) and `openclaw doctor` (legacy migrations).
- `gateway install` is a no-op when already installed; use `openclaw gateway install --force` to reinstall (profile/env/path changes).
Bundled mac app:
- Moltbot.app can bundle a Node-based gateway relay and install a per-user LaunchAgent labeled
`bot.molt.gateway` (or `bot.molt.<profile>`; legacy `com.clawdbot.*` labels still unload cleanly).
- To stop it cleanly, use `moltbot gateway stop` (or `launchctl bootout gui/$UID/bot.molt.gateway`).
- To restart, use `moltbot gateway restart` (or `launchctl kickstart -k gui/$UID/bot.molt.gateway`).
- `launchctl` only works if the LaunchAgent is installed; otherwise use `moltbot gateway install` first.
- OpenClaw.app can bundle a Node-based gateway relay and install a per-user LaunchAgent labeled
`bot.molt.gateway` (or `bot.molt.<profile>`; legacy `com.openclaw.*` labels still unload cleanly).
- To stop it cleanly, use `openclaw gateway stop` (or `launchctl bootout gui/$UID/bot.molt.gateway`).
- To restart, use `openclaw gateway restart` (or `launchctl kickstart -k gui/$UID/bot.molt.gateway`).
- `launchctl` only works if the LaunchAgent is installed; otherwise use `openclaw gateway install` first.
- Replace the label with `bot.molt.<profile>` when running a named profile.
## Supervision (systemd user unit)
Moltbot installs a **systemd user service** by default on Linux/WSL2. We
OpenClaw 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).
`moltbot gateway install` writes the user unit. `moltbot doctor` audits the
`openclaw gateway install` writes the user unit. `openclaw doctor` audits the
unit and can update it to match the current recommended defaults.
Create `~/.config/systemd/user/moltbot-gateway[-<profile>].service`:
Create `~/.config/systemd/user/openclaw-gateway[-<profile>].service`:
```
[Unit]
Description=Moltbot Gateway (profile: <profile>, v<version>)
Description=OpenClaw Gateway (profile: <profile>, v<version>)
After=network-online.target
Wants=network-online.target
[Service]
ExecStart=/usr/local/bin/moltbot gateway --port 18789
ExecStart=/usr/local/bin/openclaw gateway --port 18789
Restart=always
RestartSec=5
Environment=CLAWDBOT_GATEWAY_TOKEN=
Environment=OPENCLAW_GATEWAY_TOKEN=
WorkingDirectory=/home/youruser
[Install]
@@ -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 moltbot-gateway[-<profile>].service
systemctl --user enable --now openclaw-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/moltbot-gateway[-<profile>].service` (copy the unit above,
Create `/etc/systemd/system/openclaw-gateway[-<profile>].service` (copy the unit above,
switch `WantedBy=multi-user.target`, set `User=` + `WorkingDirectory=`), then:
```
sudo systemctl daemon-reload
sudo systemctl enable --now moltbot-gateway[-<profile>].service
sudo systemctl enable --now openclaw-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
- `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).
- `openclaw gateway health|status` — request health/status over the Gateway WS.
- `openclaw message send --target <num> --message "hi" [--media ...]` — send via Gateway (idempotent for WhatsApp).
- `openclaw agent --message "hi" --to <num>` — run an agent turn (waits for final by default).
- `openclaw gateway call <method> --params '{"k":"v"}'` — raw method invoker for debugging.
- `openclaw 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 `moltbot gateway` and the legacy TCP control port.
- Retire uses of `openclaw gateway` and the legacy TCP control port.
- Update clients to speak the WS protocol with mandatory connect and structured presence.

4
docs/gateway/local-models.md
View File

@@ -1,5 +1,5 @@
---
summary: "Run Moltbot on local LLMs (LM Studio, vLLM, LiteLLM, custom OpenAI endpoints)"
summary: "Run OpenClaw 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 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)).
Local is doable, but OpenClaw 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)

16
docs/gateway/logging.md
View File

@@ -9,16 +9,16 @@ read_when:
For a user-facing overview (CLI + Control UI + config), see [/logging](/logging).
Moltbot has two log “surfaces”:
OpenClaw 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/moltbot/` (one file per day): `moltbot-YYYY-MM-DD.log`
- Default rolling log file is under `/tmp/openclaw/` (one file per day): `openclaw-YYYY-MM-DD.log`
- Date uses the gateway host's local timezone.
- The log file path and level can be configured via `~/.clawdbot/moltbot.json`:
- The log file path and level can be configured via `~/.openclaw/openclaw.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
moltbot logs --follow
openclaw logs --follow
```
**Verbose vs. log levels**
@@ -72,7 +72,7 @@ The gateway prints WebSocket protocol logs in two modes:
### WS log style
`moltbot gateway` supports a per-gateway style switch:
`openclaw 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)
moltbot gateway
openclaw gateway
# show all WS traffic (paired)
moltbot gateway --verbose --ws-log compact
openclaw gateway --verbose --ws-log compact
# show all WS traffic (full meta)
moltbot gateway --verbose --ws-log full
openclaw gateway --verbose --ws-log full
```
## Console formatting (subsystem logging)

48
docs/gateway/multiple-gateways.md
View File

@@ -1,5 +1,5 @@
---
summary: "Run multiple Moltbot Gateways on one host (isolation, ports, and profiles)"
summary: "Run multiple OpenClaw 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
@@ -9,8 +9,8 @@ read_when:
Most setups should use one Gateway because a single Gateway can handle multiple messaging connections and agents. If you need stronger isolation or redundancy (e.g., a rescue bot), run separate Gateways with isolated profiles/ports.
## Isolation checklist (required)
- `CLAWDBOT_CONFIG_PATH` — per-instance config file
- `CLAWDBOT_STATE_DIR` — per-instance sessions, creds, caches
- `OPENCLAW_CONFIG_PATH` — per-instance config file
- `OPENCLAW_STATE_DIR` — per-instance sessions, creds, caches
- `agents.defaults.workspace` — per-instance workspace root
- `gateway.port` (or `--port`) — unique per instance
- Derived ports (browser/canvas) must not overlap
@@ -19,22 +19,22 @@ If these are shared, you will hit config races and port conflicts.
## Recommended: profiles (`--profile`)
Profiles auto-scope `CLAWDBOT_STATE_DIR` + `CLAWDBOT_CONFIG_PATH` and suffix service names.
Profiles auto-scope `OPENCLAW_STATE_DIR` + `OPENCLAW_CONFIG_PATH` and suffix service names.
```bash
# main
moltbot --profile main setup
moltbot --profile main gateway --port 18789
openclaw --profile main setup
openclaw --profile main gateway --port 18789
# rescue
moltbot --profile rescue setup
moltbot --profile rescue gateway --port 19001
openclaw --profile rescue setup
openclaw --profile rescue gateway --port 19001
```
Per-profile services:
```bash
moltbot --profile main gateway install
moltbot --profile rescue gateway install
openclaw --profile main gateway install
openclaw --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
moltbot onboard
moltbot gateway install
openclaw onboard
openclaw gateway install
# Rescue bot (isolated profile + ports)
moltbot --profile rescue onboard
openclaw --profile rescue onboard
# Notes:
# - workspace name will be postfixed with -rescue per default
# - Port should be at least 18789 + 20 Ports,
@@ -66,12 +66,12 @@ moltbot --profile rescue onboard
# - rest of the onboarding is the same as normal
# To install the service (if not happened automatically during onboarding)
moltbot --profile rescue gateway install
openclaw --profile rescue gateway install
```
## Port mapping (derived)
Base port = `gateway.port` (or `CLAWDBOT_GATEWAY_PORT` / `--port`).
Base port = `gateway.port` (or `OPENCLAW_GATEWAY_PORT` / `--port`).
- browser control service port = base + 2 (loopback only)
- `canvasHost.port = base + 4`
@@ -89,19 +89,19 @@ If you override any of these in config or env, you must keep them unique per ins
## Manual env example
```bash
CLAWDBOT_CONFIG_PATH=~/.clawdbot/main.json \
CLAWDBOT_STATE_DIR=~/.clawdbot-main \
moltbot gateway --port 18789
OPENCLAW_CONFIG_PATH=~/.openclaw/main.json \
OPENCLAW_STATE_DIR=~/.openclaw-main \
openclaw gateway --port 18789
CLAWDBOT_CONFIG_PATH=~/.clawdbot/rescue.json \
CLAWDBOT_STATE_DIR=~/.clawdbot-rescue \
moltbot gateway --port 19001
OPENCLAW_CONFIG_PATH=~/.openclaw/rescue.json \
OPENCLAW_STATE_DIR=~/.openclaw-rescue \
openclaw gateway --port 19001
```
## Quick checks
```bash
moltbot --profile main status
moltbot --profile rescue status
moltbot --profile rescue browser status
openclaw --profile main status
openclaw --profile rescue status
openclaw --profile rescue browser status
```

24
docs/gateway/openai-http-api.md
View File

@@ -5,14 +5,14 @@ read_when:
---
# OpenAI Chat Completions (HTTP)
Moltbot’s Gateway can serve a small OpenAI-compatible Chat Completions endpoint.
OpenClaw’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 `moltbot agent`), so routing/permissions/config match your Gateway.
Under the hood, requests are executed as a normal Gateway agent run (same codepath as `openclaw agent`), so routing/permissions/config match your Gateway.
## Authentication
@@ -21,22 +21,22 @@ Uses the Gateway auth configuration. Send a bearer token:
- `Authorization: Bearer <token>`
Notes:
- When `gateway.auth.mode="token"`, use `gateway.auth.token` (or `CLAWDBOT_GATEWAY_TOKEN`).
- When `gateway.auth.mode="password"`, use `gateway.auth.password` (or `CLAWDBOT_GATEWAY_PASSWORD`).
- When `gateway.auth.mode="token"`, use `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`).
- When `gateway.auth.mode="password"`, use `gateway.auth.password` (or `OPENCLAW_GATEWAY_PASSWORD`).
## Choosing an agent
No custom headers required: encode the agent id in the OpenAI `model` field:
- `model: "moltbot:<agentId>"` (example: `"moltbot:main"`, `"moltbot:beta"`)
- `model: "openclaw:<agentId>"` (example: `"openclaw:main"`, `"openclaw:beta"`)
- `model: "agent:<agentId>"` (alias)
Or target a specific Moltbot agent by header:
Or target a specific OpenClaw agent by header:
- `x-moltbot-agent-id: <agentId>` (default: `main`)
- `x-openclaw-agent-id: <agentId>` (default: `main`)
Advanced:
- `x-moltbot-session-key: <sessionKey>` to fully control session routing.
- `x-openclaw-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-moltbot-agent-id: main' \
-H 'x-openclaw-agent-id: main' \
-d '{
"model": "moltbot",
"model": "openclaw",
"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-moltbot-agent-id: main' \
-H 'x-openclaw-agent-id: main' \
-d '{
"model": "moltbot",
"model": "openclaw",
"stream": true,
"messages": [{"role":"user","content":"hi"}]
}'

24
docs/gateway/openresponses-http-api.md
View File

@@ -6,7 +6,7 @@ read_when:
---
# OpenResponses API (HTTP)
Moltbot’s Gateway can serve an OpenResponses-compatible `POST /v1/responses` endpoint.
OpenClaw’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
`moltbot agent`), so routing/permissions/config match your Gateway.
`openclaw agent`), so routing/permissions/config match your Gateway.
## Authentication
@@ -23,22 +23,22 @@ Uses the Gateway auth configuration. Send a bearer token:
- `Authorization: Bearer <token>`
Notes:
- When `gateway.auth.mode="token"`, use `gateway.auth.token` (or `CLAWDBOT_GATEWAY_TOKEN`).
- When `gateway.auth.mode="password"`, use `gateway.auth.password` (or `CLAWDBOT_GATEWAY_PASSWORD`).
- When `gateway.auth.mode="token"`, use `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`).
- When `gateway.auth.mode="password"`, use `gateway.auth.password` (or `OPENCLAW_GATEWAY_PASSWORD`).
## Choosing an agent
No custom headers required: encode the agent id in the OpenResponses `model` field:
- `model: "moltbot:<agentId>"` (example: `"moltbot:main"`, `"moltbot:beta"`)
- `model: "openclaw:<agentId>"` (example: `"openclaw:main"`, `"openclaw:beta"`)
- `model: "agent:<agentId>"` (alias)
Or target a specific Moltbot agent by header:
Or target a specific OpenClaw agent by header:
- `x-moltbot-agent-id: <agentId>` (default: `main`)
- `x-openclaw-agent-id: <agentId>` (default: `main`)
Advanced:
- `x-moltbot-session-key: <sessionKey>` to fully control session routing.
- `x-openclaw-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-moltbot-agent-id: main' \
-H 'x-openclaw-agent-id: main' \
-d '{
"model": "moltbot",
"model": "openclaw",
"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-moltbot-agent-id: main' \
-H 'x-openclaw-agent-id: main' \
-d '{
"model": "moltbot",
"model": "openclaw",
"stream": true,
"input": "hi"
}'

18
docs/gateway/pairing.md
View File

@@ -35,11 +35,11 @@ Pending requests expire automatically after **5 minutes**.
## CLI workflow (headless friendly)
```bash
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"
openclaw nodes pending
openclaw nodes approve <requestId>
openclaw nodes reject <requestId>
openclaw nodes status
openclaw nodes rename --node <id|name|ip> --name "Living Room iPad"
```
`nodes status` shows paired/connected nodes and their capabilities.
@@ -74,12 +74,12 @@ If silent approval fails, it falls back to the normal “Approve/Reject” promp
## Storage (local, private)
Pairing state is stored under the Gateway state directory (default `~/.clawdbot`):
Pairing state is stored under the Gateway state directory (default `~/.openclaw`):
- `~/.clawdbot/nodes/paired.json`
- `~/.clawdbot/nodes/pending.json`
- `~/.openclaw/nodes/paired.json`
- `~/.openclaw/nodes/pending.json`
If you override `CLAWDBOT_STATE_DIR`, the `nodes/` folder moves with it.
If you override `OPENCLAW_STATE_DIR`, the `nodes/` folder moves with it.
Security notes:
- Tokens are secrets; treat `paired.json` as sensitive.

8
docs/gateway/protocol.md
View File

@@ -9,7 +9,7 @@ read_when:
# Gateway protocol (WebSocket)
The Gateway WS protocol is the **single control plane + node transport** for
Moltbot. All clients (CLI, web UI, macOS app, iOS/Android nodes, headless
OpenClaw. 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": "moltbot-cli/1.2.3",
"userAgent": "openclaw-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": "moltbot-ios/1.2.3",
"userAgent": "openclaw-ios/1.2.3",
"device": {
"id": "device_fingerprint",
"publicKey": "…",
@@ -180,7 +180,7 @@ The Gateway treats these as **claims** and enforces server-side allowlists.
## Auth
- If `CLAWDBOT_GATEWAY_TOKEN` (or `--token`) is set, `connect.params.auth.token`
- If `OPENCLAW_GATEWAY_TOKEN` (or `--token`) is set, `connect.params.auth.token`
must match or the socket is closed.
- After pairing, the Gateway issues a **device token** scoped to the connection
role + scopes. It is returned in `hello-ok.auth.deviceToken` and should be

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

@@ -1,11 +1,11 @@
---
summary: "SSH tunnel setup for Moltbot.app connecting to a remote gateway"
summary: "SSH tunnel setup for OpenClaw.app connecting to a remote gateway"
read_when: "Connecting the macOS app to a remote gateway over SSH"
---
# Running Moltbot.app with a Remote Gateway
# Running OpenClaw.app with a Remote Gateway
Moltbot.app uses SSH tunneling to connect to a remote gateway. This guide shows you how to set it up.
OpenClaw.app uses SSH tunneling to connect to a remote gateway. This guide shows you how to set it up.
## Overview
@@ -13,7 +13,7 @@ Moltbot.app uses SSH tunneling to connect to a remote gateway. This guide shows
┌─────────────────────────────────────────────────────────────┐
│ Client Machine │
│ │
│ Moltbot.app ──► ws://127.0.0.1:18789 (local port) │
│ OpenClaw.app ──► ws://127.0.0.1:18789 (local port) │
│ │ │
│ ▼ │
│ SSH Tunnel ────────────────────────────────────────────────│
@@ -56,7 +56,7 @@ ssh-copy-id -i ~/.ssh/id_rsa <REMOTE_USER>@<REMOTE_IP>
### Step 3: Set Gateway Token
```bash
launchctl setenv CLAWDBOT_GATEWAY_TOKEN "<your-token>"
launchctl setenv OPENCLAW_GATEWAY_TOKEN "<your-token>"
```
### Step 4: Start SSH Tunnel
@@ -65,11 +65,11 @@ launchctl setenv CLAWDBOT_GATEWAY_TOKEN "<your-token>"
ssh -N remote-gateway &
```
### Step 5: Restart Moltbot.app
### Step 5: Restart OpenClaw.app
```bash
# Quit Moltbot.app (⌘Q), then reopen:
open /path/to/Moltbot.app
# Quit OpenClaw.app (⌘Q), then reopen:
open /path/to/OpenClaw.app
```
The app will now connect to the remote gateway through the SSH tunnel.
@@ -116,7 +116,7 @@ The tunnel will now:
- Restart if it crashes
- Keep running in the background
Legacy note: remove any leftover `com.clawdbot.ssh-tunnel` LaunchAgent if present.
Legacy note: remove any leftover `com.openclaw.ssh-tunnel` LaunchAgent if present.
---
@@ -152,4 +152,4 @@ launchctl bootout gui/$UID/bot.molt.ssh-tunnel
| `KeepAlive` | Automatically restarts tunnel if it crashes |
| `RunAtLoad` | Starts tunnel when the agent loads |
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.
OpenClaw.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.

8
docs/gateway/remote.md
View File

@@ -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 → “Moltbot runs”).
- Use the macOS app’s **Remote over SSH** mode (Settings → General → “OpenClaw runs”).
- The app opens and manages the tunnel, so WebChat + health checks “just work.”
Runbook: [macOS remote access](/platforms/mac/remote).
@@ -71,10 +71,10 @@ ssh -N -L 18789:127.0.0.1:18789 user@host
```
With the tunnel up:
- `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.
- `openclaw health` and `openclaw status --deep` now reach the remote gateway via `ws://127.0.0.1:18789`.
- `openclaw 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`).
Note: replace `18789` with your configured `gateway.port` (or `--port`/`OPENCLAW_GATEWAY_PORT`).
## CLI remote defaults

14
docs/gateway/sandbox-vs-tool-policy-vs-elevated.md
View File

@@ -7,7 +7,7 @@ status: active
# Sandbox vs Tool Policy vs Elevated
Moltbot has three related (but different) controls:
OpenClaw 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 @@ Moltbot has three related (but different) controls:
## Quick debug
Use the inspector to see what Moltbot is *actually* doing:
Use the inspector to see what OpenClaw is *actually* doing:
```bash
moltbot sandbox explain
moltbot sandbox explain --session agent:main:main
moltbot sandbox explain --agent work
moltbot sandbox explain --json
openclaw sandbox explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work
openclaw sandbox explain --json
```
It prints:
@@ -88,7 +88,7 @@ Available groups:
- `group:automation`: `cron`, `gateway`
- `group:messaging`: `message`
- `group:nodes`: `nodes`
- `group:moltbot`: all built-in Moltbot tools (excludes provider plugins)
- `group:openclaw`: all built-in OpenClaw tools (excludes provider plugins)
## Elevated: exec-only “run on host”

12
docs/gateway/sandboxing.md
View File

@@ -1,5 +1,5 @@
---
summary: "How Moltbot sandboxing works: modes, scopes, workspace access, and images"
summary: "How OpenClaw 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
Moltbot can run **tools inside Docker containers** to reduce blast radius.
OpenClaw 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
@@ -46,13 +46,13 @@ Group/channel sessions use their own keys, so they count as non-main and will be
## Workspace access
`agents.defaults.sandbox.workspaceAccess` controls **what the sandbox can see**:
- `"none"` (default): tools see a sandbox workspace under `~/.clawdbot/sandboxes`.
- `"none"` (default): tools see a sandbox workspace under `~/.openclaw/sandboxes`.
- `"ro"`: mounts the agent workspace read-only at `/agent` (disables `write`/`edit`/`apply_patch`).
- `"rw"`: mounts the agent workspace read/write at `/workspace`.
Inbound media is copied into the active sandbox workspace (`media/inbound/*`).
Skills note: the `read` tool is sandbox-rooted. With `workspaceAccess: "none"`,
Moltbot mirrors eligible skills into the sandbox workspace (`.../skills`) so
OpenClaw 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: `moltbot-sandbox:bookworm-slim`
Default image: `openclaw-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 `moltbot sandbox explain` to inspect effective sandbox mode, tool policy, and fix-it config keys.
- Use `openclaw 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.

14
docs/gateway/security/formal-verification.md
View File

@@ -1,16 +1,16 @@
---
title: Formal Verification (Security Models)
summary: Machine-checked security models for Moltbot’s highest-risk paths.
summary: Machine-checked security models for OpenClaw’s highest-risk paths.
permalink: /security/formal-verification/
---
# Formal Verification (Security Models)
This page tracks Moltbot’s **formal security models** (TLA+/TLC today; more as needed).
This page tracks OpenClaw’s **formal security models** (TLA+/TLC today; more as needed).
> Note: some older links may refer to the previous project name.
**Goal (north star):** provide a machine-checked argument that Moltbot enforces its
**Goal (north star):** provide a machine-checked argument that OpenClaw enforces its
intended security policy (authorization, session isolation, tool gating, and
misconfiguration safety), under explicit assumptions.
@@ -18,11 +18,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 “Moltbot is secure in all respects” or that the full TypeScript implementation is correct.
**What this is not (yet):** a proof that “OpenClaw 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/openclaw-formal-models](https://github.com/vignesh07/openclaw-formal-models).
## Important caveats
@@ -39,8 +39,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/openclaw-formal-models
cd openclaw-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.

112
docs/gateway/security/index.md
View File

@@ -5,18 +5,16 @@ read_when:
---
# Security 🔒
## Quick check: `moltbot security audit` (formerly `clawdbot security audit`)
## Quick check: `openclaw security audit`
See also: [Formal Verification (Security Models)](/security/formal-verification/)
Run this regularly (especially after changing config or exposing network surfaces):
```bash
moltbot security audit
moltbot security audit --deep
moltbot security audit --fix
# (On older installs, the command is `clawdbot ...`.)
openclaw security audit
openclaw security audit --deep
openclaw security audit --fix
```
It flags common footguns (Gateway auth exposure, browser control exposure, elevated allowlists, filesystem permissions).
@@ -24,11 +22,11 @@ It flags common footguns (Gateway auth exposure, browser control exposure, eleva
`--fix` applies safe guardrails:
- Tighten `groupPolicy="open"` to `groupPolicy="allowlist"` (and per-account variants) for common channels.
- Turn `logging.redactSensitive="off"` back to `"tools"`.
- Tighten local perms (`~/.moltbot` → `700`, config file → `600`, plus common state files like `credentials/*.json`, `agents/*/agent/auth-profiles.json`, and `agents/*/sessions/sessions.json`).
- Tighten local perms (`~/.openclaw` → `700`, config file → `600`, plus common state files like `credentials/*.json`, `agents/*/agent/auth-profiles.json`, and `agents/*/sessions/sessions.json`).
Running an AI agent with shell access on your machine is... *spicy*. Here’s how to not get pwned.
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:
OpenClaw 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
@@ -45,19 +43,19 @@ 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`, Moltbot also attempts a best-effort live Gateway probe.
If you run `--deep`, OpenClaw also attempts a best-effort live Gateway probe.
## Credential storage map
Use this when auditing access or deciding what to back up:
- **WhatsApp**: `~/.moltbot/credentials/whatsapp/<accountId>/creds.json`
- **WhatsApp**: `~/.openclaw/credentials/whatsapp/<accountId>/creds.json`
- **Telegram bot token**: config/env or `channels.telegram.tokenFile`
- **Discord bot token**: config/env (token file not yet supported)
- **Slack tokens**: config/env (`channels.slack.*`)
- **Pairing allowlists**: `~/.moltbot/credentials/<channel>-allowFrom.json`
- **Model auth profiles**: `~/.moltbot/agents/<agentId>/agent/auth-profiles.json`
- **Legacy OAuth import**: `~/.moltbot/credentials/oauth.json`
- **Pairing allowlists**: `~/.openclaw/credentials/<channel>-allowFrom.json`
- **Model auth profiles**: `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
- **Legacy OAuth import**: `~/.openclaw/credentials/oauth.json`
## Security Audit Checklist
@@ -81,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.
`moltbot security audit` warns when this setting is enabled.
`openclaw security audit` warns when this setting is enabled.
## Reverse Proxy Configuration
@@ -95,17 +93,17 @@ gateway:
- "127.0.0.1" # if your proxy runs on localhost
auth:
mode: password
password: ${CLAWDBOT_GATEWAY_PASSWORD}
password: ${OPENCLAW_GATEWAY_PASSWORD}
```
When `trustedProxies` is configured, the Gateway will use `X-Forwarded-For` headers to determine the real client IP for local client detection. Make sure your proxy overwrites (not appends to) incoming `X-Forwarded-For` headers to prevent spoofing.
## Local session logs live on disk
Moltbot stores session transcripts on disk under `~/.moltbot/agents/<agentId>/sessions/*.jsonl`.
OpenClaw stores session transcripts on disk under `~/.openclaw/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 `~/.moltbot` (see the audit section below). If you need
boundary and lock down permissions on `~/.openclaw` (see the audit section below). If you need
stronger isolation between agents, run them under separate OS users or separate hosts.
## Node execution (system.run)
@@ -118,7 +116,7 @@ If a macOS node is paired, the Gateway can invoke `system.run` on that node. Thi
## Dynamic skills (watcher / remote nodes)
Moltbot can refresh the skills list mid-session:
OpenClaw 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).
@@ -141,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.”
Moltbot’s stance:
OpenClaw’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.
@@ -164,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 (`moltbot plugins install <npm-spec>`), treat it like running untrusted code:
- The install path is `~/.moltbot/extensions/<pluginId>/` (or `$CLAWDBOT_STATE_DIR/extensions/<pluginId>/`).
- Moltbot uses `npm pack` and then runs `npm install --omit=dev` in that directory (npm lifecycle scripts can execute code during install).
- If you install plugins from npm (`openclaw plugins install <npm-spec>`), treat it like running untrusted code:
- The install path is `~/.openclaw/extensions/<pluginId>/` (or `$OPENCLAW_STATE_DIR/extensions/<pluginId>/`).
- OpenClaw 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)
@@ -183,15 +181,15 @@ All current DM-capable channels support a DM policy (`dmPolicy` or `*.dm.policy`
Approve via CLI:
```bash
moltbot pairing list <channel>
moltbot pairing approve <channel> <code>
openclaw pairing list <channel>
openclaw pairing approve <channel> <code>
```
Details + files on disk: [Pairing](/start/pairing)
## DM session isolation (multi-user mode)
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:
By default, OpenClaw 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
{
@@ -203,10 +201,10 @@ This prevents cross-user context leakage while keeping group chats isolated. If
## Allowlists (DM + groups) — terminology
Moltbot has two separate “who can trigger me?” layers:
OpenClaw 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 `~/.moltbot/credentials/<channel>-allowFrom.json` (merged with config allowlists).
- When `dmPolicy="pairing"`, approvals are written to `~/.openclaw/credentials/<channel>-allowFrom.json` (merged with config allowlists).
- **Group allowlist** (channel-specific): which groups/channels/guilds the bot will accept messages from at all.
- Common patterns:
- `channels.whatsapp.groups`, `channels.telegram.groups`, `channels.imessage.groups`: per-group defaults like `requireMention`; when set, it also acts as a group allowlist (include `"*"` to keep allow-all behavior).
@@ -233,7 +231,7 @@ Red flags to treat as untrusted:
- “Read this file/URL and do exactly what it says.”
- “Ignore your system prompt or safety rules.”
- “Reveal your hidden instructions or tool outputs.”
- “Paste the full contents of ~/.moltbot or your logs.”
- “Paste the full contents of ~/.openclaw or your logs.”
### Prompt injection does not require public DMs
@@ -287,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**
- `moltbot security audit --deep` and confirm the report is clean.
- `openclaw security audit --deep` and confirm the report is clean.
## Lessons Learned (The Hard Way)
@@ -310,16 +308,16 @@ This is social engineering 101. Create distrust, encourage snooping.
### 0) File permissions
Keep config + state private on the gateway host:
- `~/.moltbot/moltbot.json`: `600` (user read/write only)
- `~/.moltbot`: `700` (user only)
- `~/.openclaw/openclaw.json`: `600` (user read/write only)
- `~/.openclaw`: `700` (user only)
`moltbot doctor` can warn and offer to tighten these permissions.
`openclaw doctor` can warn and offer to tighten these permissions.
### 0.4) Network exposure (bind + port + firewall)
The Gateway multiplexes **WebSocket + HTTP** on a single port:
- Default: `18789`
- Config/flags/env: `gateway.port`, `--port`, `CLAWDBOT_GATEWAY_PORT`
- Config/flags/env: `gateway.port`, `--port`, `OPENCLAW_GATEWAY_PORT`
Bind mode controls where the Gateway listens:
- `gateway.bind: "loopback"` (default): only local clients can connect.
@@ -332,7 +330,7 @@ Rules of thumb:
### 0.4.1) mDNS/Bonjour discovery (information disclosure)
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:
The Gateway broadcasts its presence via mDNS (`_openclaw-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
@@ -369,7 +367,7 @@ The Gateway broadcasts its presence via mDNS (`_moltbot-gw._tcp` on port 5353) f
}
```
4. **Environment variable** (alternative): set `CLAWDBOT_DISABLE_BONJOUR=1` to disable mDNS without config changes.
4. **Environment variable** (alternative): set `OPENCLAW_DISABLE_BONJOUR=1` to disable mDNS without config changes.
In minimal mode, the Gateway still broadcasts enough for device discovery (`role`, `gatewayPort`, `transport`) but omits `cliPath` and `sshPort`. Apps that need CLI path information can fetch it via the authenticated WebSocket connection instead.
@@ -391,7 +389,7 @@ Set a token so **all** WS clients must authenticate:
}
```
Doctor can generate one for you: `moltbot doctor --generate-gateway-token`.
Doctor can generate one for you: `openclaw doctor --generate-gateway-token`.
Note: `gateway.remote.token` is **only** for remote CLI calls; it does not
protect local WS access.
@@ -405,19 +403,19 @@ Local device pairing:
Auth modes:
- `gateway.auth.mode: "token"`: shared bearer token (recommended for most setups).
- `gateway.auth.mode: "password"`: password auth (prefer setting via env: `CLAWDBOT_GATEWAY_PASSWORD`).
- `gateway.auth.mode: "password"`: password auth (prefer setting via env: `OPENCLAW_GATEWAY_PASSWORD`).
Rotation checklist (token/password):
1. Generate/set a new secret (`gateway.auth.token` or `CLAWDBOT_GATEWAY_PASSWORD`).
1. Generate/set a new secret (`gateway.auth.token` or `OPENCLAW_GATEWAY_PASSWORD`).
2. Restart the Gateway (or restart the macOS app if it supervises the Gateway).
3. Update any remote clients (`gateway.remote.token` / `.password` on machines that call into the Gateway).
4. Verify you can no longer connect with the old credentials.
### 0.6) Tailscale Serve identity headers
When `gateway.auth.allowTailscale` is `true` (default for Serve), Moltbot
When `gateway.auth.allowTailscale` is `true` (default for Serve), OpenClaw
accepts Tailscale Serve identity headers (`tailscale-user-login`) as
authentication. Moltbot verifies the identity by resolving the
authentication. OpenClaw 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
@@ -429,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.
- 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.
- OpenClaw 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,9 +448,9 @@ Avoid:
### 0.7) Secrets on disk (what’s sensitive)
Assume anything under `~/.moltbot/` (or `$CLAWDBOT_STATE_DIR/`) may contain secrets or private data:
Assume anything under `~/.openclaw/` (or `$OPENCLAW_STATE_DIR/`) may contain secrets or private data:
- `moltbot.json`: config may include tokens (gateway, remote gateway), provider settings, and allowlists.
- `openclaw.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.
@@ -473,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 `moltbot status --all` (pasteable, secrets redacted) over raw logs.
- When sharing diagnostics, prefer `openclaw 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)
@@ -501,7 +499,7 @@ Details: [Logging](/gateway/logging)
"list": [
{
"id": "main",
"groupChat": { "mentionPatterns": ["@clawd", "@mybot"] }
"groupChat": { "mentionPatterns": ["@openclaw", "@mybot"] }
}
]
}
@@ -561,7 +559,7 @@ or `"session"` for stricter per-session isolation. `scope: "shared"` uses a
single container/workspace.
Also consider agent workspace access inside the sandbox:
- `agents.defaults.sandbox.workspaceAccess: "none"` (default) keeps the agent workspace off-limits; tools run against a sandbox workspace under `~/.clawdbot/sandboxes`
- `agents.defaults.sandbox.workspaceAccess: "none"` (default) keeps the agent workspace off-limits; tools run against a sandbox workspace under `~/.openclaw/sandboxes`
- `agents.defaults.sandbox.workspaceAccess: "ro"` mounts the agent workspace read-only at `/agent` (disables `write`/`edit`/`apply_patch`)
- `agents.defaults.sandbox.workspaceAccess: "rw"` mounts the agent workspace read/write at `/workspace`
@@ -572,7 +570,7 @@ Important: `tools.elevated` is the global baseline escape hatch that runs exec o
Enabling browser control gives the model the ability to drive a real browser.
If that browser profile already contains logged-in sessions, the model can
access those accounts and data. Treat browser profiles as **sensitive state**:
- Prefer a dedicated profile for the agent (the default `clawd` profile).
- Prefer a dedicated profile for the agent (the default `openclaw` profile).
- Avoid pointing the agent at your personal daily-driver profile.
- Keep host browser control disabled for sandboxed agents unless you trust them.
- Treat browser downloads as untrusted input; prefer an isolated downloads directory.
@@ -602,7 +600,7 @@ Common use cases:
list: [
{
id: "personal",
workspace: "~/clawd-personal",
workspace: "~/.openclaw/workspace-personal",
sandbox: { mode: "off" }
}
]
@@ -618,7 +616,7 @@ Common use cases:
list: [
{
id: "family",
workspace: "~/clawd-family",
workspace: "~/.openclaw/workspace-family",
sandbox: {
mode: "all",
scope: "agent",
@@ -642,7 +640,7 @@ Common use cases:
list: [
{
id: "public",
workspace: "~/clawd-public",
workspace: "~/.openclaw/workspace-public",
sandbox: {
mode: "all",
scope: "agent",
@@ -677,25 +675,25 @@ If your AI does something bad:
### Contain
1. **Stop it:** stop the macOS app (if it supervises the Gateway) or terminate your `moltbot gateway` process.
1. **Stop it:** stop the macOS app (if it supervises the Gateway) or terminate your `openclaw 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.
### Rotate (assume compromise if secrets leaked)
1. Rotate Gateway auth (`gateway.auth.token` / `CLAWDBOT_GATEWAY_PASSWORD`) and restart.
1. Rotate Gateway auth (`gateway.auth.token` / `OPENCLAW_GATEWAY_PASSWORD`) and restart.
2. Rotate remote client secrets (`gateway.remote.token` / `.password`) on any machine that can call the Gateway.
3. Rotate provider/API credentials (WhatsApp creds, Slack/Discord tokens, model/API keys in `auth-profiles.json`).
### Audit
1. Check Gateway logs: `/tmp/moltbot/moltbot-YYYY-MM-DD.log` (or `logging.file`).
2. Review the relevant transcript(s): `~/.moltbot/agents/<agentId>/sessions/*.jsonl`.
1. Check Gateway logs: `/tmp/openclaw/openclaw-YYYY-MM-DD.log` (or `logging.file`).
2. Review the relevant transcript(s): `~/.openclaw/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 + Moltbot version
- Timestamp, gateway host OS + OpenClaw 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)
@@ -747,9 +745,9 @@ Mario asking for find ~
## Reporting Security Issues
Found a vulnerability in Moltbot? Please report responsibly:
Found a vulnerability in OpenClaw? Please report responsibly:
1. Email: security@clawd.bot
1. Email: security@openclaw.ai
2. Don't post publicly until fixed
3. We'll credit you (unless you prefer anonymity)

20
docs/gateway/tailscale.md
View File

@@ -6,29 +6,29 @@ read_when:
---
# Tailscale (Gateway dashboard)
Moltbot can auto-configure Tailscale **Serve** (tailnet) or **Funnel** (public) for the
OpenClaw 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`. Moltbot requires a shared password.
- `funnel`: Public HTTPS via `tailscale funnel`. OpenClaw requires a shared password.
- `off`: Default (no Tailscale automation).
## Auth
Set `gateway.auth.mode` to control the handshake:
- `token` (default when `CLAWDBOT_GATEWAY_TOKEN` is set)
- `password` (shared secret via `CLAWDBOT_GATEWAY_PASSWORD` or config)
- `token` (default when `OPENCLAW_GATEWAY_TOKEN` is set)
- `password` (shared secret via `OPENCLAW_GATEWAY_PASSWORD` or config)
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. Moltbot verifies
(`tailscale-user-login`) without supplying a token/password. OpenClaw 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.
Moltbot only treats a request as Serve when it arrives from loopback with
OpenClaw 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
@@ -80,20 +80,20 @@ Note: loopback (`http://127.0.0.1:18789`) will **not** work in this mode.
}
```
Prefer `CLAWDBOT_GATEWAY_PASSWORD` over committing a password to disk.
Prefer `OPENCLAW_GATEWAY_PASSWORD` over committing a password to disk.
## CLI examples
```bash
moltbot gateway --tailscale serve
moltbot gateway --tailscale funnel --auth password
openclaw gateway --tailscale serve
openclaw 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 Moltbot to undo `tailscale serve`
- Set `gateway.tailscale.resetOnExit` if you want OpenClaw 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.

10
docs/gateway/tools-invoke-http-api.md
View File

@@ -6,7 +6,7 @@ read_when:
---
# Tools Invoke (HTTP)
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.
OpenClaw’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`
@@ -20,8 +20,8 @@ Uses the Gateway auth configuration. Send a bearer token:
- `Authorization: Bearer <token>`
Notes:
- When `gateway.auth.mode="token"`, use `gateway.auth.token` (or `CLAWDBOT_GATEWAY_TOKEN`).
- When `gateway.auth.mode="password"`, use `gateway.auth.password` (or `CLAWDBOT_GATEWAY_PASSWORD`).
- When `gateway.auth.mode="token"`, use `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`).
- When `gateway.auth.mode="password"`, use `gateway.auth.password` (or `OPENCLAW_GATEWAY_PASSWORD`).
## Request body
@@ -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-moltbot-message-channel: <channel>` (example: `slack`, `telegram`)
- `x-moltbot-account-id: <accountId>` (when multiple accounts exist)
- `x-openclaw-message-channel: <channel>` (example: `slack`, `telegram`)
- `x-openclaw-account-id: <accountId>` (when multiple accounts exist)
## Responses

224
docs/gateway/troubleshooting.md
View File

@@ -1,11 +1,11 @@
---
summary: "Quick troubleshooting guide for common Moltbot failures"
summary: "Quick troubleshooting guide for common OpenClaw failures"
read_when:
- Investigating runtime issues or failures
---
# Troubleshooting 🔧
When Moltbot misbehaves, here's how to fix it.
When OpenClaw 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 |
|---|---|---|
| `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 |
| `openclaw status` | Local summary: OS + update, gateway reachability/mode, service, agents/sessions, provider config state | First check, quick overview |
| `openclaw status --all` | Full local diagnosis (read-only, pasteable, safe-ish) incl. log tail | When you need to share a debug report |
| `openclaw status --deep` | Runs gateway health checks (incl. provider probes; requires reachable gateway) | When “configured” doesn’t mean “working” |
| `openclaw gateway probe` | Gateway discovery + reachability (local + remote targets) | When you suspect you’re probing the wrong gateway |
| `openclaw channels status --probe` | Asks the running gateway for channel status (and optionally probes) | When gateway is reachable but channels misbehave |
| `openclaw gateway status` | Supervisor state (launchd/systemd/schtasks), runtime PID/exit, last gateway error | When the service “looks loaded” but nothing runs |
| `openclaw logs --follow` | Live logs (best signal for runtime issues) | When you need the actual failure reason |
**Sharing output:** prefer `moltbot status --all` (it redacts tokens). If you paste `moltbot status`, consider setting `CLAWDBOT_SHOW_SECRETS=0` first (token previews).
**Sharing output:** prefer `openclaw status --all` (it redacts tokens). If you paste `openclaw status`, consider setting `OPENCLAW_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
moltbot models auth setup-token --provider anthropic
openclaw models auth setup-token --provider anthropic
```
- Or copy `auth-profiles.json` from the main agent dir to the new agent dir.
Verify:
```bash
moltbot models status
openclaw 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)
moltbot models auth setup-token --provider anthropic
moltbot models status
openclaw models auth setup-token --provider anthropic
openclaw models status
```
If you generated the token elsewhere:
```bash
moltbot models auth paste-token --provider anthropic
moltbot models status
openclaw models auth paste-token --provider anthropic
openclaw models status
```
More detail: [Anthropic](/providers/anthropic) and [OAuth](/concepts/oauth).
@@ -97,18 +97,18 @@ can appear “loaded” while nothing is running.
**Check:**
```bash
moltbot gateway status
moltbot doctor
openclaw gateway status
openclaw doctor
```
Doctor/service will show runtime state (PID/last exit) and log hints.
**Logs:**
- 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 moltbot-gateway[-<profile>].service -n 200 --no-pager`
- Windows: `schtasks /Query /TN "Moltbot Gateway (<profile>)" /V /FO LIST`
- Preferred: `openclaw logs --follow`
- File logs (always): `/tmp/openclaw/openclaw-YYYY-MM-DD.log` (or your configured `logging.file`)
- macOS LaunchAgent (if installed): `$OPENCLAW_STATE_DIR/logs/gateway.log` and `gateway.err.log`
- Linux systemd (if installed): `journalctl --user -u openclaw-gateway[-<profile>].service -n 200 --no-pager`
- Windows: `schtasks /Query /TN "OpenClaw 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
moltbot configure
openclaw configure
```
- Or set it directly:
```bash
moltbot config set gateway.mode local
openclaw config set gateway.mode local
```
**If you meant to run a remote Gateway instead:**
- Set a remote URL and keep `gateway.mode=remote`:
```bash
moltbot config set gateway.mode remote
moltbot config set gateway.remote.url "wss://gateway.example.com"
openclaw config set gateway.mode remote
openclaw 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 `moltbot setup` to create a starter config, then rerun
**No config file yet?** Run `openclaw setup` to create a starter config, then rerun
the gateway.
### Service Environment (PATH + runtime)
@@ -159,14 +159,14 @@ The gateway service runs with a **minimal PATH** to avoid shell/manager cruft:
This intentionally excludes version managers (nvm/fnm/volta/asdf) and package
managers (pnpm/npm) because the service does not load your shell init. Runtime
variables like `DISPLAY` should live in `~/.clawdbot/.env` (loaded early by the
variables like `DISPLAY` should live in `~/.openclaw/.env` (loaded early by the
gateway).
Exec runs on `host=gateway` merge your login-shell `PATH` into the exec environment,
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 `moltbot doctor`
service was installed with Bun or a version-managed Node path, run `openclaw 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 `moltbot sandbox recreate --agent <id>` (or `--all`)
- then run `openclaw 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 `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.
- `gateway.mode` must be `local` for `openclaw 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 `openclaw gateway status` to see the service’s resolved port + probe target (or pass `--url`).
- `openclaw gateway status` and `openclaw 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.auth.token` (or `OPENCLAW_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 `moltbot gateway status` shows a config mismatch**
**If `openclaw 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 `moltbot gateway install --force` from the same `--profile` / `CLAWDBOT_STATE_DIR` you want the service to use.
- Fix: rerun `openclaw gateway install --force` from the same `--profile` / `OPENCLAW_STATE_DIR` you want the service to use.
**If `moltbot gateway status` reports service config issues**
**If `openclaw gateway status` reports service config issues**
- The supervisor config (launchd/systemd/schtasks) is missing current defaults.
- Fix: run `moltbot doctor` to update it (or `moltbot gateway install --force` for a full rewrite).
- Fix: run `openclaw doctor` to update it (or `openclaw 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.
- Fix: set `gateway.auth.mode` + `gateway.auth.token` (or export `OPENCLAW_GATEWAY_TOKEN`) and restart the service.
**If `moltbot gateway status` says `bind=tailnet` but no tailnet interface was found**
**If `openclaw 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
moltbot gateway status
openclaw 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 `~/moltbot` on disk.
If you upgraded from older installs, you might still have `~/openclaw` on disk.
Multiple workspace directories can cause confusing auth or state drift because
only one workspace is active.
@@ -243,7 +243,7 @@ only one workspace is active.
### Main chat running in a sandbox workspace
Symptoms: `pwd` or file tools show `~/.clawdbot/sandboxes/...` even though you
Symptoms: `pwd` or file tools show `~/.openclaw/sandboxes/...` even though you
expected the host workspace.
**Why:** `agents.defaults.sandbox.mode: "non-main"` keys off `session.mainKey` (default `"main"`).
@@ -267,14 +267,14 @@ The agent was interrupted mid-response.
### "Agent failed before reply: Unknown model: anthropic/claude-haiku-3-5"
Moltbot intentionally rejects **older/insecure models** (especially those more
OpenClaw 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 `moltbot models list` or
`moltbot models scan` and choose a supported one.
- If you’re unsure which models are available, run `openclaw models list` or
`openclaw 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
moltbot status
openclaw 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/moltbot.json}"
"${OPENCLAW_CONFIG_PATH:-$HOME/.openclaw/openclaw.json}"
```
**Check 3:** Check the logs
```bash
moltbot logs --follow
openclaw logs --follow
# or if you want quick filters:
tail -f "$(ls -t /tmp/moltbot/moltbot-*.log | head -1)" | grep "blocked\\|skip\\|unauthorized"
tail -f "$(ls -t /tmp/openclaw/openclaw-*.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
moltbot pairing list <channel>
openclaw 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
moltbot logs --follow | grep "pairing request"
openclaw logs --follow | grep "pairing request"
```
**Check 3:** Confirm `dmPolicy` isn’t `open`/`allowlist` for that channel.
@@ -325,14 +325,14 @@ moltbot logs --follow | grep "pairing request"
Known issue: When you send an image with ONLY a mention (no other text), WhatsApp sometimes doesn't include the mention metadata.
**Workaround:** Add some text with the mention:
- ❌ `@clawd` + image
- ✅ `@clawd check this` + image
- ❌ `@openclaw` + image
- ✅ `@openclaw check this` + image
### Session Not Resuming
**Check 1:** Is the session file there?
```bash
ls -la ~/.clawdbot/agents/<agentId>/sessions/
ls -la ~/.openclaw/agents/<agentId>/sessions/
```
**Check 2:** Is the reset window too short?
@@ -368,26 +368,26 @@ Or use the `process` tool to background long commands.
```bash
# Check local status (creds, sessions, queued events)
moltbot status
openclaw status
# Probe the running gateway + channels (WA connect + Telegram + Discord APIs)
moltbot status --deep
openclaw status --deep
# View recent connection events
moltbot logs --limit 200 | grep "connection\\|disconnect\\|logout"
openclaw 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
moltbot gateway --verbose
openclaw gateway --verbose
```
If you’re logged out / unlinked:
```bash
moltbot channels logout
trash "${CLAWDBOT_STATE_DIR:-$HOME/.clawdbot}/credentials" # if logout can't cleanly remove everything
moltbot channels login --verbose # re-scan QR
openclaw channels logout
trash "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/credentials" # if logout can't cleanly remove everything
openclaw 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/moltbot/moltbot-*.log | head -1)" | tail -20
grep "media\\|fetch\\|download" "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" | tail -20
```
### High Memory Usage
Moltbot keeps conversation history in memory.
OpenClaw keeps conversation history in memory.
**Fix:** Restart periodically or set session limits:
```json
@@ -424,26 +424,26 @@ Moltbot keeps conversation history in memory.
### “Gateway won’t start — configuration invalid”
Moltbot now refuses to start when the config contains unknown keys, malformed values, or invalid types.
OpenClaw 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
moltbot doctor
moltbot doctor --fix
openclaw doctor
openclaw doctor --fix
```
Notes:
- `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.
- `openclaw doctor` reports every invalid entry.
- `openclaw doctor --fix` applies migrations/repairs and rewrites the config.
- Diagnostic commands like `openclaw logs`, `openclaw health`, `openclaw status`, `openclaw gateway status`, and `openclaw 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/moltbot/…` for the exact provider error.
- **Model status**: use `/model status` (chat) or `moltbot models status` (CLI).
- **Gateway logs** in `/tmp/openclaw/…` for the exact provider error.
- **Model status**: use `/model status` (chat) or `openclaw 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
moltbot channels login
openclaw channels login
```
### Build errors on `main` — what’s the standard fix path?
1) `git pull origin main && pnpm install`
2) `moltbot doctor`
2) `openclaw 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
moltbot doctor
moltbot gateway restart
openclaw doctor
openclaw gateway restart
```
Why: pnpm is the configured package manager for this repo.
@@ -501,20 +501,20 @@ upgrades in place and rewrites the gateway service to point at the new install.
Switch **to git install**:
```bash
curl -fsSL https://molt.bot/install.sh | bash -s -- --install-method git --no-onboard
curl -fsSL https://openclaw.bot/install.sh | bash -s -- --install-method git --no-onboard
```
Switch **to npm global**:
```bash
curl -fsSL https://molt.bot/install.sh | bash
curl -fsSL https://openclaw.bot/install.sh | bash
```
Notes:
- The git flow only rebases if the repo is clean. Commit or stash changes first.
- After switching, run:
```bash
moltbot doctor
moltbot gateway restart
openclaw doctor
openclaw 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 `moltbot channels status --probe` for audit hints.
5) Run `openclaw 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. Moltbot scrubs/normalizes tool
endpoint accepts a strict subset of JSON Schema. OpenClaw 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 Moltbot**:
1) **Update OpenClaw**:
- 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 bot.molt.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/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.
If resetting doesn't work, change the `BUNDLE_ID` in [`scripts/package-mac-app.sh`](https://github.com/openclaw/openclaw/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,9 +589,9 @@ 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
moltbot gateway status
moltbot gateway stop
# Or: launchctl bootout gui/$UID/bot.molt.gateway (replace with bot.molt.<profile>; legacy com.clawdbot.* still works)
openclaw gateway status
openclaw gateway stop
# Or: launchctl bootout gui/$UID/bot.molt.gateway (replace with bot.molt.<profile>; legacy com.openclaw.* still works)
```
**Fix 2: Port is busy (find the listener)**
@@ -607,10 +607,10 @@ kill -9 <PID> # last resort
```
**Fix 3: Check the CLI install**
Ensure the global `moltbot` CLI is installed and matches the app version:
Ensure the global `openclaw` CLI is installed and matches the app version:
```bash
moltbot --version
npm install -g moltbot@<version>
openclaw --version
npm install -g openclaw@<version>
```
## Debug Mode
@@ -619,43 +619,43 @@ Get verbose logging:
```bash
# Turn on trace logging in config:
# ${CLAWDBOT_CONFIG_PATH:-$HOME/.clawdbot/moltbot.json} -> { logging: { level: "trace" } }
# ${OPENCLAW_CONFIG_PATH:-$HOME/.openclaw/openclaw.json} -> { logging: { level: "trace" } }
#
# Then run verbose commands to mirror debug output to stdout:
moltbot gateway --verbose
moltbot channels login --verbose
openclaw gateway --verbose
openclaw channels login --verbose
```
## Log Locations
| Log | Location |
|-----|----------|
| 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/` |
| Gateway file logs (structured) | `/tmp/openclaw/openclaw-YYYY-MM-DD.log` (or `logging.file`) |
| Gateway service logs (supervisor) | macOS: `$OPENCLAW_STATE_DIR/logs/gateway.log` + `gateway.err.log` (default: `~/.openclaw/logs/...`; profiles use `~/.openclaw-<profile>/logs/...`)<br />Linux: `journalctl --user -u openclaw-gateway[-<profile>].service -n 200 --no-pager`<br />Windows: `schtasks /Query /TN "OpenClaw Gateway (<profile>)" /V /FO LIST` |
| Session files | `$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/` |
| Media cache | `$OPENCLAW_STATE_DIR/media/` |
| Credentials | `$OPENCLAW_STATE_DIR/credentials/` |
## Health Check
```bash
# Supervisor + probe target + config paths
moltbot gateway status
openclaw gateway status
# Include system-level scans (legacy/extra services, port listeners)
moltbot gateway status --deep
openclaw gateway status --deep
# Is the gateway reachable?
moltbot health --json
openclaw health --json
# If it fails, rerun with connection details:
moltbot health --verbose
openclaw health --verbose
# Is something listening on the default port?
lsof -nP -iTCP:18789 -sTCP:LISTEN
# Recent activity (RPC log tail)
moltbot logs --follow
openclaw logs --follow
# Fallback if RPC is down
tail -20 /tmp/moltbot/moltbot-*.log
tail -20 /tmp/openclaw/openclaw-*.log
```
## Reset Everything
@@ -663,23 +663,23 @@ tail -20 /tmp/moltbot/moltbot-*.log
Nuclear option:
```bash
moltbot gateway stop
openclaw gateway stop
# If you installed a service and want a clean install:
# moltbot gateway uninstall
# openclaw gateway uninstall
trash "${CLAWDBOT_STATE_DIR:-$HOME/.clawdbot}"
moltbot channels login # re-pair WhatsApp
moltbot gateway restart # or: moltbot gateway
trash "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
openclaw channels login # re-pair WhatsApp
openclaw gateway restart # or: openclaw gateway
```
⚠️ This loses all sessions and requires re-pairing WhatsApp.
## Getting Help
1. Check logs first: `/tmp/moltbot/` (default: `moltbot-YYYY-MM-DD.log`, or your configured `logging.file`)
1. Check logs first: `/tmp/openclaw/` (default: `openclaw-YYYY-MM-DD.log`, or your configured `logging.file`)
2. Search existing issues on GitHub
3. Open a new issue with:
- Moltbot version
- OpenClaw version
- Relevant log snippets
- Steps to reproduce
- Your config (redact secrets!)