Include full contents of all nested repositories
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
168
openclaw/docs/gateway/authentication.md
Normal file
168
openclaw/docs/gateway/authentication.md
Normal file
@@ -0,0 +1,168 @@
|
||||
---
|
||||
summary: "Model authentication: OAuth, API keys, and setup-token"
|
||||
read_when:
|
||||
- Debugging model auth or OAuth expiry
|
||||
- Documenting authentication or credential storage
|
||||
title: "Authentication"
|
||||
---
|
||||
|
||||
# Authentication
|
||||
|
||||
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`.
|
||||
|
||||
See [/concepts/oauth](/concepts/oauth) for the full OAuth flow and storage
|
||||
layout.
|
||||
For SecretRef-based auth (`env`/`file`/`exec` providers), see [Secrets Management](/gateway/secrets).
|
||||
|
||||
## Recommended Anthropic setup (API key)
|
||||
|
||||
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 `openclaw gateway`).
|
||||
|
||||
```bash
|
||||
export ANTHROPIC_API_KEY="..."
|
||||
openclaw models status
|
||||
```
|
||||
|
||||
3. If the Gateway runs under systemd/launchd, prefer putting the key in
|
||||
`~/.openclaw/.env` so the daemon can read it:
|
||||
|
||||
```bash
|
||||
cat >> ~/.openclaw/.env <<'EOF'
|
||||
ANTHROPIC_API_KEY=...
|
||||
EOF
|
||||
```
|
||||
|
||||
Then restart the daemon (or restart your Gateway process) and re-check:
|
||||
|
||||
```bash
|
||||
openclaw models status
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
If you’d rather not manage env vars yourself, the onboarding wizard can store
|
||||
API keys for daemon use: `openclaw onboard`.
|
||||
|
||||
See [Help](/help) for details on env inheritance (`env.shellEnv`,
|
||||
`~/.openclaw/.env`, systemd/launchd).
|
||||
|
||||
## Anthropic: setup-token (subscription auth)
|
||||
|
||||
For Anthropic, the recommended path is an **API key**. If you’re using a Claude
|
||||
subscription, the setup-token flow is also supported. Run it on the **gateway host**:
|
||||
|
||||
```bash
|
||||
claude setup-token
|
||||
```
|
||||
|
||||
Then paste it into OpenClaw:
|
||||
|
||||
```bash
|
||||
openclaw models auth setup-token --provider anthropic
|
||||
```
|
||||
|
||||
If the token was created on another machine, paste it manually:
|
||||
|
||||
```bash
|
||||
openclaw models auth paste-token --provider anthropic
|
||||
```
|
||||
|
||||
If you see an Anthropic error like:
|
||||
|
||||
```
|
||||
This credential is only authorized for use with Claude Code and cannot be used for other API requests.
|
||||
```
|
||||
|
||||
…use an Anthropic API key instead.
|
||||
|
||||
Manual token entry (any provider; writes `auth-profiles.json` + updates config):
|
||||
|
||||
```bash
|
||||
openclaw models auth paste-token --provider anthropic
|
||||
openclaw models auth paste-token --provider openrouter
|
||||
```
|
||||
|
||||
Auth profile refs are also supported for static credentials:
|
||||
|
||||
- `api_key` credentials can use `keyRef: { source, provider, id }`
|
||||
- `token` credentials can use `tokenRef: { source, provider, id }`
|
||||
|
||||
Automation-friendly check (exit `1` when expired/missing, `2` when expiring):
|
||||
|
||||
```bash
|
||||
openclaw models status --check
|
||||
```
|
||||
|
||||
Optional ops scripts (systemd/Termux) are documented here:
|
||||
[/automation/auth-monitoring](/automation/auth-monitoring)
|
||||
|
||||
> `claude setup-token` requires an interactive TTY.
|
||||
|
||||
## Checking model auth status
|
||||
|
||||
```bash
|
||||
openclaw models status
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
## API key rotation behavior (gateway)
|
||||
|
||||
Some providers support retrying a request with alternative keys when an API call
|
||||
hits a provider rate limit.
|
||||
|
||||
- Priority order:
|
||||
- `OPENCLAW_LIVE_<PROVIDER>_KEY` (single override)
|
||||
- `<PROVIDER>_API_KEYS`
|
||||
- `<PROVIDER>_API_KEY`
|
||||
- `<PROVIDER>_API_KEY_*`
|
||||
- Google providers also include `GOOGLE_API_KEY` as an additional fallback.
|
||||
- The same key list is deduplicated before use.
|
||||
- OpenClaw retries with the next key only for rate-limit errors (for example
|
||||
`429`, `rate_limit`, `quota`, `resource exhausted`).
|
||||
- Non-rate-limit errors are not retried with alternate keys.
|
||||
- If all keys fail, the final error from the last attempt is returned.
|
||||
|
||||
## Controlling which credential is used
|
||||
|
||||
### Per-session (chat command)
|
||||
|
||||
Use `/model <alias-or-id>@<profileId>` to pin a specific provider credential for the current session (example profile ids: `anthropic:default`, `anthropic:work`).
|
||||
|
||||
Use `/model` (or `/model list`) for a compact picker; use `/model status` for the full view (candidates + next auth profile, plus provider endpoint details when configured).
|
||||
|
||||
### Per-agent (CLI override)
|
||||
|
||||
Set an explicit auth profile order override for an agent (stored in that agent’s `auth-profiles.json`):
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### “No credentials found”
|
||||
|
||||
If the Anthropic token profile is missing, run `claude setup-token` on the
|
||||
**gateway host**, then re-check:
|
||||
|
||||
```bash
|
||||
openclaw models status
|
||||
```
|
||||
|
||||
### Token expiring/expired
|
||||
|
||||
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
|
||||
|
||||
- Claude Max or Pro subscription (for `claude setup-token`)
|
||||
- Claude Code CLI installed (`claude` command available)
|
||||
96
openclaw/docs/gateway/background-process.md
Normal file
96
openclaw/docs/gateway/background-process.md
Normal file
@@ -0,0 +1,96 @@
|
||||
---
|
||||
summary: "Background exec execution and process management"
|
||||
read_when:
|
||||
- Adding or modifying background exec behavior
|
||||
- Debugging long-running exec tasks
|
||||
title: "Background Exec and Process Tool"
|
||||
---
|
||||
|
||||
# Background Exec + Process Tool
|
||||
|
||||
OpenClaw runs shell commands through the `exec` tool and keeps long‑running tasks in memory. The `process` tool manages those background sessions.
|
||||
|
||||
## exec tool
|
||||
|
||||
Key parameters:
|
||||
|
||||
- `command` (required)
|
||||
- `yieldMs` (default 10000): auto‑background after this delay
|
||||
- `background` (bool): background immediately
|
||||
- `timeout` (seconds, default 1800): kill the process after this timeout
|
||||
- `elevated` (bool): run on host if elevated mode is enabled/allowed
|
||||
- Need a real TTY? Set `pty: true`.
|
||||
- `workdir`, `env`
|
||||
|
||||
Behavior:
|
||||
|
||||
- Foreground runs return output directly.
|
||||
- When backgrounded (explicit or timeout), the tool returns `status: "running"` + `sessionId` and a short tail.
|
||||
- Output is kept in memory until the session is polled or cleared.
|
||||
- If the `process` tool is disallowed, `exec` runs synchronously and ignores `yieldMs`/`background`.
|
||||
|
||||
## Child process bridging
|
||||
|
||||
When spawning long-running child processes outside the exec/process tools (for example, CLI respawns or gateway helpers), attach the child-process bridge helper so termination signals are forwarded and listeners are detached on exit/error. This avoids orphaned processes on systemd and keeps shutdown behavior consistent across platforms.
|
||||
|
||||
Environment overrides:
|
||||
|
||||
- `PI_BASH_YIELD_MS`: default yield (ms)
|
||||
- `PI_BASH_MAX_OUTPUT_CHARS`: in‑memory output cap (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):
|
||||
|
||||
- `tools.exec.backgroundMs` (default 10000)
|
||||
- `tools.exec.timeoutSec` (default 1800)
|
||||
- `tools.exec.cleanupMs` (default 1800000)
|
||||
- `tools.exec.notifyOnExit` (default true): enqueue a system event + request heartbeat when a backgrounded exec exits.
|
||||
- `tools.exec.notifyOnExitEmptySuccess` (default false): when true, also enqueue completion events for successful backgrounded runs that produced no output.
|
||||
|
||||
## process tool
|
||||
|
||||
Actions:
|
||||
|
||||
- `list`: running + finished sessions
|
||||
- `poll`: drain new output for a session (also reports exit status)
|
||||
- `log`: read the aggregated output (supports `offset` + `limit`)
|
||||
- `write`: send stdin (`data`, optional `eof`)
|
||||
- `kill`: terminate a background session
|
||||
- `clear`: remove a finished session from memory
|
||||
- `remove`: kill if running, otherwise clear if finished
|
||||
|
||||
Notes:
|
||||
|
||||
- Only backgrounded sessions are listed/persisted in memory.
|
||||
- Sessions are lost on process restart (no disk persistence).
|
||||
- Session logs are only saved to chat history if you run `process poll/log` and the tool result is recorded.
|
||||
- `process` is scoped per agent; it only sees sessions started by that agent.
|
||||
- `process list` includes a derived `name` (command verb + target) for quick scans.
|
||||
- `process log` uses line-based `offset`/`limit`.
|
||||
- When both `offset` and `limit` are omitted, it returns the last 200 lines and includes a paging hint.
|
||||
- When `offset` is provided and `limit` is omitted, it returns from `offset` to the end (not capped to 200).
|
||||
|
||||
## Examples
|
||||
|
||||
Run a long task and poll later:
|
||||
|
||||
```json
|
||||
{ "tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000 }
|
||||
```
|
||||
|
||||
```json
|
||||
{ "tool": "process", "action": "poll", "sessionId": "<id>" }
|
||||
```
|
||||
|
||||
Start immediately in background:
|
||||
|
||||
```json
|
||||
{ "tool": "exec", "command": "npm run build", "background": true }
|
||||
```
|
||||
|
||||
Send stdin:
|
||||
|
||||
```json
|
||||
{ "tool": "process", "action": "write", "sessionId": "<id>", "data": "y\n" }
|
||||
```
|
||||
177
openclaw/docs/gateway/bonjour.md
Normal file
177
openclaw/docs/gateway/bonjour.md
Normal file
@@ -0,0 +1,177 @@
|
||||
---
|
||||
summary: "Bonjour/mDNS discovery + debugging (Gateway beacons, clients, and common failure modes)"
|
||||
read_when:
|
||||
- Debugging Bonjour discovery issues on macOS/iOS
|
||||
- Changing mDNS service types, TXT records, or discovery UX
|
||||
title: "Bonjour Discovery"
|
||||
---
|
||||
|
||||
# Bonjour / mDNS discovery
|
||||
|
||||
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.
|
||||
|
||||
## Wide‑area Bonjour (Unicast DNS‑SD) over Tailscale
|
||||
|
||||
If the node and gateway are on different networks, multicast mDNS won’t cross the
|
||||
boundary. You can keep the same discovery UX by switching to **unicast DNS‑SD**
|
||||
("Wide‑Area Bonjour") over Tailscale.
|
||||
|
||||
High‑level steps:
|
||||
|
||||
1. Run a DNS server on the gateway host (reachable over Tailnet).
|
||||
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).
|
||||
|
||||
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 wide-area DNS-SD publishing
|
||||
}
|
||||
```
|
||||
|
||||
### One‑time DNS server setup (gateway host)
|
||||
|
||||
```bash
|
||||
openclaw dns setup --apply
|
||||
```
|
||||
|
||||
This installs CoreDNS and configures it to:
|
||||
|
||||
- listen on port 53 only on the gateway’s Tailscale interfaces
|
||||
- serve your chosen domain (example: `openclaw.internal.`) from `~/.openclaw/dns/<domain>.db`
|
||||
|
||||
Validate from a tailnet‑connected machine:
|
||||
|
||||
```bash
|
||||
dns-sd -B _openclaw-gw._tcp openclaw.internal.
|
||||
dig @<TAILNET_IPV4> -p 53 _openclaw-gw._tcp.openclaw.internal PTR +short
|
||||
```
|
||||
|
||||
### Tailscale DNS settings
|
||||
|
||||
In the Tailscale admin console:
|
||||
|
||||
- Add a nameserver pointing at the gateway’s tailnet IP (UDP/TCP 53).
|
||||
- Add split DNS so your discovery domain uses that nameserver.
|
||||
|
||||
Once clients accept tailnet DNS, iOS nodes can browse
|
||||
`_openclaw-gw._tcp` in your discovery domain without multicast.
|
||||
|
||||
### Gateway listener security (recommended)
|
||||
|
||||
The Gateway WS port (default `18789`) binds to loopback by default. For LAN/tailnet
|
||||
access, bind explicitly and keep auth enabled.
|
||||
|
||||
For tailnet‑only setups:
|
||||
|
||||
- Set `gateway.bind: "tailnet"` in `~/.openclaw/openclaw.json`.
|
||||
- Restart the Gateway (or restart the macOS menubar app).
|
||||
|
||||
## What advertises
|
||||
|
||||
Only the Gateway advertises `_openclaw-gw._tcp`.
|
||||
|
||||
## Service types
|
||||
|
||||
- `_openclaw-gw._tcp` — gateway transport beacon (used by macOS/iOS/Android nodes).
|
||||
|
||||
## TXT keys (non‑secret hints)
|
||||
|
||||
The Gateway advertises small non‑secret hints to make UI flows convenient:
|
||||
|
||||
- `role=gateway`
|
||||
- `displayName=<friendly name>`
|
||||
- `lanHost=<hostname>.local`
|
||||
- `gatewayPort=<port>` (Gateway WS + HTTP)
|
||||
- `gatewayTls=1` (only when TLS is enabled)
|
||||
- `gatewayTlsSha256=<sha256>` (only when TLS is enabled and fingerprint is available)
|
||||
- `canvasPort=<port>` (only when the canvas host is enabled; currently the same as `gatewayPort`)
|
||||
- `sshPort=<port>` (defaults to 22 when not overridden)
|
||||
- `transport=gateway`
|
||||
- `cliPath=<path>` (optional; absolute path to a runnable `openclaw` entrypoint)
|
||||
- `tailnetDns=<magicdns>` (optional hint when Tailnet is available)
|
||||
|
||||
Security notes:
|
||||
|
||||
- Bonjour/mDNS TXT records are **unauthenticated**. Clients must not treat TXT as authoritative routing.
|
||||
- Clients should route using the resolved service endpoint (SRV + A/AAAA). Treat `lanHost`, `tailnetDns`, `gatewayPort`, and `gatewayTlsSha256` as hints only.
|
||||
- TLS pinning must never allow an advertised `gatewayTlsSha256` to override a previously stored pin.
|
||||
- iOS/Android nodes should treat discovery-based direct connects as **TLS-only** and require explicit user confirmation before trusting a first-time fingerprint.
|
||||
|
||||
## Debugging on macOS
|
||||
|
||||
Useful built‑in tools:
|
||||
|
||||
- Browse instances:
|
||||
|
||||
```bash
|
||||
dns-sd -B _openclaw-gw._tcp local.
|
||||
```
|
||||
|
||||
- Resolve one instance (replace `<instance>`):
|
||||
|
||||
```bash
|
||||
dns-sd -L "<instance>" _openclaw-gw._tcp local.
|
||||
```
|
||||
|
||||
If browsing works but resolving fails, you’re usually hitting a LAN policy or
|
||||
mDNS resolver issue.
|
||||
|
||||
## Debugging in Gateway logs
|
||||
|
||||
The Gateway writes a rolling log file (printed on startup as
|
||||
`gateway log file: ...`). Look for `bonjour:` lines, especially:
|
||||
|
||||
- `bonjour: advertise failed ...`
|
||||
- `bonjour: ... name conflict resolved` / `hostname conflict resolved`
|
||||
- `bonjour: watchdog detected non-announced service ...`
|
||||
|
||||
## Debugging on iOS node
|
||||
|
||||
The iOS node uses `NWBrowser` to discover `_openclaw-gw._tcp`.
|
||||
|
||||
To capture logs:
|
||||
|
||||
- Settings → Gateway → Advanced → **Discovery Debug Logs**
|
||||
- Settings → Gateway → Advanced → **Discovery Logs** → reproduce → **Copy**
|
||||
|
||||
The log includes browser state transitions and result‑set changes.
|
||||
|
||||
## Common failure modes
|
||||
|
||||
- **Bonjour doesn’t cross networks**: use Tailnet or SSH.
|
||||
- **Multicast blocked**: some Wi‑Fi networks disable mDNS.
|
||||
- **Sleep / interface churn**: macOS may temporarily drop mDNS results; retry.
|
||||
- **Browse works but resolve fails**: keep machine names simple (avoid emojis or
|
||||
punctuation), then restart the Gateway. The service instance name derives from
|
||||
the host name, so overly complex names can confuse some resolvers.
|
||||
|
||||
## Escaped instance names (`\032`)
|
||||
|
||||
Bonjour/DNS‑SD often escapes bytes in service instance names as decimal `\DDD`
|
||||
sequences (e.g. spaces become `\032`).
|
||||
|
||||
- This is normal at the protocol level.
|
||||
- UIs should decode for display (iOS uses `BonjourEscapes.decode`).
|
||||
|
||||
## Disabling / configuration
|
||||
|
||||
- `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
|
||||
|
||||
- Discovery policy and transport selection: [Discovery](/gateway/discovery)
|
||||
- Node pairing + approvals: [Gateway pairing](/gateway/pairing)
|
||||
91
openclaw/docs/gateway/bridge-protocol.md
Normal file
91
openclaw/docs/gateway/bridge-protocol.md
Normal file
@@ -0,0 +1,91 @@
|
||||
---
|
||||
summary: "Bridge protocol (legacy nodes): TCP JSONL, pairing, scoped RPC"
|
||||
read_when:
|
||||
- Building or debugging node clients (iOS/Android/macOS node mode)
|
||||
- Investigating pairing or bridge auth failures
|
||||
- Auditing the node surface exposed by the gateway
|
||||
title: "Bridge Protocol"
|
||||
---
|
||||
|
||||
# Bridge protocol (legacy node transport)
|
||||
|
||||
The Bridge protocol is a **legacy** node transport (TCP JSONL). New node clients
|
||||
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 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
|
||||
|
||||
- **Security boundary**: the bridge exposes a small allowlist instead of the
|
||||
full gateway API surface.
|
||||
- **Pairing + node identity**: node admission is owned by the gateway and tied
|
||||
to a per-node token.
|
||||
- **Discovery UX**: nodes can discover gateways via Bonjour on LAN, or connect
|
||||
directly over a tailnet.
|
||||
- **Loopback WS**: the full WS control plane stays local unless tunneled via SSH.
|
||||
|
||||
## Transport
|
||||
|
||||
- TCP, one JSON object per line (JSONL).
|
||||
- Optional TLS (when `bridge.tls.enabled` is true).
|
||||
- Legacy default listener port was `18790` (current builds do not start a TCP bridge).
|
||||
|
||||
When TLS is enabled, discovery TXT records include `bridgeTls=1` plus
|
||||
`bridgeTlsSha256` as a non-secret hint. Note that Bonjour/mDNS TXT records are
|
||||
unauthenticated; clients must not treat the advertised fingerprint as an
|
||||
authoritative pin without explicit user intent or other out-of-band verification.
|
||||
|
||||
## Handshake + pairing
|
||||
|
||||
1. Client sends `hello` with node metadata + token (if already paired).
|
||||
2. If not paired, gateway replies `error` (`NOT_PAIRED`/`UNAUTHORIZED`).
|
||||
3. Client sends `pair-request`.
|
||||
4. Gateway waits for approval, then sends `pair-ok` and `hello-ok`.
|
||||
|
||||
`hello-ok` returns `serverName` and may include `canvasHostUrl`.
|
||||
|
||||
## Frames
|
||||
|
||||
Client → Gateway:
|
||||
|
||||
- `req` / `res`: scoped gateway RPC (chat, sessions, config, health, voicewake, skills.bins)
|
||||
- `event`: node signals (voice transcript, agent request, chat subscribe, exec lifecycle)
|
||||
|
||||
Gateway → Client:
|
||||
|
||||
- `invoke` / `invoke-res`: node commands (`canvas.*`, `camera.*`, `screen.record`,
|
||||
`location.get`, `sms.send`)
|
||||
- `event`: chat updates for subscribed sessions
|
||||
- `ping` / `pong`: keepalive
|
||||
|
||||
Legacy allowlist enforcement lived in `src/gateway/server-bridge.ts` (removed).
|
||||
|
||||
## Exec lifecycle events
|
||||
|
||||
Nodes can emit `exec.finished` or `exec.denied` events to surface system.run activity.
|
||||
These are mapped to system events in the gateway. (Legacy nodes may still emit `exec.started`.)
|
||||
|
||||
Payload fields (all optional unless noted):
|
||||
|
||||
- `sessionKey` (required): agent session to receive the system event.
|
||||
- `runId`: unique exec id for grouping.
|
||||
- `command`: raw or formatted command string.
|
||||
- `exitCode`, `timedOut`, `success`, `output`: completion details (finished only).
|
||||
- `reason`: denial reason (denied only).
|
||||
|
||||
## Tailnet usage
|
||||
|
||||
- Bind the bridge to a tailnet IP: `bridge.bind: "tailnet"` in
|
||||
`~/.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.
|
||||
|
||||
## Versioning
|
||||
|
||||
Bridge is currently **implicit v1** (no min/max negotiation). Backward‑compat
|
||||
is expected; add a bridge protocol version field before any breaking changes.
|
||||
225
openclaw/docs/gateway/cli-backends.md
Normal file
225
openclaw/docs/gateway/cli-backends.md
Normal file
@@ -0,0 +1,225 @@
|
||||
---
|
||||
summary: "CLI backends: text-only fallback via local AI CLIs"
|
||||
read_when:
|
||||
- You want a reliable fallback when API providers fail
|
||||
- You are running Claude Code CLI or other local AI CLIs and want to reuse them
|
||||
- You need a text-only, tool-free path that still supports sessions and images
|
||||
title: "CLI Backends"
|
||||
---
|
||||
|
||||
# CLI backends (fallback runtime)
|
||||
|
||||
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).
|
||||
- **Text in → text out** (reliable).
|
||||
- **Sessions are supported** (so follow-up turns stay coherent).
|
||||
- **Images can be passed through** if the CLI accepts image paths.
|
||||
|
||||
This is designed as a **safety net** rather than a primary path. Use it when you
|
||||
want “always works” text responses without relying on external APIs.
|
||||
|
||||
## Beginner-friendly quick start
|
||||
|
||||
You can use Claude Code CLI **without any config** (OpenClaw ships a built-in default):
|
||||
|
||||
```bash
|
||||
openclaw agent --message "hi" --model claude-cli/opus-4.6
|
||||
```
|
||||
|
||||
Codex CLI also works out of the box:
|
||||
|
||||
```bash
|
||||
openclaw agent --message "hi" --model codex-cli/gpt-5.3-codex
|
||||
```
|
||||
|
||||
If your gateway runs under launchd/systemd and PATH is minimal, add just the
|
||||
command path:
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
cliBackends: {
|
||||
"claude-cli": {
|
||||
command: "/opt/homebrew/bin/claude",
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
That’s it. No keys, no extra auth config needed beyond the CLI itself.
|
||||
|
||||
## Using it as a fallback
|
||||
|
||||
Add a CLI backend to your fallback list so it only runs when primary models fail:
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
model: {
|
||||
primary: "anthropic/claude-opus-4-6",
|
||||
fallbacks: ["claude-cli/opus-4.6", "claude-cli/opus-4.5"],
|
||||
},
|
||||
models: {
|
||||
"anthropic/claude-opus-4-6": { alias: "Opus" },
|
||||
"claude-cli/opus-4.6": {},
|
||||
"claude-cli/opus-4.5": {},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- If you use `agents.defaults.models` (allowlist), you must include `claude-cli/...`.
|
||||
- If the primary provider fails (auth, rate limits, timeouts), OpenClaw will
|
||||
try the CLI backend next.
|
||||
|
||||
## Configuration overview
|
||||
|
||||
All CLI backends live under:
|
||||
|
||||
```
|
||||
agents.defaults.cliBackends
|
||||
```
|
||||
|
||||
Each entry is keyed by a **provider id** (e.g. `claude-cli`, `my-cli`).
|
||||
The provider id becomes the left side of your model ref:
|
||||
|
||||
```
|
||||
<provider>/<model>
|
||||
```
|
||||
|
||||
### Example configuration
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
cliBackends: {
|
||||
"claude-cli": {
|
||||
command: "/opt/homebrew/bin/claude",
|
||||
},
|
||||
"my-cli": {
|
||||
command: "my-cli",
|
||||
args: ["--json"],
|
||||
output: "json",
|
||||
input: "arg",
|
||||
modelArg: "--model",
|
||||
modelAliases: {
|
||||
"claude-opus-4-6": "opus",
|
||||
"claude-opus-4-5": "opus",
|
||||
"claude-sonnet-4-5": "sonnet",
|
||||
},
|
||||
sessionArg: "--session",
|
||||
sessionMode: "existing",
|
||||
sessionIdFields: ["session_id", "conversation_id"],
|
||||
systemPromptArg: "--system",
|
||||
systemPromptWhen: "first",
|
||||
imageArg: "--image",
|
||||
imageMode: "repeat",
|
||||
serialize: true,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## How it works
|
||||
|
||||
1. **Selects a backend** based on the provider prefix (`claude-cli/...`).
|
||||
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.
|
||||
|
||||
## Sessions
|
||||
|
||||
- If the CLI supports sessions, set `sessionArg` (e.g. `--session-id`) or
|
||||
`sessionArgs` (placeholder `{sessionId}`) when the ID needs to be inserted
|
||||
into multiple flags.
|
||||
- If the CLI uses a **resume subcommand** with different flags, set
|
||||
`resumeArgs` (replaces `args` when resuming) and optionally `resumeOutput`
|
||||
(for non-JSON resumes).
|
||||
- `sessionMode`:
|
||||
- `always`: always send a session id (new UUID if none stored).
|
||||
- `existing`: only send a session id if one was stored before.
|
||||
- `none`: never send a session id.
|
||||
|
||||
## Images (pass-through)
|
||||
|
||||
If your CLI accepts image paths, set `imageArg`:
|
||||
|
||||
```json5
|
||||
imageArg: "--image",
|
||||
imageMode: "repeat"
|
||||
```
|
||||
|
||||
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).
|
||||
|
||||
## Inputs / outputs
|
||||
|
||||
- `output: "json"` (default) tries to parse JSON and extract text + session id.
|
||||
- `output: "jsonl"` parses JSONL streams (Codex CLI `--json`) and extracts the
|
||||
last agent message plus `thread_id` when present.
|
||||
- `output: "text"` treats stdout as the final response.
|
||||
|
||||
Input modes:
|
||||
|
||||
- `input: "arg"` (default) passes the prompt as the last CLI arg.
|
||||
- `input: "stdin"` sends the prompt via stdin.
|
||||
- If the prompt is very long and `maxPromptArgChars` is set, stdin is used.
|
||||
|
||||
## Defaults (built-in)
|
||||
|
||||
OpenClaw ships a default for `claude-cli`:
|
||||
|
||||
- `command: "claude"`
|
||||
- `args: ["-p", "--output-format", "json", "--dangerously-skip-permissions"]`
|
||||
- `resumeArgs: ["-p", "--output-format", "json", "--dangerously-skip-permissions", "--resume", "{sessionId}"]`
|
||||
- `modelArg: "--model"`
|
||||
- `systemPromptArg: "--append-system-prompt"`
|
||||
- `sessionArg: "--session-id"`
|
||||
- `systemPromptWhen: "first"`
|
||||
- `sessionMode: "always"`
|
||||
|
||||
OpenClaw also ships a default for `codex-cli`:
|
||||
|
||||
- `command: "codex"`
|
||||
- `args: ["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]`
|
||||
- `resumeArgs: ["exec","resume","{sessionId}","--color","never","--sandbox","read-only","--skip-git-repo-check"]`
|
||||
- `output: "jsonl"`
|
||||
- `resumeOutput: "text"`
|
||||
- `modelArg: "--model"`
|
||||
- `imageArg: "--image"`
|
||||
- `sessionMode: "existing"`
|
||||
|
||||
Override only if needed (common: absolute `command` path).
|
||||
|
||||
## Limitations
|
||||
|
||||
- **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. OpenClaw sessions still work
|
||||
normally.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- **CLI not found**: set `command` to a full path.
|
||||
- **Wrong model name**: use `modelAliases` to map `provider/model` → CLI model.
|
||||
- **No session continuity**: ensure `sessionArg` is set and `sessionMode` is not
|
||||
`none` (Codex CLI currently cannot resume with JSON output).
|
||||
- **Images ignored**: set `imageArg` (and verify CLI supports file paths).
|
||||
631
openclaw/docs/gateway/configuration-examples.md
Normal file
631
openclaw/docs/gateway/configuration-examples.md
Normal file
@@ -0,0 +1,631 @@
|
||||
---
|
||||
summary: "Schema-accurate configuration examples for common OpenClaw setups"
|
||||
read_when:
|
||||
- Learning how to configure OpenClaw
|
||||
- Looking for configuration examples
|
||||
- Setting up OpenClaw for the first time
|
||||
title: "Configuration Examples"
|
||||
---
|
||||
|
||||
# Configuration Examples
|
||||
|
||||
Examples below are aligned with the current config schema. For the exhaustive reference and per-field notes, see [Configuration](/gateway/configuration).
|
||||
|
||||
## Quick start
|
||||
|
||||
### Absolute minimum
|
||||
|
||||
```json5
|
||||
{
|
||||
agent: { workspace: "~/.openclaw/workspace" },
|
||||
channels: { whatsapp: { allowFrom: ["+15555550123"] } },
|
||||
}
|
||||
```
|
||||
|
||||
Save to `~/.openclaw/openclaw.json` and you can DM the bot from that number.
|
||||
|
||||
### Recommended starter
|
||||
|
||||
```json5
|
||||
{
|
||||
identity: {
|
||||
name: "Clawd",
|
||||
theme: "helpful assistant",
|
||||
emoji: "🦞",
|
||||
},
|
||||
agent: {
|
||||
workspace: "~/.openclaw/workspace",
|
||||
model: { primary: "anthropic/claude-sonnet-4-5" },
|
||||
},
|
||||
channels: {
|
||||
whatsapp: {
|
||||
allowFrom: ["+15555550123"],
|
||||
groups: { "*": { requireMention: true } },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## Expanded example (major options)
|
||||
|
||||
> JSON5 lets you use comments and trailing commas. Regular JSON works too.
|
||||
|
||||
```json5
|
||||
{
|
||||
// Environment + shell
|
||||
env: {
|
||||
OPENROUTER_API_KEY: "sk-or-...",
|
||||
vars: {
|
||||
GROQ_API_KEY: "gsk-...",
|
||||
},
|
||||
shellEnv: {
|
||||
enabled: true,
|
||||
timeoutMs: 15000,
|
||||
},
|
||||
},
|
||||
|
||||
// Auth profile metadata (secrets live in auth-profiles.json)
|
||||
auth: {
|
||||
profiles: {
|
||||
"anthropic:me@example.com": {
|
||||
provider: "anthropic",
|
||||
mode: "oauth",
|
||||
email: "me@example.com",
|
||||
},
|
||||
"anthropic:work": { provider: "anthropic", mode: "api_key" },
|
||||
"openai:default": { provider: "openai", mode: "api_key" },
|
||||
"openai-codex:default": { provider: "openai-codex", mode: "oauth" },
|
||||
},
|
||||
order: {
|
||||
anthropic: ["anthropic:me@example.com", "anthropic:work"],
|
||||
openai: ["openai:default"],
|
||||
"openai-codex": ["openai-codex:default"],
|
||||
},
|
||||
},
|
||||
|
||||
// Identity
|
||||
identity: {
|
||||
name: "Samantha",
|
||||
theme: "helpful sloth",
|
||||
emoji: "🦥",
|
||||
},
|
||||
|
||||
// Logging
|
||||
logging: {
|
||||
level: "info",
|
||||
file: "/tmp/openclaw/openclaw.log",
|
||||
consoleLevel: "info",
|
||||
consoleStyle: "pretty",
|
||||
redactSensitive: "tools",
|
||||
},
|
||||
|
||||
// Message formatting
|
||||
messages: {
|
||||
messagePrefix: "[openclaw]",
|
||||
responsePrefix: ">",
|
||||
ackReaction: "👀",
|
||||
ackReactionScope: "group-mentions",
|
||||
},
|
||||
|
||||
// Routing + queue
|
||||
routing: {
|
||||
groupChat: {
|
||||
mentionPatterns: ["@openclaw", "openclaw"],
|
||||
historyLimit: 50,
|
||||
},
|
||||
queue: {
|
||||
mode: "collect",
|
||||
debounceMs: 1000,
|
||||
cap: 20,
|
||||
drop: "summarize",
|
||||
byChannel: {
|
||||
whatsapp: "collect",
|
||||
telegram: "collect",
|
||||
discord: "collect",
|
||||
slack: "collect",
|
||||
signal: "collect",
|
||||
imessage: "collect",
|
||||
webchat: "collect",
|
||||
},
|
||||
},
|
||||
},
|
||||
|
||||
// Tooling
|
||||
tools: {
|
||||
media: {
|
||||
audio: {
|
||||
enabled: true,
|
||||
maxBytes: 20971520,
|
||||
models: [
|
||||
{ provider: "openai", model: "gpt-4o-mini-transcribe" },
|
||||
// Optional CLI fallback (Whisper binary):
|
||||
// { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] }
|
||||
],
|
||||
timeoutSeconds: 120,
|
||||
},
|
||||
video: {
|
||||
enabled: true,
|
||||
maxBytes: 52428800,
|
||||
models: [{ provider: "google", model: "gemini-3-flash-preview" }],
|
||||
},
|
||||
},
|
||||
},
|
||||
|
||||
// Session behavior
|
||||
session: {
|
||||
scope: "per-sender",
|
||||
reset: {
|
||||
mode: "daily",
|
||||
atHour: 4,
|
||||
idleMinutes: 60,
|
||||
},
|
||||
resetByChannel: {
|
||||
discord: { mode: "idle", idleMinutes: 10080 },
|
||||
},
|
||||
resetTriggers: ["/new", "/reset"],
|
||||
store: "~/.openclaw/agents/default/sessions/sessions.json",
|
||||
maintenance: {
|
||||
mode: "warn",
|
||||
pruneAfter: "30d",
|
||||
maxEntries: 500,
|
||||
rotateBytes: "10mb",
|
||||
resetArchiveRetention: "30d", // duration or false
|
||||
maxDiskBytes: "500mb", // optional
|
||||
highWaterBytes: "400mb", // optional (defaults to 80% of maxDiskBytes)
|
||||
},
|
||||
typingIntervalSeconds: 5,
|
||||
sendPolicy: {
|
||||
default: "allow",
|
||||
rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
|
||||
},
|
||||
},
|
||||
|
||||
// Channels
|
||||
channels: {
|
||||
whatsapp: {
|
||||
dmPolicy: "pairing",
|
||||
allowFrom: ["+15555550123"],
|
||||
groupPolicy: "allowlist",
|
||||
groupAllowFrom: ["+15555550123"],
|
||||
groups: { "*": { requireMention: true } },
|
||||
},
|
||||
|
||||
telegram: {
|
||||
enabled: true,
|
||||
botToken: "YOUR_TELEGRAM_BOT_TOKEN",
|
||||
allowFrom: ["123456789"],
|
||||
groupPolicy: "allowlist",
|
||||
groupAllowFrom: ["123456789"],
|
||||
groups: { "*": { requireMention: true } },
|
||||
},
|
||||
|
||||
discord: {
|
||||
enabled: true,
|
||||
token: "YOUR_DISCORD_BOT_TOKEN",
|
||||
dm: { enabled: true, allowFrom: ["123456789012345678"] },
|
||||
guilds: {
|
||||
"123456789012345678": {
|
||||
slug: "friends-of-openclaw",
|
||||
requireMention: false,
|
||||
channels: {
|
||||
general: { allow: true },
|
||||
help: { allow: true, requireMention: true },
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
|
||||
slack: {
|
||||
enabled: true,
|
||||
botToken: "xoxb-REPLACE_ME",
|
||||
appToken: "xapp-REPLACE_ME",
|
||||
channels: {
|
||||
"#general": { allow: true, requireMention: true },
|
||||
},
|
||||
dm: { enabled: true, allowFrom: ["U123"] },
|
||||
slashCommand: {
|
||||
enabled: true,
|
||||
name: "openclaw",
|
||||
sessionPrefix: "slack:slash",
|
||||
ephemeral: true,
|
||||
},
|
||||
},
|
||||
},
|
||||
|
||||
// Agent runtime
|
||||
agents: {
|
||||
defaults: {
|
||||
workspace: "~/.openclaw/workspace",
|
||||
userTimezone: "America/Chicago",
|
||||
model: {
|
||||
primary: "anthropic/claude-sonnet-4-5",
|
||||
fallbacks: ["anthropic/claude-opus-4-6", "openai/gpt-5.2"],
|
||||
},
|
||||
imageModel: {
|
||||
primary: "openrouter/anthropic/claude-sonnet-4-5",
|
||||
},
|
||||
models: {
|
||||
"anthropic/claude-opus-4-6": { alias: "opus" },
|
||||
"anthropic/claude-sonnet-4-5": { alias: "sonnet" },
|
||||
"openai/gpt-5.2": { alias: "gpt" },
|
||||
},
|
||||
thinkingDefault: "low",
|
||||
verboseDefault: "off",
|
||||
elevatedDefault: "on",
|
||||
blockStreamingDefault: "off",
|
||||
blockStreamingBreak: "text_end",
|
||||
blockStreamingChunk: {
|
||||
minChars: 800,
|
||||
maxChars: 1200,
|
||||
breakPreference: "paragraph",
|
||||
},
|
||||
blockStreamingCoalesce: {
|
||||
idleMs: 1000,
|
||||
},
|
||||
humanDelay: {
|
||||
mode: "natural",
|
||||
},
|
||||
timeoutSeconds: 600,
|
||||
mediaMaxMb: 5,
|
||||
typingIntervalSeconds: 5,
|
||||
maxConcurrent: 3,
|
||||
heartbeat: {
|
||||
every: "30m",
|
||||
model: "anthropic/claude-sonnet-4-5",
|
||||
target: "last",
|
||||
directPolicy: "allow", // allow (default) | block
|
||||
to: "+15555550123",
|
||||
prompt: "HEARTBEAT",
|
||||
ackMaxChars: 300,
|
||||
},
|
||||
memorySearch: {
|
||||
provider: "gemini",
|
||||
model: "gemini-embedding-001",
|
||||
remote: {
|
||||
apiKey: "${GEMINI_API_KEY}",
|
||||
},
|
||||
extraPaths: ["../team-docs", "/srv/shared-notes"],
|
||||
},
|
||||
sandbox: {
|
||||
mode: "non-main",
|
||||
perSession: true,
|
||||
workspaceRoot: "~/.openclaw/sandboxes",
|
||||
docker: {
|
||||
image: "openclaw-sandbox:bookworm-slim",
|
||||
workdir: "/workspace",
|
||||
readOnlyRoot: true,
|
||||
tmpfs: ["/tmp", "/var/tmp", "/run"],
|
||||
network: "none",
|
||||
user: "1000:1000",
|
||||
},
|
||||
browser: {
|
||||
enabled: false,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
|
||||
tools: {
|
||||
allow: ["exec", "process", "read", "write", "edit", "apply_patch"],
|
||||
deny: ["browser", "canvas"],
|
||||
exec: {
|
||||
backgroundMs: 10000,
|
||||
timeoutSec: 1800,
|
||||
cleanupMs: 1800000,
|
||||
},
|
||||
elevated: {
|
||||
enabled: true,
|
||||
allowFrom: {
|
||||
whatsapp: ["+15555550123"],
|
||||
telegram: ["123456789"],
|
||||
discord: ["123456789012345678"],
|
||||
slack: ["U123"],
|
||||
signal: ["+15555550123"],
|
||||
imessage: ["user@example.com"],
|
||||
webchat: ["session:demo"],
|
||||
},
|
||||
},
|
||||
},
|
||||
|
||||
// Custom model providers
|
||||
models: {
|
||||
mode: "merge",
|
||||
providers: {
|
||||
"custom-proxy": {
|
||||
baseUrl: "http://localhost:4000/v1",
|
||||
apiKey: "LITELLM_KEY",
|
||||
api: "openai-responses",
|
||||
authHeader: true,
|
||||
headers: { "X-Proxy-Region": "us-west" },
|
||||
models: [
|
||||
{
|
||||
id: "llama-3.1-8b",
|
||||
name: "Llama 3.1 8B",
|
||||
api: "openai-responses",
|
||||
reasoning: false,
|
||||
input: ["text"],
|
||||
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
|
||||
contextWindow: 128000,
|
||||
maxTokens: 32000,
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
},
|
||||
|
||||
// Cron jobs
|
||||
cron: {
|
||||
enabled: true,
|
||||
store: "~/.openclaw/cron/cron.json",
|
||||
maxConcurrentRuns: 2,
|
||||
sessionRetention: "24h",
|
||||
runLog: {
|
||||
maxBytes: "2mb",
|
||||
keepLines: 2000,
|
||||
},
|
||||
},
|
||||
|
||||
// Webhooks
|
||||
hooks: {
|
||||
enabled: true,
|
||||
path: "/hooks",
|
||||
token: "shared-secret",
|
||||
presets: ["gmail"],
|
||||
transformsDir: "~/.openclaw/hooks/transforms",
|
||||
mappings: [
|
||||
{
|
||||
id: "gmail-hook",
|
||||
match: { path: "gmail" },
|
||||
action: "agent",
|
||||
wakeMode: "now",
|
||||
name: "Gmail",
|
||||
sessionKey: "hook:gmail:{{messages[0].id}}",
|
||||
messageTemplate: "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}",
|
||||
textTemplate: "{{messages[0].snippet}}",
|
||||
deliver: true,
|
||||
channel: "last",
|
||||
to: "+15555550123",
|
||||
thinking: "low",
|
||||
timeoutSeconds: 300,
|
||||
transform: {
|
||||
module: "gmail.js",
|
||||
export: "transformGmail",
|
||||
},
|
||||
},
|
||||
],
|
||||
gmail: {
|
||||
account: "openclaw@gmail.com",
|
||||
label: "INBOX",
|
||||
topic: "projects/<project-id>/topics/gog-gmail-watch",
|
||||
subscription: "gog-gmail-watch-push",
|
||||
pushToken: "shared-push-token",
|
||||
hookUrl: "http://127.0.0.1:18789/hooks/gmail",
|
||||
includeBody: true,
|
||||
maxBytes: 20000,
|
||||
renewEveryMinutes: 720,
|
||||
serve: { bind: "127.0.0.1", port: 8788, path: "/" },
|
||||
tailscale: { mode: "funnel", path: "/gmail-pubsub" },
|
||||
},
|
||||
},
|
||||
|
||||
// Gateway + networking
|
||||
gateway: {
|
||||
mode: "local",
|
||||
port: 18789,
|
||||
bind: "loopback",
|
||||
controlUi: { enabled: true, basePath: "/openclaw" },
|
||||
auth: {
|
||||
mode: "token",
|
||||
token: "gateway-token",
|
||||
allowTailscale: true,
|
||||
},
|
||||
tailscale: { mode: "serve", resetOnExit: false },
|
||||
remote: { url: "ws://gateway.tailnet:18789", token: "remote-token" },
|
||||
reload: { mode: "hybrid", debounceMs: 300 },
|
||||
},
|
||||
|
||||
skills: {
|
||||
allowBundled: ["gemini", "peekaboo"],
|
||||
load: {
|
||||
extraDirs: ["~/Projects/agent-scripts/skills"],
|
||||
},
|
||||
install: {
|
||||
preferBrew: true,
|
||||
nodeManager: "npm",
|
||||
},
|
||||
entries: {
|
||||
"nano-banana-pro": {
|
||||
enabled: true,
|
||||
apiKey: "GEMINI_KEY_HERE",
|
||||
env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
|
||||
},
|
||||
peekaboo: { enabled: true },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## Common patterns
|
||||
|
||||
### Multi-platform setup
|
||||
|
||||
```json5
|
||||
{
|
||||
agent: { workspace: "~/.openclaw/workspace" },
|
||||
channels: {
|
||||
whatsapp: { allowFrom: ["+15555550123"] },
|
||||
telegram: {
|
||||
enabled: true,
|
||||
botToken: "YOUR_TOKEN",
|
||||
allowFrom: ["123456789"],
|
||||
},
|
||||
discord: {
|
||||
enabled: true,
|
||||
token: "YOUR_TOKEN",
|
||||
dm: { allowFrom: ["123456789012345678"] },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Secure DM mode (shared inbox / multi-user DMs)
|
||||
|
||||
If more than one person can DM your bot (multiple entries in `allowFrom`, pairing approvals for multiple people, or `dmPolicy: "open"`), enable **secure DM mode** so DMs from different senders don’t share one context by default:
|
||||
|
||||
```json5
|
||||
{
|
||||
// Secure DM mode (recommended for multi-user or sensitive DM agents)
|
||||
session: { dmScope: "per-channel-peer" },
|
||||
|
||||
channels: {
|
||||
// Example: WhatsApp multi-user inbox
|
||||
whatsapp: {
|
||||
dmPolicy: "allowlist",
|
||||
allowFrom: ["+15555550123", "+15555550124"],
|
||||
},
|
||||
|
||||
// Example: Discord multi-user inbox
|
||||
discord: {
|
||||
enabled: true,
|
||||
token: "YOUR_DISCORD_BOT_TOKEN",
|
||||
dm: { enabled: true, allowFrom: ["123456789012345678", "987654321098765432"] },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
For Discord/Slack/Google Chat/MS Teams/Mattermost/IRC, sender authorization is ID-first by default.
|
||||
Only enable direct mutable name/email/nick matching with each channel's `dangerouslyAllowNameMatching: true` if you explicitly accept that risk.
|
||||
|
||||
### OAuth with API key failover
|
||||
|
||||
```json5
|
||||
{
|
||||
auth: {
|
||||
profiles: {
|
||||
"anthropic:subscription": {
|
||||
provider: "anthropic",
|
||||
mode: "oauth",
|
||||
email: "me@example.com",
|
||||
},
|
||||
"anthropic:api": {
|
||||
provider: "anthropic",
|
||||
mode: "api_key",
|
||||
},
|
||||
},
|
||||
order: {
|
||||
anthropic: ["anthropic:subscription", "anthropic:api"],
|
||||
},
|
||||
},
|
||||
agent: {
|
||||
workspace: "~/.openclaw/workspace",
|
||||
model: {
|
||||
primary: "anthropic/claude-sonnet-4-5",
|
||||
fallbacks: ["anthropic/claude-opus-4-6"],
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Anthropic subscription + API key, MiniMax fallback
|
||||
|
||||
```json5
|
||||
{
|
||||
auth: {
|
||||
profiles: {
|
||||
"anthropic:subscription": {
|
||||
provider: "anthropic",
|
||||
mode: "oauth",
|
||||
email: "user@example.com",
|
||||
},
|
||||
"anthropic:api": {
|
||||
provider: "anthropic",
|
||||
mode: "api_key",
|
||||
},
|
||||
},
|
||||
order: {
|
||||
anthropic: ["anthropic:subscription", "anthropic:api"],
|
||||
},
|
||||
},
|
||||
models: {
|
||||
providers: {
|
||||
minimax: {
|
||||
baseUrl: "https://api.minimax.io/anthropic",
|
||||
api: "anthropic-messages",
|
||||
apiKey: "${MINIMAX_API_KEY}",
|
||||
},
|
||||
},
|
||||
},
|
||||
agent: {
|
||||
workspace: "~/.openclaw/workspace",
|
||||
model: {
|
||||
primary: "anthropic/claude-opus-4-6",
|
||||
fallbacks: ["minimax/MiniMax-M2.1"],
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Work bot (restricted access)
|
||||
|
||||
```json5
|
||||
{
|
||||
identity: {
|
||||
name: "WorkBot",
|
||||
theme: "professional assistant",
|
||||
},
|
||||
agent: {
|
||||
workspace: "~/work-openclaw",
|
||||
elevated: { enabled: false },
|
||||
},
|
||||
channels: {
|
||||
slack: {
|
||||
enabled: true,
|
||||
botToken: "xoxb-...",
|
||||
channels: {
|
||||
"#engineering": { allow: true, requireMention: true },
|
||||
"#general": { allow: true, requireMention: true },
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Local models only
|
||||
|
||||
```json5
|
||||
{
|
||||
agent: {
|
||||
workspace: "~/.openclaw/workspace",
|
||||
model: { primary: "lmstudio/minimax-m2.1-gs32" },
|
||||
},
|
||||
models: {
|
||||
mode: "merge",
|
||||
providers: {
|
||||
lmstudio: {
|
||||
baseUrl: "http://127.0.0.1:1234/v1",
|
||||
apiKey: "lmstudio",
|
||||
api: "openai-responses",
|
||||
models: [
|
||||
{
|
||||
id: "minimax-m2.1-gs32",
|
||||
name: "MiniMax M2.1 GS32",
|
||||
reasoning: false,
|
||||
input: ["text"],
|
||||
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
|
||||
contextWindow: 196608,
|
||||
maxTokens: 8192,
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## Tips
|
||||
|
||||
- If you set `dmPolicy: "open"`, the matching `allowFrom` list must include `"*"`.
|
||||
- Provider IDs differ (phone numbers, user IDs, channel IDs). Use the provider docs to confirm the format.
|
||||
- Optional sections to add later: `web`, `browser`, `ui`, `discovery`, `canvasHost`, `talk`, `signal`, `imessage`.
|
||||
- See [Providers](/providers) and [Troubleshooting](/gateway/troubleshooting) for deeper setup notes.
|
||||
2796
openclaw/docs/gateway/configuration-reference.md
Normal file
2796
openclaw/docs/gateway/configuration-reference.md
Normal file
File diff suppressed because it is too large
Load Diff
540
openclaw/docs/gateway/configuration.md
Normal file
540
openclaw/docs/gateway/configuration.md
Normal file
@@ -0,0 +1,540 @@
|
||||
---
|
||||
summary: "Configuration overview: common tasks, quick setup, and links to the full reference"
|
||||
read_when:
|
||||
- Setting up OpenClaw for the first time
|
||||
- Looking for common configuration patterns
|
||||
- Navigating to specific config sections
|
||||
title: "Configuration"
|
||||
---
|
||||
|
||||
# Configuration
|
||||
|
||||
OpenClaw reads an optional <Tooltip tip="JSON5 supports comments and trailing commas">**JSON5**</Tooltip> config from `~/.openclaw/openclaw.json`.
|
||||
|
||||
If the file is missing, OpenClaw uses safe defaults. Common reasons to add a config:
|
||||
|
||||
- Connect channels and control who can message the bot
|
||||
- Set models, tools, sandboxing, or automation (cron, hooks)
|
||||
- Tune sessions, media, networking, or UI
|
||||
|
||||
See the [full reference](/gateway/configuration-reference) for every available field.
|
||||
|
||||
<Tip>
|
||||
**New to configuration?** Start with `openclaw onboard` for interactive setup, or check out the [Configuration Examples](/gateway/configuration-examples) guide for complete copy-paste configs.
|
||||
</Tip>
|
||||
|
||||
## Minimal config
|
||||
|
||||
```json5
|
||||
// ~/.openclaw/openclaw.json
|
||||
{
|
||||
agents: { defaults: { workspace: "~/.openclaw/workspace" } },
|
||||
channels: { whatsapp: { allowFrom: ["+15555550123"] } },
|
||||
}
|
||||
```
|
||||
|
||||
## Editing config
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Interactive wizard">
|
||||
```bash
|
||||
openclaw onboard # full setup wizard
|
||||
openclaw configure # config wizard
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="CLI (one-liners)">
|
||||
```bash
|
||||
openclaw config get agents.defaults.workspace
|
||||
openclaw config set agents.defaults.heartbeat.every "2h"
|
||||
openclaw config unset tools.web.search.apiKey
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Control UI">
|
||||
Open [http://127.0.0.1:18789](http://127.0.0.1:18789) and use the **Config** tab.
|
||||
The Control UI renders a form from the config schema, with a **Raw JSON** editor as an escape hatch.
|
||||
</Tab>
|
||||
<Tab title="Direct edit">
|
||||
Edit `~/.openclaw/openclaw.json` directly. The Gateway watches the file and applies changes automatically (see [hot reload](#config-hot-reload)).
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Strict validation
|
||||
|
||||
<Warning>
|
||||
OpenClaw only accepts configurations that fully match the schema. Unknown keys, malformed types, or invalid values cause the Gateway to **refuse to start**. The only root-level exception is `$schema` (string), so editors can attach JSON Schema metadata.
|
||||
</Warning>
|
||||
|
||||
When validation fails:
|
||||
|
||||
- The Gateway does not boot
|
||||
- Only diagnostic commands work (`openclaw doctor`, `openclaw logs`, `openclaw health`, `openclaw status`)
|
||||
- Run `openclaw doctor` to see exact issues
|
||||
- Run `openclaw doctor --fix` (or `--yes`) to apply repairs
|
||||
|
||||
## Common tasks
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Set up a channel (WhatsApp, Telegram, Discord, etc.)">
|
||||
Each channel has its own config section under `channels.<provider>`. See the dedicated channel page for setup steps:
|
||||
|
||||
- [WhatsApp](/channels/whatsapp) — `channels.whatsapp`
|
||||
- [Telegram](/channels/telegram) — `channels.telegram`
|
||||
- [Discord](/channels/discord) — `channels.discord`
|
||||
- [Slack](/channels/slack) — `channels.slack`
|
||||
- [Signal](/channels/signal) — `channels.signal`
|
||||
- [iMessage](/channels/imessage) — `channels.imessage`
|
||||
- [Google Chat](/channels/googlechat) — `channels.googlechat`
|
||||
- [Mattermost](/channels/mattermost) — `channels.mattermost`
|
||||
- [MS Teams](/channels/msteams) — `channels.msteams`
|
||||
|
||||
All channels share the same DM policy pattern:
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
telegram: {
|
||||
enabled: true,
|
||||
botToken: "123:abc",
|
||||
dmPolicy: "pairing", // pairing | allowlist | open | disabled
|
||||
allowFrom: ["tg:123"], // only for allowlist/open
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Choose and configure models">
|
||||
Set the primary model and optional fallbacks:
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
model: {
|
||||
primary: "anthropic/claude-sonnet-4-5",
|
||||
fallbacks: ["openai/gpt-5.2"],
|
||||
},
|
||||
models: {
|
||||
"anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
|
||||
"openai/gpt-5.2": { alias: "GPT" },
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
- `agents.defaults.models` defines the model catalog and acts as the allowlist for `/model`.
|
||||
- Model refs use `provider/model` format (e.g. `anthropic/claude-opus-4-6`).
|
||||
- `agents.defaults.imageMaxDimensionPx` controls transcript/tool image downscaling (default `1200`); lower values usually reduce vision-token usage on screenshot-heavy runs.
|
||||
- See [Models CLI](/concepts/models) for switching models in chat and [Model Failover](/concepts/model-failover) for auth rotation and fallback behavior.
|
||||
- For custom/self-hosted providers, see [Custom providers](/gateway/configuration-reference#custom-providers-and-base-urls) in the reference.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Control who can message the bot">
|
||||
DM access is controlled per channel via `dmPolicy`:
|
||||
|
||||
- `"pairing"` (default): unknown senders get a one-time pairing code to approve
|
||||
- `"allowlist"`: only senders in `allowFrom` (or the paired allow store)
|
||||
- `"open"`: allow all inbound DMs (requires `allowFrom: ["*"]`)
|
||||
- `"disabled"`: ignore all DMs
|
||||
|
||||
For groups, use `groupPolicy` + `groupAllowFrom` or channel-specific allowlists.
|
||||
|
||||
See the [full reference](/gateway/configuration-reference#dm-and-group-access) for per-channel details.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Set up group chat mention gating">
|
||||
Group messages default to **require mention**. Configure patterns per agent:
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
list: [
|
||||
{
|
||||
id: "main",
|
||||
groupChat: {
|
||||
mentionPatterns: ["@openclaw", "openclaw"],
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
channels: {
|
||||
whatsapp: {
|
||||
groups: { "*": { requireMention: true } },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
- **Metadata mentions**: native @-mentions (WhatsApp tap-to-mention, Telegram @bot, etc.)
|
||||
- **Text patterns**: regex patterns in `mentionPatterns`
|
||||
- See [full reference](/gateway/configuration-reference#group-chat-mention-gating) for per-channel overrides and self-chat mode.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Configure sessions and resets">
|
||||
Sessions control conversation continuity and isolation:
|
||||
|
||||
```json5
|
||||
{
|
||||
session: {
|
||||
dmScope: "per-channel-peer", // recommended for multi-user
|
||||
threadBindings: {
|
||||
enabled: true,
|
||||
idleHours: 24,
|
||||
maxAgeHours: 0,
|
||||
},
|
||||
reset: {
|
||||
mode: "daily",
|
||||
atHour: 4,
|
||||
idleMinutes: 120,
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
- `dmScope`: `main` (shared) | `per-peer` | `per-channel-peer` | `per-account-channel-peer`
|
||||
- `threadBindings`: global defaults for thread-bound session routing (Discord supports `/focus`, `/unfocus`, `/agents`, `/session idle`, and `/session max-age`).
|
||||
- See [Session Management](/concepts/session) for scoping, identity links, and send policy.
|
||||
- See [full reference](/gateway/configuration-reference#session) for all fields.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Enable sandboxing">
|
||||
Run agent sessions in isolated Docker containers:
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
sandbox: {
|
||||
mode: "non-main", // off | non-main | all
|
||||
scope: "agent", // session | agent | shared
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Build the image first: `scripts/sandbox-setup.sh`
|
||||
|
||||
See [Sandboxing](/gateway/sandboxing) for the full guide and [full reference](/gateway/configuration-reference#sandbox) for all options.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Set up heartbeat (periodic check-ins)">
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
heartbeat: {
|
||||
every: "30m",
|
||||
target: "last",
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
- `every`: duration string (`30m`, `2h`). Set `0m` to disable.
|
||||
- `target`: `last` | `whatsapp` | `telegram` | `discord` | `none`
|
||||
- `directPolicy`: `allow` (default) or `block` for DM-style heartbeat targets
|
||||
- See [Heartbeat](/gateway/heartbeat) for the full guide.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Configure cron jobs">
|
||||
```json5
|
||||
{
|
||||
cron: {
|
||||
enabled: true,
|
||||
maxConcurrentRuns: 2,
|
||||
sessionRetention: "24h",
|
||||
runLog: {
|
||||
maxBytes: "2mb",
|
||||
keepLines: 2000,
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
- `sessionRetention`: prune completed isolated run sessions from `sessions.json` (default `24h`; set `false` to disable).
|
||||
- `runLog`: prune `cron/runs/<jobId>.jsonl` by size and retained lines.
|
||||
- See [Cron jobs](/automation/cron-jobs) for feature overview and CLI examples.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Set up webhooks (hooks)">
|
||||
Enable HTTP webhook endpoints on the Gateway:
|
||||
|
||||
```json5
|
||||
{
|
||||
hooks: {
|
||||
enabled: true,
|
||||
token: "shared-secret",
|
||||
path: "/hooks",
|
||||
defaultSessionKey: "hook:ingress",
|
||||
allowRequestSessionKey: false,
|
||||
allowedSessionKeyPrefixes: ["hook:"],
|
||||
mappings: [
|
||||
{
|
||||
match: { path: "gmail" },
|
||||
action: "agent",
|
||||
agentId: "main",
|
||||
deliver: true,
|
||||
},
|
||||
],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
See [full reference](/gateway/configuration-reference#hooks) for all mapping options and Gmail integration.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Configure multi-agent routing">
|
||||
Run multiple isolated agents with separate workspaces and sessions:
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
list: [
|
||||
{ id: "home", default: true, workspace: "~/.openclaw/workspace-home" },
|
||||
{ id: "work", workspace: "~/.openclaw/workspace-work" },
|
||||
],
|
||||
},
|
||||
bindings: [
|
||||
{ agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
|
||||
{ agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
|
||||
],
|
||||
}
|
||||
```
|
||||
|
||||
See [Multi-Agent](/concepts/multi-agent) and [full reference](/gateway/configuration-reference#multi-agent-routing) for binding rules and per-agent access profiles.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Split config into multiple files ($include)">
|
||||
Use `$include` to organize large configs:
|
||||
|
||||
```json5
|
||||
// ~/.openclaw/openclaw.json
|
||||
{
|
||||
gateway: { port: 18789 },
|
||||
agents: { $include: "./agents.json5" },
|
||||
broadcast: {
|
||||
$include: ["./clients/a.json5", "./clients/b.json5"],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
- **Single file**: replaces the containing object
|
||||
- **Array of files**: deep-merged in order (later wins)
|
||||
- **Sibling keys**: merged after includes (override included values)
|
||||
- **Nested includes**: supported up to 10 levels deep
|
||||
- **Relative paths**: resolved relative to the including file
|
||||
- **Error handling**: clear errors for missing files, parse errors, and circular includes
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Config hot reload
|
||||
|
||||
The Gateway watches `~/.openclaw/openclaw.json` and applies changes automatically — no manual restart needed for most settings.
|
||||
|
||||
### Reload modes
|
||||
|
||||
| Mode | Behavior |
|
||||
| ---------------------- | --------------------------------------------------------------------------------------- |
|
||||
| **`hybrid`** (default) | Hot-applies safe changes instantly. Automatically restarts for critical ones. |
|
||||
| **`hot`** | Hot-applies safe changes only. Logs a warning when a restart is needed — you handle it. |
|
||||
| **`restart`** | Restarts the Gateway on any config change, safe or not. |
|
||||
| **`off`** | Disables file watching. Changes take effect on the next manual restart. |
|
||||
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
reload: { mode: "hybrid", debounceMs: 300 },
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### What hot-applies vs what needs a restart
|
||||
|
||||
Most fields hot-apply without downtime. In `hybrid` mode, restart-required changes are handled automatically.
|
||||
|
||||
| Category | Fields | Restart needed? |
|
||||
| ------------------- | -------------------------------------------------------------------- | --------------- |
|
||||
| Channels | `channels.*`, `web` (WhatsApp) — all built-in and extension channels | No |
|
||||
| Agent & models | `agent`, `agents`, `models`, `routing` | No |
|
||||
| Automation | `hooks`, `cron`, `agent.heartbeat` | No |
|
||||
| Sessions & messages | `session`, `messages` | No |
|
||||
| Tools & media | `tools`, `browser`, `skills`, `audio`, `talk` | No |
|
||||
| UI & misc | `ui`, `logging`, `identity`, `bindings` | No |
|
||||
| Gateway server | `gateway.*` (port, bind, auth, tailscale, TLS, HTTP) | **Yes** |
|
||||
| Infrastructure | `discovery`, `canvasHost`, `plugins` | **Yes** |
|
||||
|
||||
<Note>
|
||||
`gateway.reload` and `gateway.remote` are exceptions — changing them does **not** trigger a restart.
|
||||
</Note>
|
||||
|
||||
## Config RPC (programmatic updates)
|
||||
|
||||
<Note>
|
||||
Control-plane write RPCs (`config.apply`, `config.patch`, `update.run`) are rate-limited to **3 requests per 60 seconds** per `deviceId+clientIp`. When limited, the RPC returns `UNAVAILABLE` with `retryAfterMs`.
|
||||
</Note>
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="config.apply (full replace)">
|
||||
Validates + writes the full config and restarts the Gateway in one step.
|
||||
|
||||
<Warning>
|
||||
`config.apply` replaces the **entire config**. Use `config.patch` for partial updates, or `openclaw config set` for single keys.
|
||||
</Warning>
|
||||
|
||||
Params:
|
||||
|
||||
- `raw` (string) — JSON5 payload for the entire config
|
||||
- `baseHash` (optional) — config hash from `config.get` (required when config exists)
|
||||
- `sessionKey` (optional) — session key for the post-restart wake-up ping
|
||||
- `note` (optional) — note for the restart sentinel
|
||||
- `restartDelayMs` (optional) — delay before restart (default 2000)
|
||||
|
||||
Restart requests are coalesced while one is already pending/in-flight, and a 30-second cooldown applies between restart cycles.
|
||||
|
||||
```bash
|
||||
openclaw gateway call config.get --params '{}' # capture payload.hash
|
||||
openclaw gateway call config.apply --params '{
|
||||
"raw": "{ agents: { defaults: { workspace: \"~/.openclaw/workspace\" } } }",
|
||||
"baseHash": "<hash>",
|
||||
"sessionKey": "agent:main:whatsapp:dm:+15555550123"
|
||||
}'
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="config.patch (partial update)">
|
||||
Merges a partial update into the existing config (JSON merge patch semantics):
|
||||
|
||||
- Objects merge recursively
|
||||
- `null` deletes a key
|
||||
- Arrays replace
|
||||
|
||||
Params:
|
||||
|
||||
- `raw` (string) — JSON5 with just the keys to change
|
||||
- `baseHash` (required) — config hash from `config.get`
|
||||
- `sessionKey`, `note`, `restartDelayMs` — same as `config.apply`
|
||||
|
||||
Restart behavior matches `config.apply`: coalesced pending restarts plus a 30-second cooldown between restart cycles.
|
||||
|
||||
```bash
|
||||
openclaw gateway call config.patch --params '{
|
||||
"raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
|
||||
"baseHash": "<hash>"
|
||||
}'
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Environment variables
|
||||
|
||||
OpenClaw reads env vars from the parent process plus:
|
||||
|
||||
- `.env` from the current working directory (if present)
|
||||
- `~/.openclaw/.env` (global fallback)
|
||||
|
||||
Neither file overrides existing env vars. You can also set inline env vars in config:
|
||||
|
||||
```json5
|
||||
{
|
||||
env: {
|
||||
OPENROUTER_API_KEY: "sk-or-...",
|
||||
vars: { GROQ_API_KEY: "gsk-..." },
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
<Accordion title="Shell env import (optional)">
|
||||
If enabled and expected keys aren't set, OpenClaw runs your login shell and imports only the missing keys:
|
||||
|
||||
```json5
|
||||
{
|
||||
env: {
|
||||
shellEnv: { enabled: true, timeoutMs: 15000 },
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Env var equivalent: `OPENCLAW_LOAD_SHELL_ENV=1`
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Env var substitution in config values">
|
||||
Reference env vars in any config string value with `${VAR_NAME}`:
|
||||
|
||||
```json5
|
||||
{
|
||||
gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } },
|
||||
models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } },
|
||||
}
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Only uppercase names matched: `[A-Z_][A-Z0-9_]*`
|
||||
- Missing/empty vars throw an error at load time
|
||||
- Escape with `$${VAR}` for literal output
|
||||
- Works inside `$include` files
|
||||
- Inline substitution: `"${BASE}/v1"` → `"https://api.example.com/v1"`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Secret refs (env, file, exec)">
|
||||
For fields that support SecretRef objects, you can use:
|
||||
|
||||
```json5
|
||||
{
|
||||
models: {
|
||||
providers: {
|
||||
openai: { apiKey: { source: "env", provider: "default", id: "OPENAI_API_KEY" } },
|
||||
},
|
||||
},
|
||||
skills: {
|
||||
entries: {
|
||||
"nano-banana-pro": {
|
||||
apiKey: {
|
||||
source: "file",
|
||||
provider: "filemain",
|
||||
id: "/skills/entries/nano-banana-pro/apiKey",
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
channels: {
|
||||
googlechat: {
|
||||
serviceAccountRef: {
|
||||
source: "exec",
|
||||
provider: "vault",
|
||||
id: "channels/googlechat/serviceAccount",
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
SecretRef details (including `secrets.providers` for `env`/`file`/`exec`) are in [Secrets Management](/gateway/secrets).
|
||||
</Accordion>
|
||||
|
||||
See [Environment](/help/environment) for full precedence and sources.
|
||||
|
||||
## Full reference
|
||||
|
||||
For the complete field-by-field reference, see **[Configuration Reference](/gateway/configuration-reference)**.
|
||||
|
||||
---
|
||||
|
||||
_Related: [Configuration Examples](/gateway/configuration-examples) · [Configuration Reference](/gateway/configuration-reference) · [Doctor](/gateway/doctor)_
|
||||
123
openclaw/docs/gateway/discovery.md
Normal file
123
openclaw/docs/gateway/discovery.md
Normal file
@@ -0,0 +1,123 @@
|
||||
---
|
||||
summary: "Node discovery and transports (Bonjour, Tailscale, SSH) for finding the gateway"
|
||||
read_when:
|
||||
- Implementing or changing Bonjour discovery/advertising
|
||||
- Adjusting remote connection modes (direct vs SSH)
|
||||
- Designing node discovery + pairing for remote nodes
|
||||
title: "Discovery and Transports"
|
||||
---
|
||||
|
||||
# Discovery & transports
|
||||
|
||||
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** (`openclaw gateway`) and keep clients (mac app, iOS) as consumers.
|
||||
|
||||
## Terms
|
||||
|
||||
- **Gateway**: a single long-running gateway process that owns state (sessions, pairing, node registry) and runs channels. Most setups use one per host; isolated multi-gateway setups are possible.
|
||||
- **Gateway WS (control plane)**: the WebSocket endpoint on `127.0.0.1:18789` by default; can be bound to LAN/tailnet via `gateway.bind`.
|
||||
- **Direct WS transport**: a LAN/tailnet-facing Gateway WS endpoint (no SSH).
|
||||
- **SSH transport (fallback)**: remote control by forwarding `127.0.0.1:18789` over SSH.
|
||||
- **Legacy TCP bridge (deprecated/removed)**: older node transport (see [Bridge protocol](/gateway/bridge-protocol)); no longer advertised for discovery.
|
||||
|
||||
Protocol details:
|
||||
|
||||
- [Gateway protocol](/gateway/protocol)
|
||||
- [Bridge protocol (legacy)](/gateway/bridge-protocol)
|
||||
|
||||
## Why we keep both “direct” and SSH
|
||||
|
||||
- **Direct WS** is the best UX on the same network and within a tailnet:
|
||||
- auto-discovery on LAN via Bonjour
|
||||
- pairing tokens + ACLs owned by the gateway
|
||||
- no shell access required; protocol surface can stay tight and auditable
|
||||
- **SSH** remains the universal fallback:
|
||||
- works anywhere you have SSH access (even across unrelated networks)
|
||||
- survives multicast/mDNS issues
|
||||
- requires no new inbound ports besides SSH
|
||||
|
||||
## Discovery inputs (how clients learn where the gateway is)
|
||||
|
||||
### 1) Bonjour / mDNS (LAN only)
|
||||
|
||||
Bonjour is best-effort and does not cross networks. It is only used for “same LAN” convenience.
|
||||
|
||||
Target direction:
|
||||
|
||||
- The **gateway** advertises its WS endpoint via Bonjour.
|
||||
- Clients browse and show a “pick a gateway” list, then store the chosen endpoint.
|
||||
|
||||
Troubleshooting and beacon details: [Bonjour](/gateway/bonjour).
|
||||
|
||||
#### Service beacon details
|
||||
|
||||
- Service types:
|
||||
- `_openclaw-gw._tcp` (gateway transport beacon)
|
||||
- TXT keys (non-secret):
|
||||
- `role=gateway`
|
||||
- `lanHost=<hostname>.local`
|
||||
- `sshPort=22` (or whatever is advertised)
|
||||
- `gatewayPort=18789` (Gateway WS + HTTP)
|
||||
- `gatewayTls=1` (only when TLS is enabled)
|
||||
- `gatewayTlsSha256=<sha256>` (only when TLS is enabled and fingerprint is available)
|
||||
- `canvasPort=<port>` (canvas host port; currently the same as `gatewayPort` when the canvas host is enabled)
|
||||
- `cliPath=<path>` (optional; absolute path to a runnable `openclaw` entrypoint or binary)
|
||||
- `tailnetDns=<magicdns>` (optional hint; auto-detected when Tailscale is available)
|
||||
|
||||
Security notes:
|
||||
|
||||
- Bonjour/mDNS TXT records are **unauthenticated**. Clients must treat TXT values as UX hints only.
|
||||
- Routing (host/port) should prefer the **resolved service endpoint** (SRV + A/AAAA) over TXT-provided `lanHost`, `tailnetDns`, or `gatewayPort`.
|
||||
- TLS pinning must never allow an advertised `gatewayTlsSha256` to override a previously stored pin.
|
||||
- iOS/Android nodes should treat discovery-based direct connects as **TLS-only** and require an explicit “trust this fingerprint” confirmation before storing a first-time pin (out-of-band verification).
|
||||
|
||||
Disable/override:
|
||||
|
||||
- `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)
|
||||
|
||||
For London/Vienna style setups, Bonjour won’t help. The recommended “direct” target is:
|
||||
|
||||
- Tailscale MagicDNS name (preferred) or a stable tailnet IP.
|
||||
|
||||
If the gateway can detect it is running under Tailscale, it publishes `tailnetDns` as an optional hint for clients (including wide-area beacons).
|
||||
|
||||
### 3) Manual / SSH target
|
||||
|
||||
When there is no direct route (or direct is disabled), clients can always connect via SSH by forwarding the loopback gateway port.
|
||||
|
||||
See [Remote access](/gateway/remote).
|
||||
|
||||
## Transport selection (client policy)
|
||||
|
||||
Recommended client behavior:
|
||||
|
||||
1. If a paired direct endpoint is configured and reachable, use it.
|
||||
2. Else, if Bonjour finds a gateway on LAN, offer a one-tap “Use this gateway” choice and save it as the direct endpoint.
|
||||
3. Else, if a tailnet DNS/IP is configured, try direct.
|
||||
4. Else, fall back to SSH.
|
||||
|
||||
## Pairing + auth (direct transport)
|
||||
|
||||
The gateway is the source of truth for node/client admission.
|
||||
|
||||
- Pairing requests are created/approved/rejected in the gateway (see [Gateway pairing](/gateway/pairing)).
|
||||
- The gateway enforces:
|
||||
- auth (token / keypair)
|
||||
- scopes/ACLs (the gateway is not a raw proxy to every method)
|
||||
- rate limits
|
||||
|
||||
## Responsibilities by component
|
||||
|
||||
- **Gateway**: advertises discovery beacons, owns pairing decisions, and hosts the WS endpoint.
|
||||
- **macOS app**: helps you pick a gateway, shows pairing prompts, and uses SSH only as a fallback.
|
||||
- **iOS/Android nodes**: browse Bonjour as a convenience and connect to the paired Gateway WS.
|
||||
284
openclaw/docs/gateway/doctor.md
Normal file
284
openclaw/docs/gateway/doctor.md
Normal file
@@ -0,0 +1,284 @@
|
||||
---
|
||||
summary: "Doctor command: health checks, config migrations, and repair steps"
|
||||
read_when:
|
||||
- Adding or modifying doctor migrations
|
||||
- Introducing breaking config changes
|
||||
title: "Doctor"
|
||||
---
|
||||
|
||||
# Doctor
|
||||
|
||||
`openclaw doctor` is the repair + migration tool for OpenClaw. It fixes stale
|
||||
config/state, checks health, and provides actionable repair steps.
|
||||
|
||||
## Quick start
|
||||
|
||||
```bash
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
### Headless / automation
|
||||
|
||||
```bash
|
||||
openclaw doctor --yes
|
||||
```
|
||||
|
||||
Accept defaults without prompting (including restart/service/sandbox repair steps when applicable).
|
||||
|
||||
```bash
|
||||
openclaw doctor --repair
|
||||
```
|
||||
|
||||
Apply recommended repairs without prompting (repairs + restarts where safe).
|
||||
|
||||
```bash
|
||||
openclaw doctor --repair --force
|
||||
```
|
||||
|
||||
Apply aggressive repairs too (overwrites custom supervisor configs).
|
||||
|
||||
```bash
|
||||
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
|
||||
openclaw doctor --deep
|
||||
```
|
||||
|
||||
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 ~/.openclaw/openclaw.json
|
||||
```
|
||||
|
||||
## What it does (summary)
|
||||
|
||||
- Optional pre-flight update for git installs (interactive only).
|
||||
- UI protocol freshness check (rebuilds Control UI when the protocol schema is newer).
|
||||
- Health check + restart prompt.
|
||||
- Skills status summary (eligible/missing/blocked).
|
||||
- Config normalization for legacy values.
|
||||
- OpenCode Zen provider override warnings (`models.providers.opencode`).
|
||||
- Legacy on-disk state migration (sessions/agent dir/WhatsApp auth).
|
||||
- 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 (`~/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).
|
||||
- Channel status warnings (probed from the running gateway).
|
||||
- Supervisor config audit (launchd/systemd/schtasks) with optional repair.
|
||||
- Gateway runtime best-practice checks (Node vs Bun, version-manager paths).
|
||||
- Gateway port collision diagnostics (default `18789`).
|
||||
- Security warnings for open DM policies.
|
||||
- Gateway auth warnings when no `gateway.auth.token` is set (local mode; offers token generation).
|
||||
- systemd linger check on Linux.
|
||||
- Source install checks (pnpm workspace mismatch, missing UI assets, missing tsx binary).
|
||||
- Writes updated config + wizard metadata.
|
||||
|
||||
## Detailed behavior and rationale
|
||||
|
||||
### 0) Optional update (git installs)
|
||||
|
||||
If this is a git checkout and doctor is running interactively, it offers to
|
||||
update (fetch/rebase/build) before running doctor.
|
||||
|
||||
### 1) Config normalization
|
||||
|
||||
If the config contains legacy value shapes (for example `messages.ackReaction`
|
||||
without a channel-specific override), doctor normalizes them into the current
|
||||
schema.
|
||||
|
||||
### 2) Legacy config key migrations
|
||||
|
||||
When the config contains deprecated keys, other commands refuse to run and ask
|
||||
you to run `openclaw doctor`.
|
||||
|
||||
Doctor will:
|
||||
|
||||
- Explain which legacy keys were found.
|
||||
- Show the migration it applied.
|
||||
- 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.
|
||||
|
||||
Current migrations:
|
||||
|
||||
- `routing.allowFrom` → `channels.whatsapp.allowFrom`
|
||||
- `routing.groupChat.requireMention` → `channels.whatsapp/telegram/imessage.groups."*".requireMention`
|
||||
- `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit`
|
||||
- `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns`
|
||||
- `routing.queue` → `messages.queue`
|
||||
- `routing.bindings` → top-level `bindings`
|
||||
- `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default`
|
||||
- `routing.agentToAgent` → `tools.agentToAgent`
|
||||
- `routing.transcribeAudio` → `tools.media.audio.models`
|
||||
- `bindings[].match.accountID` → `bindings[].match.accountId`
|
||||
- For channels with named `accounts` but missing `accounts.default`, move account-scoped top-level single-account channel values into `channels.<channel>.accounts.default` when present
|
||||
- `identity` → `agents.list[].identity`
|
||||
- `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents)
|
||||
- `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks`
|
||||
→ `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks`
|
||||
- `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`
|
||||
|
||||
### 2b) OpenCode Zen provider overrides
|
||||
|
||||
If you’ve added `models.providers.opencode` (or `opencode-zen`) manually, it
|
||||
overrides the built-in OpenCode Zen catalog from `@mariozechner/pi-ai`. That can
|
||||
force every model onto a single API or zero out costs. Doctor warns so you can
|
||||
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 `~/.openclaw/sessions/` to `~/.openclaw/agents/<agentId>/sessions/`
|
||||
- Agent dir:
|
||||
- from `~/.openclaw/agent/` to `~/.openclaw/agents/<agentId>/agent/`
|
||||
- WhatsApp auth state (Baileys):
|
||||
- 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 `openclaw doctor`.
|
||||
|
||||
### 4) State integrity checks (session persistence, routing, and safety)
|
||||
|
||||
The state directory is the operational brainstem. If it vanishes, you lose
|
||||
sessions, credentials, logs, and config (unless you have backups elsewhere).
|
||||
|
||||
Doctor checks:
|
||||
|
||||
- **State dir missing**: warns about catastrophic state loss, prompts to recreate
|
||||
the directory, and reminds you that it cannot recover missing data.
|
||||
- **State dir permissions**: verifies writability; offers to repair permissions
|
||||
(and emits a `chown` hint when owner/group mismatch is detected).
|
||||
- **Session dirs missing**: `sessions/` and the session store directory are
|
||||
required to persist history and avoid `ENOENT` crashes.
|
||||
- **Transcript mismatch**: warns when recent session entries have missing
|
||||
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 `~/.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 `~/.openclaw/openclaw.json` is
|
||||
group/world readable and offers to tighten to `600`.
|
||||
|
||||
### 5) Model auth health (OAuth expiry)
|
||||
|
||||
Doctor inspects OAuth profiles in the auth store, warns when tokens are
|
||||
expiring/expired, and can refresh them when safe. If the Anthropic Claude Code
|
||||
profile is stale, it suggests running `claude setup-token` (or pasting a setup-token).
|
||||
Refresh prompts only appear when running interactively (TTY); `--non-interactive`
|
||||
skips refresh attempts.
|
||||
|
||||
Doctor also reports auth profiles that are temporarily unusable due to:
|
||||
|
||||
- short cooldowns (rate limits/timeouts/auth failures)
|
||||
- longer disables (billing/credit failures)
|
||||
|
||||
### 6) Hooks model validation
|
||||
|
||||
If `hooks.gmail.model` is set, doctor validates the model reference against the
|
||||
catalog and allowlist and warns when it won’t resolve or is disallowed.
|
||||
|
||||
### 7) Sandbox image repair
|
||||
|
||||
When sandboxing is enabled, doctor checks Docker images and offers to build or
|
||||
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 OpenClaw service using the current gateway
|
||||
port. It can also scan for extra gateway-like services and print cleanup hints.
|
||||
Profile-named OpenClaw gateway services are considered first-class and are not
|
||||
flagged as "extra."
|
||||
|
||||
### 9) Security warnings
|
||||
|
||||
Doctor emits warnings when a provider is open to DMs without an allowlist, or
|
||||
when a policy is configured in a dangerous way.
|
||||
|
||||
### 10) systemd linger (Linux)
|
||||
|
||||
If running as a systemd user service, doctor ensures lingering is enabled so the
|
||||
gateway stays alive after logout.
|
||||
|
||||
### 11) Skills status
|
||||
|
||||
Doctor prints a quick summary of eligible/missing/blocked skills for the current
|
||||
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 `openclaw doctor --generate-gateway-token` to force token
|
||||
creation in automation.
|
||||
|
||||
### 13) Gateway health check + restart
|
||||
|
||||
Doctor runs a health check and offers to restart the gateway when it looks
|
||||
unhealthy.
|
||||
|
||||
### 14) Channel status warnings
|
||||
|
||||
If the gateway is healthy, doctor runs a channel status probe and reports
|
||||
warnings with suggested fixes.
|
||||
|
||||
### 15) Supervisor config audit + repair
|
||||
|
||||
Doctor checks the installed supervisor config (launchd/systemd/schtasks) for
|
||||
missing or outdated defaults (e.g., systemd network-online dependencies and
|
||||
restart delay). When it finds a mismatch, it recommends an update and can
|
||||
rewrite the service file/task to the current defaults.
|
||||
|
||||
Notes:
|
||||
|
||||
- `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
|
||||
service is installed but not actually running. It also checks for port collisions
|
||||
on the gateway port (default `18789`) and reports likely causes (gateway already
|
||||
running, SSH tunnel).
|
||||
|
||||
### 17) Gateway runtime best practices
|
||||
|
||||
Doctor warns when the gateway service runs on Bun or a version-managed Node path
|
||||
(`nvm`, `fnm`, `volta`, `asdf`, etc.). WhatsApp + Telegram channels require Node,
|
||||
and version-manager paths can break after upgrades because the service does not
|
||||
load your shell init. Doctor offers to migrate to a system Node install when
|
||||
available (Homebrew/apt/choco).
|
||||
|
||||
### 18) Config write + wizard metadata
|
||||
|
||||
Doctor persists any config changes and stamps wizard metadata to record the
|
||||
doctor run.
|
||||
|
||||
### 19) Workspace tips (backup + memory system)
|
||||
|
||||
Doctor suggests a workspace memory system when missing and prints a backup tip
|
||||
if the workspace is not already under git.
|
||||
|
||||
See [/concepts/agent-workspace](/concepts/agent-workspace) for a full guide to
|
||||
workspace structure and git backup (recommended private GitHub or GitLab).
|
||||
34
openclaw/docs/gateway/gateway-lock.md
Normal file
34
openclaw/docs/gateway/gateway-lock.md
Normal file
@@ -0,0 +1,34 @@
|
||||
---
|
||||
summary: "Gateway singleton guard using the WebSocket listener bind"
|
||||
read_when:
|
||||
- Running or debugging the gateway process
|
||||
- Investigating single-instance enforcement
|
||||
title: "Gateway Lock"
|
||||
---
|
||||
|
||||
# Gateway lock
|
||||
|
||||
Last updated: 2025-12-11
|
||||
|
||||
## Why
|
||||
|
||||
- Ensure only one gateway instance runs per base port on the same host; additional gateways must use isolated profiles and unique ports.
|
||||
- Survive crashes/SIGKILL without leaving stale lock files.
|
||||
- Fail fast with a clear error when the control port is already occupied.
|
||||
|
||||
## Mechanism
|
||||
|
||||
- The gateway binds the WebSocket listener (default `ws://127.0.0.1:18789`) immediately on startup using an exclusive TCP listener.
|
||||
- If the bind fails with `EADDRINUSE`, startup throws `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")`.
|
||||
- The OS releases the listener automatically on any process exit, including crashes and SIGKILL—no separate lock file or cleanup step is needed.
|
||||
- On shutdown the gateway closes the WebSocket server and underlying HTTP server to free the port promptly.
|
||||
|
||||
## Error surface
|
||||
|
||||
- If another process holds the port, startup throws `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")`.
|
||||
- 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 `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.
|
||||
35
openclaw/docs/gateway/health.md
Normal file
35
openclaw/docs/gateway/health.md
Normal file
@@ -0,0 +1,35 @@
|
||||
---
|
||||
summary: "Health check steps for channel connectivity"
|
||||
read_when:
|
||||
- Diagnosing WhatsApp channel health
|
||||
title: "Health Checks"
|
||||
---
|
||||
|
||||
# Health Checks (CLI)
|
||||
|
||||
Short guide to verify channel connectivity without guessing.
|
||||
|
||||
## Quick checks
|
||||
|
||||
- `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/openclaw/openclaw-*.log` and filter for `web-heartbeat`, `web-reconnect`, `web-auto-reply`, `web-inbound`.
|
||||
|
||||
## Deep diagnostics
|
||||
|
||||
- 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 `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
|
||||
|
||||
`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.
|
||||
381
openclaw/docs/gateway/heartbeat.md
Normal file
381
openclaw/docs/gateway/heartbeat.md
Normal file
@@ -0,0 +1,381 @@
|
||||
---
|
||||
summary: "Heartbeat polling messages and notification rules"
|
||||
read_when:
|
||||
- Adjusting heartbeat cadence or messaging
|
||||
- Deciding between heartbeat and cron for scheduled tasks
|
||||
title: "Heartbeat"
|
||||
---
|
||||
|
||||
# Heartbeat (Gateway)
|
||||
|
||||
> **Heartbeat vs Cron?** See [Cron vs Heartbeat](/automation/cron-vs-heartbeat) for guidance on when to use each.
|
||||
|
||||
Heartbeat runs **periodic agent turns** in the main session so the model can
|
||||
surface anything that needs attention without spamming you.
|
||||
|
||||
Troubleshooting: [/automation/troubleshooting](/automation/troubleshooting)
|
||||
|
||||
## Quick start (beginner)
|
||||
|
||||
1. Leave heartbeats enabled (default is `30m`, or `1h` for Anthropic OAuth/setup-token) or set your own cadence.
|
||||
2. Create a tiny `HEARTBEAT.md` checklist in the agent workspace (optional but recommended).
|
||||
3. Decide where heartbeat messages should go (`target: "none"` is the default; set `target: "last"` to route to the last contact).
|
||||
4. Optional: enable heartbeat reasoning delivery for transparency.
|
||||
5. Optional: restrict heartbeats to active hours (local time).
|
||||
|
||||
Example config:
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
heartbeat: {
|
||||
every: "30m",
|
||||
target: "last", // explicit delivery to last contact (default is "none")
|
||||
directPolicy: "allow", // default: allow direct/DM targets; set "block" to suppress
|
||||
// activeHours: { start: "08:00", end: "24:00" },
|
||||
// includeReasoning: true, // optional: send separate `Reasoning:` message too
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## Defaults
|
||||
|
||||
- Interval: `30m` (or `1h` when Anthropic OAuth/setup-token is the detected auth mode). Set `agents.defaults.heartbeat.every` or per-agent `agents.list[].heartbeat.every`; use `0m` to disable.
|
||||
- Prompt body (configurable via `agents.defaults.heartbeat.prompt`):
|
||||
`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`
|
||||
- The heartbeat prompt is sent **verbatim** as the user message. The system
|
||||
prompt includes a “Heartbeat” section and the run is flagged internally.
|
||||
- Active hours (`heartbeat.activeHours`) are checked in the configured timezone.
|
||||
Outside the window, heartbeats are skipped until the next tick inside the window.
|
||||
|
||||
## What the heartbeat prompt is for
|
||||
|
||||
The default prompt is intentionally broad:
|
||||
|
||||
- **Background tasks**: “Consider outstanding tasks” nudges the agent to review
|
||||
follow-ups (inbox, calendar, reminders, queued work) and surface anything urgent.
|
||||
- **Human check-in**: “Checkup sometimes on your human during day time” nudges an
|
||||
occasional lightweight “anything you need?” message, but avoids night-time spam
|
||||
by using your configured local timezone (see [/concepts/timezone](/concepts/timezone)).
|
||||
|
||||
If you want a heartbeat to do something very specific (e.g. “check Gmail PubSub
|
||||
stats” or “verify gateway health”), set `agents.defaults.heartbeat.prompt` (or
|
||||
`agents.list[].heartbeat.prompt`) to a custom body (sent verbatim).
|
||||
|
||||
## Response contract
|
||||
|
||||
- If nothing needs attention, reply with **`HEARTBEAT_OK`**.
|
||||
- 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
|
||||
specially.
|
||||
- For alerts, **do not** include `HEARTBEAT_OK`; return only the alert text.
|
||||
|
||||
Outside heartbeats, stray `HEARTBEAT_OK` at the start/end of a message is stripped
|
||||
and logged; a message that is only `HEARTBEAT_OK` is dropped.
|
||||
|
||||
## Config
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
heartbeat: {
|
||||
every: "30m", // default: 30m (0m disables)
|
||||
model: "anthropic/claude-opus-4-6",
|
||||
includeReasoning: false, // default: false (deliver separate Reasoning: message when available)
|
||||
target: "last", // default: none | options: last | none | <channel id> (core or plugin, e.g. "bluebubbles")
|
||||
to: "+15551234567", // optional channel-specific override
|
||||
accountId: "ops-bot", // optional multi-account channel id
|
||||
prompt: "Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.",
|
||||
ackMaxChars: 300, // max chars allowed after HEARTBEAT_OK
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Scope and precedence
|
||||
|
||||
- `agents.defaults.heartbeat` sets global heartbeat behavior.
|
||||
- `agents.list[].heartbeat` merges on top; if any agent has a `heartbeat` block, **only those agents** run heartbeats.
|
||||
- `channels.defaults.heartbeat` sets visibility defaults for all channels.
|
||||
- `channels.<channel>.heartbeat` overrides channel defaults.
|
||||
- `channels.<channel>.accounts.<id>.heartbeat` (multi-account channels) overrides per-channel settings.
|
||||
|
||||
### Per-agent heartbeats
|
||||
|
||||
If any `agents.list[]` entry includes a `heartbeat` block, **only those agents**
|
||||
run heartbeats. The per-agent block merges on top of `agents.defaults.heartbeat`
|
||||
(so you can set shared defaults once and override per agent).
|
||||
|
||||
Example: two agents, only the second agent runs heartbeats.
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
heartbeat: {
|
||||
every: "30m",
|
||||
target: "last", // explicit delivery to last contact (default is "none")
|
||||
},
|
||||
},
|
||||
list: [
|
||||
{ id: "main", default: true },
|
||||
{
|
||||
id: "ops",
|
||||
heartbeat: {
|
||||
every: "1h",
|
||||
target: "whatsapp",
|
||||
to: "+15551234567",
|
||||
prompt: "Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.",
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Active hours example
|
||||
|
||||
Restrict heartbeats to business hours in a specific timezone:
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
heartbeat: {
|
||||
every: "30m",
|
||||
target: "last", // explicit delivery to last contact (default is "none")
|
||||
activeHours: {
|
||||
start: "09:00",
|
||||
end: "22:00",
|
||||
timezone: "America/New_York", // optional; uses your userTimezone if set, otherwise host tz
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Outside this window (before 9am or after 10pm Eastern), heartbeats are skipped. The next scheduled tick inside the window will run normally.
|
||||
|
||||
### 24/7 setup
|
||||
|
||||
If you want heartbeats to run all day, use one of these patterns:
|
||||
|
||||
- Omit `activeHours` entirely (no time-window restriction; this is the default behavior).
|
||||
- Set a full-day window: `activeHours: { start: "00:00", end: "24:00" }`.
|
||||
|
||||
Do not set the same `start` and `end` time (for example `08:00` to `08:00`).
|
||||
That is treated as a zero-width window, so heartbeats are always skipped.
|
||||
|
||||
### Multi account example
|
||||
|
||||
Use `accountId` to target a specific account on multi-account channels like Telegram:
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
list: [
|
||||
{
|
||||
id: "ops",
|
||||
heartbeat: {
|
||||
every: "1h",
|
||||
target: "telegram",
|
||||
to: "12345678:topic:42", // optional: route to a specific topic/thread
|
||||
accountId: "ops-bot",
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
channels: {
|
||||
telegram: {
|
||||
accounts: {
|
||||
"ops-bot": { botToken: "YOUR_TELEGRAM_BOT_TOKEN" },
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Field notes
|
||||
|
||||
- `every`: heartbeat interval (duration string; default unit = minutes).
|
||||
- `model`: optional model override for heartbeat runs (`provider/model`).
|
||||
- `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 `openclaw sessions --json` or the [sessions CLI](/cli/sessions)).
|
||||
- Session key formats: see [Sessions](/concepts/session) and [Groups](/channels/groups).
|
||||
- `target`:
|
||||
- `last`: deliver to the last used external channel.
|
||||
- explicit channel: `whatsapp` / `telegram` / `discord` / `googlechat` / `slack` / `msteams` / `signal` / `imessage`.
|
||||
- `none` (default): run the heartbeat but **do not deliver** externally.
|
||||
- `directPolicy`: controls direct/DM delivery behavior:
|
||||
- `allow` (default): allow direct/DM heartbeat delivery.
|
||||
- `block`: suppress direct/DM delivery (`reason=dm-blocked`).
|
||||
- `to`: optional recipient override (channel-specific id, e.g. E.164 for WhatsApp or a Telegram chat id). For Telegram topics/threads, use `<chatId>:topic:<messageThreadId>`.
|
||||
- `accountId`: optional account id for multi-account channels. When `target: "last"`, the account id applies to the resolved last channel if it supports accounts; otherwise it is ignored. If the account id does not match a configured account for the resolved channel, delivery is skipped.
|
||||
- `prompt`: overrides the default prompt body (not merged).
|
||||
- `ackMaxChars`: max chars allowed after `HEARTBEAT_OK` before delivery.
|
||||
- `suppressToolErrorWarnings`: when true, suppresses tool error warning payloads during heartbeat runs.
|
||||
- `activeHours`: restricts heartbeat runs to a time window. Object with `start` (HH:MM, inclusive; use `00:00` for start-of-day), `end` (HH:MM exclusive; `24:00` allowed for end-of-day), and optional `timezone`.
|
||||
- Omitted or `"user"`: uses your `agents.defaults.userTimezone` if set, otherwise falls back to the host system timezone.
|
||||
- `"local"`: always uses the host system timezone.
|
||||
- Any IANA identifier (e.g. `America/New_York`): used directly; if invalid, falls back to the `"user"` behavior above.
|
||||
- `start` and `end` must not be equal for an active window; equal values are treated as zero-width (always outside the window).
|
||||
- Outside the active window, heartbeats are skipped until the next tick inside the window.
|
||||
|
||||
## Delivery behavior
|
||||
|
||||
- Heartbeats run in the agent’s main session by default (`agent:<id>:<mainKey>`),
|
||||
or `global` when `session.scope = "global"`. Set `session` to override to a
|
||||
specific channel session (Discord/WhatsApp/etc.).
|
||||
- `session` only affects the run context; delivery is controlled by `target` and `to`.
|
||||
- To deliver to a specific channel/recipient, set `target` + `to`. With
|
||||
`target: "last"`, delivery uses the last external channel for that session.
|
||||
- Heartbeat deliveries allow direct/DM targets by default. Set `directPolicy: "block"` to suppress direct-target sends while still running the heartbeat turn.
|
||||
- If the main queue is busy, the heartbeat is skipped and retried later.
|
||||
- If `target` resolves to no external destination, the run still happens but no
|
||||
outbound message is sent.
|
||||
- Heartbeat-only replies do **not** keep the session alive; the last `updatedAt`
|
||||
is restored so idle expiry behaves normally.
|
||||
|
||||
## Visibility controls
|
||||
|
||||
By default, `HEARTBEAT_OK` acknowledgments are suppressed while alert content is
|
||||
delivered. You can adjust this per channel or per account:
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
defaults:
|
||||
heartbeat:
|
||||
showOk: false # Hide HEARTBEAT_OK (default)
|
||||
showAlerts: true # Show alert messages (default)
|
||||
useIndicator: true # Emit indicator events (default)
|
||||
telegram:
|
||||
heartbeat:
|
||||
showOk: true # Show OK acknowledgments on Telegram
|
||||
whatsapp:
|
||||
accounts:
|
||||
work:
|
||||
heartbeat:
|
||||
showAlerts: false # Suppress alert delivery for this account
|
||||
```
|
||||
|
||||
Precedence: per-account → per-channel → channel defaults → built-in defaults.
|
||||
|
||||
### What each flag does
|
||||
|
||||
- `showOk`: sends a `HEARTBEAT_OK` acknowledgment when the model returns an OK-only reply.
|
||||
- `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, OpenClaw skips the heartbeat run entirely (no model call).
|
||||
|
||||
### Per-channel vs per-account examples
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
defaults:
|
||||
heartbeat:
|
||||
showOk: false
|
||||
showAlerts: true
|
||||
useIndicator: true
|
||||
slack:
|
||||
heartbeat:
|
||||
showOk: true # all Slack accounts
|
||||
accounts:
|
||||
ops:
|
||||
heartbeat:
|
||||
showAlerts: false # suppress alerts for the ops account only
|
||||
telegram:
|
||||
heartbeat:
|
||||
showOk: true
|
||||
```
|
||||
|
||||
### Common patterns
|
||||
|
||||
| Goal | Config |
|
||||
| ---------------------------------------- | ---------------------------------------------------------------------------------------- |
|
||||
| Default behavior (silent OKs, alerts on) | _(no config needed)_ |
|
||||
| Fully silent (no messages, no indicator) | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }` |
|
||||
| Indicator-only (no messages) | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }` |
|
||||
| OKs in one channel only | `channels.telegram.heartbeat: { showOk: true }` |
|
||||
|
||||
## HEARTBEAT.md (optional)
|
||||
|
||||
If a `HEARTBEAT.md` file exists in the workspace, the default prompt tells the
|
||||
agent to read it. Think of it as your “heartbeat checklist”: small, stable, and
|
||||
safe to include every 30 minutes.
|
||||
|
||||
If `HEARTBEAT.md` exists but is effectively empty (only blank lines and markdown
|
||||
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.
|
||||
|
||||
Example `HEARTBEAT.md`:
|
||||
|
||||
```md
|
||||
# Heartbeat checklist
|
||||
|
||||
- Quick scan: anything urgent in inboxes?
|
||||
- If it’s daytime, do a lightweight check-in if nothing else is pending.
|
||||
- If a task is blocked, write down _what is missing_ and ask Peter next time.
|
||||
```
|
||||
|
||||
### Can the agent update HEARTBEAT.md?
|
||||
|
||||
Yes — if you ask it to.
|
||||
|
||||
`HEARTBEAT.md` is just a normal file in the agent workspace, so you can tell the
|
||||
agent (in a normal chat) something like:
|
||||
|
||||
- “Update `HEARTBEAT.md` to add a daily calendar check.”
|
||||
- “Rewrite `HEARTBEAT.md` so it’s shorter and focused on inbox follow-ups.”
|
||||
|
||||
If you want this to happen proactively, you can also include an explicit line in
|
||||
your heartbeat prompt like: “If the checklist becomes stale, update HEARTBEAT.md
|
||||
with a better one.”
|
||||
|
||||
Safety note: don’t put secrets (API keys, phone numbers, private tokens) into
|
||||
`HEARTBEAT.md` — it becomes part of the prompt context.
|
||||
|
||||
## Manual wake (on-demand)
|
||||
|
||||
You can enqueue a system event and trigger an immediate heartbeat with:
|
||||
|
||||
```bash
|
||||
openclaw system event --text "Check for urgent follow-ups" --mode now
|
||||
```
|
||||
|
||||
If multiple agents have `heartbeat` configured, a manual wake runs each of those
|
||||
agent heartbeats immediately.
|
||||
|
||||
Use `--mode next-heartbeat` to wait for the next scheduled tick.
|
||||
|
||||
## Reasoning delivery (optional)
|
||||
|
||||
By default, heartbeats deliver only the final “answer” payload.
|
||||
|
||||
If you want transparency, enable:
|
||||
|
||||
- `agents.defaults.heartbeat.includeReasoning: true`
|
||||
|
||||
When enabled, heartbeats will also deliver a separate message prefixed
|
||||
`Reasoning:` (same shape as `/reasoning on`). This can be useful when the agent
|
||||
is managing multiple sessions/codexes and you want to see why it decided to ping
|
||||
you — but it can also leak more internal detail than you want. Prefer keeping it
|
||||
off in group chats.
|
||||
|
||||
## Cost awareness
|
||||
|
||||
Heartbeats run full agent turns. Shorter intervals burn more tokens. Keep
|
||||
`HEARTBEAT.md` small and consider a cheaper `model` or `target: "none"` if you
|
||||
only want internal state updates.
|
||||
261
openclaw/docs/gateway/index.md
Normal file
261
openclaw/docs/gateway/index.md
Normal file
@@ -0,0 +1,261 @@
|
||||
---
|
||||
summary: "Runbook for the Gateway service, lifecycle, and operations"
|
||||
read_when:
|
||||
- Running or debugging the gateway process
|
||||
title: "Gateway Runbook"
|
||||
---
|
||||
|
||||
# Gateway runbook
|
||||
|
||||
Use this page for day-1 startup and day-2 operations of the Gateway service.
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Deep troubleshooting" icon="siren" href="/gateway/troubleshooting">
|
||||
Symptom-first diagnostics with exact command ladders and log signatures.
|
||||
</Card>
|
||||
<Card title="Configuration" icon="sliders" href="/gateway/configuration">
|
||||
Task-oriented setup guide + full configuration reference.
|
||||
</Card>
|
||||
<Card title="Secrets management" icon="key-round" href="/gateway/secrets">
|
||||
SecretRef contract, runtime snapshot behavior, and migrate/reload operations.
|
||||
</Card>
|
||||
<Card title="Secrets plan contract" icon="shield-check" href="/gateway/secrets-plan-contract">
|
||||
Exact `secrets apply` target/path rules and ref-only auth-profile behavior.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## 5-minute local startup
|
||||
|
||||
<Steps>
|
||||
<Step title="Start the Gateway">
|
||||
|
||||
```bash
|
||||
openclaw gateway --port 18789
|
||||
# debug/trace mirrored to stdio
|
||||
openclaw gateway --port 18789 --verbose
|
||||
# force-kill listener on selected port, then start
|
||||
openclaw gateway --force
|
||||
```
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Verify service health">
|
||||
|
||||
```bash
|
||||
openclaw gateway status
|
||||
openclaw status
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
Healthy baseline: `Runtime: running` and `RPC probe: ok`.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Validate channel readiness">
|
||||
|
||||
```bash
|
||||
openclaw channels status --probe
|
||||
```
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
Gateway config reload watches the active config file path (resolved from profile/state defaults, or `OPENCLAW_CONFIG_PATH` when set).
|
||||
Default mode is `gateway.reload.mode="hybrid"`.
|
||||
</Note>
|
||||
|
||||
## Runtime model
|
||||
|
||||
- One always-on process for routing, control plane, and channel connections.
|
||||
- Single multiplexed port for:
|
||||
- WebSocket control/RPC
|
||||
- HTTP APIs (OpenAI-compatible, Responses, tools invoke)
|
||||
- Control UI and hooks
|
||||
- Default bind mode: `loopback`.
|
||||
- Auth is required by default (`gateway.auth.token` / `gateway.auth.password`, or `OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`).
|
||||
|
||||
### Port and bind precedence
|
||||
|
||||
| Setting | Resolution order |
|
||||
| ------------ | ------------------------------------------------------------- |
|
||||
| Gateway port | `--port` → `OPENCLAW_GATEWAY_PORT` → `gateway.port` → `18789` |
|
||||
| Bind mode | CLI/override → `gateway.bind` → `loopback` |
|
||||
|
||||
### Hot reload modes
|
||||
|
||||
| `gateway.reload.mode` | Behavior |
|
||||
| --------------------- | ------------------------------------------ |
|
||||
| `off` | No config reload |
|
||||
| `hot` | Apply only hot-safe changes |
|
||||
| `restart` | Restart on reload-required changes |
|
||||
| `hybrid` (default) | Hot-apply when safe, restart when required |
|
||||
|
||||
## Operator command set
|
||||
|
||||
```bash
|
||||
openclaw gateway status
|
||||
openclaw gateway status --deep
|
||||
openclaw gateway status --json
|
||||
openclaw gateway install
|
||||
openclaw gateway restart
|
||||
openclaw gateway stop
|
||||
openclaw secrets reload
|
||||
openclaw logs --follow
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
## Remote access
|
||||
|
||||
Preferred: Tailscale/VPN.
|
||||
Fallback: SSH tunnel.
|
||||
|
||||
```bash
|
||||
ssh -N -L 18789:127.0.0.1:18789 user@host
|
||||
```
|
||||
|
||||
Then connect clients to `ws://127.0.0.1:18789` locally.
|
||||
|
||||
<Warning>
|
||||
If gateway auth is configured, clients still must send auth (`token`/`password`) even over SSH tunnels.
|
||||
</Warning>
|
||||
|
||||
See: [Remote Gateway](/gateway/remote), [Authentication](/gateway/authentication), [Tailscale](/gateway/tailscale).
|
||||
|
||||
## Supervision and service lifecycle
|
||||
|
||||
Use supervised runs for production-like reliability.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="macOS (launchd)">
|
||||
|
||||
```bash
|
||||
openclaw gateway install
|
||||
openclaw gateway status
|
||||
openclaw gateway restart
|
||||
openclaw gateway stop
|
||||
```
|
||||
|
||||
LaunchAgent labels are `ai.openclaw.gateway` (default) or `ai.openclaw.<profile>` (named profile). `openclaw doctor` audits and repairs service config drift.
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Linux (systemd user)">
|
||||
|
||||
```bash
|
||||
openclaw gateway install
|
||||
systemctl --user enable --now openclaw-gateway[-<profile>].service
|
||||
openclaw gateway status
|
||||
```
|
||||
|
||||
For persistence after logout, enable lingering:
|
||||
|
||||
```bash
|
||||
sudo loginctl enable-linger <user>
|
||||
```
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Linux (system service)">
|
||||
|
||||
Use a system unit for multi-user/always-on hosts.
|
||||
|
||||
```bash
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable --now openclaw-gateway[-<profile>].service
|
||||
```
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Multiple gateways on one host
|
||||
|
||||
Most setups should run **one** Gateway.
|
||||
Use multiple only for strict isolation/redundancy (for example a rescue profile).
|
||||
|
||||
Checklist per instance:
|
||||
|
||||
- Unique `gateway.port`
|
||||
- Unique `OPENCLAW_CONFIG_PATH`
|
||||
- Unique `OPENCLAW_STATE_DIR`
|
||||
- Unique `agents.defaults.workspace`
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
See: [Multiple gateways](/gateway/multiple-gateways).
|
||||
|
||||
### Dev profile quick path
|
||||
|
||||
```bash
|
||||
openclaw --dev setup
|
||||
openclaw --dev gateway --allow-unconfigured
|
||||
openclaw --dev status
|
||||
```
|
||||
|
||||
Defaults include isolated state/config and base gateway port `19001`.
|
||||
|
||||
## Protocol quick reference (operator view)
|
||||
|
||||
- First client frame must be `connect`.
|
||||
- Gateway returns `hello-ok` snapshot (`presence`, `health`, `stateVersion`, `uptimeMs`, limits/policy).
|
||||
- Requests: `req(method, params)` → `res(ok/payload|error)`.
|
||||
- Common events: `connect.challenge`, `agent`, `chat`, `presence`, `tick`, `health`, `heartbeat`, `shutdown`.
|
||||
|
||||
Agent runs are two-stage:
|
||||
|
||||
1. Immediate accepted ack (`status:"accepted"`)
|
||||
2. Final completion response (`status:"ok"|"error"`), with streamed `agent` events in between.
|
||||
|
||||
See full protocol docs: [Gateway Protocol](/gateway/protocol).
|
||||
|
||||
## Operational checks
|
||||
|
||||
### Liveness
|
||||
|
||||
- Open WS and send `connect`.
|
||||
- Expect `hello-ok` response with snapshot.
|
||||
|
||||
### Readiness
|
||||
|
||||
```bash
|
||||
openclaw gateway status
|
||||
openclaw channels status --probe
|
||||
openclaw health
|
||||
```
|
||||
|
||||
### Gap recovery
|
||||
|
||||
Events are not replayed. On sequence gaps, refresh state (`health`, `system-presence`) before continuing.
|
||||
|
||||
## Common failure signatures
|
||||
|
||||
| Signature | Likely issue |
|
||||
| -------------------------------------------------------------- | ---------------------------------------- |
|
||||
| `refusing to bind gateway ... without auth` | Non-loopback bind without token/password |
|
||||
| `another gateway instance is already listening` / `EADDRINUSE` | Port conflict |
|
||||
| `Gateway start blocked: set gateway.mode=local` | Config set to remote mode |
|
||||
| `unauthorized` during connect | Auth mismatch between client and gateway |
|
||||
|
||||
For full diagnosis ladders, use [Gateway Troubleshooting](/gateway/troubleshooting).
|
||||
|
||||
## Safety guarantees
|
||||
|
||||
- Gateway protocol clients fail fast when Gateway is unavailable (no implicit direct-channel fallback).
|
||||
- Invalid/non-connect first frames are rejected and closed.
|
||||
- Graceful shutdown emits `shutdown` event before socket close.
|
||||
|
||||
---
|
||||
|
||||
Related:
|
||||
|
||||
- [Troubleshooting](/gateway/troubleshooting)
|
||||
- [Background Process](/gateway/background-process)
|
||||
- [Configuration](/gateway/configuration)
|
||||
- [Health](/gateway/health)
|
||||
- [Doctor](/gateway/doctor)
|
||||
- [Authentication](/gateway/authentication)
|
||||
150
openclaw/docs/gateway/local-models.md
Normal file
150
openclaw/docs/gateway/local-models.md
Normal file
@@ -0,0 +1,150 @@
|
||||
---
|
||||
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
|
||||
- You need the safest local model guidance
|
||||
title: "Local Models"
|
||||
---
|
||||
|
||||
# Local models
|
||||
|
||||
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)
|
||||
|
||||
Best current local stack. Load MiniMax M2.1 in LM Studio, enable the local server (default `http://127.0.0.1:1234`), and use Responses API to keep reasoning separate from final text.
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
model: { primary: "lmstudio/minimax-m2.1-gs32" },
|
||||
models: {
|
||||
"anthropic/claude-opus-4-6": { alias: "Opus" },
|
||||
"lmstudio/minimax-m2.1-gs32": { alias: "Minimax" },
|
||||
},
|
||||
},
|
||||
},
|
||||
models: {
|
||||
mode: "merge",
|
||||
providers: {
|
||||
lmstudio: {
|
||||
baseUrl: "http://127.0.0.1:1234/v1",
|
||||
apiKey: "lmstudio",
|
||||
api: "openai-responses",
|
||||
models: [
|
||||
{
|
||||
id: "minimax-m2.1-gs32",
|
||||
name: "MiniMax M2.1 GS32",
|
||||
reasoning: false,
|
||||
input: ["text"],
|
||||
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
|
||||
contextWindow: 196608,
|
||||
maxTokens: 8192,
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
**Setup checklist**
|
||||
|
||||
- Install LM Studio: [https://lmstudio.ai](https://lmstudio.ai)
|
||||
- In LM Studio, download the **largest MiniMax M2.1 build available** (avoid “small”/heavily quantized variants), start the server, confirm `http://127.0.0.1:1234/v1/models` lists it.
|
||||
- Keep the model loaded; cold-load adds startup latency.
|
||||
- Adjust `contextWindow`/`maxTokens` if your LM Studio build differs.
|
||||
- For WhatsApp, stick to Responses API so only final text is sent.
|
||||
|
||||
Keep hosted models configured even when running local; use `models.mode: "merge"` so fallbacks stay available.
|
||||
|
||||
### Hybrid config: hosted primary, local fallback
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
model: {
|
||||
primary: "anthropic/claude-sonnet-4-5",
|
||||
fallbacks: ["lmstudio/minimax-m2.1-gs32", "anthropic/claude-opus-4-6"],
|
||||
},
|
||||
models: {
|
||||
"anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
|
||||
"lmstudio/minimax-m2.1-gs32": { alias: "MiniMax Local" },
|
||||
"anthropic/claude-opus-4-6": { alias: "Opus" },
|
||||
},
|
||||
},
|
||||
},
|
||||
models: {
|
||||
mode: "merge",
|
||||
providers: {
|
||||
lmstudio: {
|
||||
baseUrl: "http://127.0.0.1:1234/v1",
|
||||
apiKey: "lmstudio",
|
||||
api: "openai-responses",
|
||||
models: [
|
||||
{
|
||||
id: "minimax-m2.1-gs32",
|
||||
name: "MiniMax M2.1 GS32",
|
||||
reasoning: false,
|
||||
input: ["text"],
|
||||
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
|
||||
contextWindow: 196608,
|
||||
maxTokens: 8192,
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Local-first with hosted safety net
|
||||
|
||||
Swap the primary and fallback order; keep the same providers block and `models.mode: "merge"` so you can fall back to Sonnet or Opus when the local box is down.
|
||||
|
||||
### Regional hosting / data routing
|
||||
|
||||
- Hosted MiniMax/Kimi/GLM variants also exist on OpenRouter with region-pinned endpoints (e.g., US-hosted). Pick the regional variant there to keep traffic in your chosen jurisdiction while still using `models.mode: "merge"` for Anthropic/OpenAI fallbacks.
|
||||
- Local-only remains the strongest privacy path; hosted regional routing is the middle ground when you need provider features but want control over data flow.
|
||||
|
||||
## Other OpenAI-compatible local proxies
|
||||
|
||||
vLLM, LiteLLM, OAI-proxy, or custom gateways work if they expose an OpenAI-style `/v1` endpoint. Replace the provider block above with your endpoint and model ID:
|
||||
|
||||
```json5
|
||||
{
|
||||
models: {
|
||||
mode: "merge",
|
||||
providers: {
|
||||
local: {
|
||||
baseUrl: "http://127.0.0.1:8000/v1",
|
||||
apiKey: "sk-local",
|
||||
api: "openai-responses",
|
||||
models: [
|
||||
{
|
||||
id: "my-local-model",
|
||||
name: "Local Model",
|
||||
reasoning: false,
|
||||
input: ["text"],
|
||||
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
|
||||
contextWindow: 120000,
|
||||
maxTokens: 8192,
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Keep `models.mode: "merge"` so hosted models stay available as fallbacks.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- Gateway can reach the proxy? `curl http://127.0.0.1:1234/v1/models`.
|
||||
- LM Studio model unloaded? Reload; cold start is a common “hanging” cause.
|
||||
- Context errors? Lower `contextWindow` or raise your server limit.
|
||||
- Safety: local models skip provider-side filters; keep agents narrow and compaction on to limit prompt injection blast radius.
|
||||
113
openclaw/docs/gateway/logging.md
Normal file
113
openclaw/docs/gateway/logging.md
Normal file
@@ -0,0 +1,113 @@
|
||||
---
|
||||
summary: "Logging surfaces, file logs, WS log styles, and console formatting"
|
||||
read_when:
|
||||
- Changing logging output or formats
|
||||
- Debugging CLI or gateway output
|
||||
title: "Logging"
|
||||
---
|
||||
|
||||
# Logging
|
||||
|
||||
For a user-facing overview (CLI + Control UI + config), see [/logging](/logging).
|
||||
|
||||
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/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 `~/.openclaw/openclaw.json`:
|
||||
- `logging.file`
|
||||
- `logging.level`
|
||||
|
||||
The file format is one JSON object per line.
|
||||
|
||||
The Control UI Logs tab tails this file via the gateway (`logs.tail`).
|
||||
CLI can do the same:
|
||||
|
||||
```bash
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
**Verbose vs. log levels**
|
||||
|
||||
- **File logs** are controlled exclusively by `logging.level`.
|
||||
- `--verbose` only affects **console verbosity** (and WS log style); it does **not**
|
||||
raise the file log level.
|
||||
- To capture verbose-only details in file logs, set `logging.level` to `debug` or
|
||||
`trace`.
|
||||
|
||||
## Console capture
|
||||
|
||||
The CLI captures `console.log/info/warn/error/debug/trace` and writes them to file logs,
|
||||
while still printing to stdout/stderr.
|
||||
|
||||
You can tune console verbosity independently via:
|
||||
|
||||
- `logging.consoleLevel` (default `info`)
|
||||
- `logging.consoleStyle` (`pretty` | `compact` | `json`)
|
||||
|
||||
## Tool summary redaction
|
||||
|
||||
Verbose tool summaries (e.g. `🛠️ Exec: ...`) can mask sensitive tokens before they hit the
|
||||
console stream. This is **tools-only** and does not alter file logs.
|
||||
|
||||
- `logging.redactSensitive`: `off` | `tools` (default: `tools`)
|
||||
- `logging.redactPatterns`: array of regex strings (overrides defaults)
|
||||
- Use raw regex strings (auto `gi`), or `/pattern/flags` if you need custom flags.
|
||||
- Matches are masked by keeping the first 6 + last 4 chars (length >= 18), otherwise `***`.
|
||||
- Defaults cover common key assignments, CLI flags, JSON fields, bearer headers, PEM blocks, and popular token prefixes.
|
||||
|
||||
## Gateway WebSocket logs
|
||||
|
||||
The gateway prints WebSocket protocol logs in two modes:
|
||||
|
||||
- **Normal mode (no `--verbose`)**: only “interesting” RPC results are printed:
|
||||
- errors (`ok=false`)
|
||||
- slow calls (default threshold: `>= 50ms`)
|
||||
- parse errors
|
||||
- **Verbose mode (`--verbose`)**: prints all WS request/response traffic.
|
||||
|
||||
### WS log style
|
||||
|
||||
`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
|
||||
- `--ws-log full`: full per-frame output when verbose
|
||||
- `--compact`: alias for `--ws-log compact`
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
# optimized (only errors/slow)
|
||||
openclaw gateway
|
||||
|
||||
# show all WS traffic (paired)
|
||||
openclaw gateway --verbose --ws-log compact
|
||||
|
||||
# show all WS traffic (full meta)
|
||||
openclaw gateway --verbose --ws-log full
|
||||
```
|
||||
|
||||
## Console formatting (subsystem logging)
|
||||
|
||||
The console formatter is **TTY-aware** and prints consistent, prefixed lines.
|
||||
Subsystem loggers keep output grouped and scannable.
|
||||
|
||||
Behavior:
|
||||
|
||||
- **Subsystem prefixes** on every line (e.g. `[gateway]`, `[canvas]`, `[tailscale]`)
|
||||
- **Subsystem colors** (stable per subsystem) plus level coloring
|
||||
- **Color when output is a TTY or the environment looks like a rich terminal** (`TERM`/`COLORTERM`/`TERM_PROGRAM`), respects `NO_COLOR`
|
||||
- **Shortened subsystem prefixes**: drops leading `gateway/` + `channels/`, keeps last 2 segments (e.g. `whatsapp/outbound`)
|
||||
- **Sub-loggers by subsystem** (auto prefix + structured field `{ subsystem }`)
|
||||
- **`logRaw()`** for QR/UX output (no prefix, no formatting)
|
||||
- **Console styles** (e.g. `pretty | compact | json`)
|
||||
- **Console log level** separate from file log level (file keeps full detail when `logging.level` is set to `debug`/`trace`)
|
||||
- **WhatsApp message bodies** are logged at `debug` (use `--verbose` to see them)
|
||||
|
||||
This keeps existing file logs stable while making interactive output scannable.
|
||||
112
openclaw/docs/gateway/multiple-gateways.md
Normal file
112
openclaw/docs/gateway/multiple-gateways.md
Normal file
@@ -0,0 +1,112 @@
|
||||
---
|
||||
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
|
||||
title: "Multiple Gateways"
|
||||
---
|
||||
|
||||
# Multiple Gateways (same host)
|
||||
|
||||
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)
|
||||
|
||||
- `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
|
||||
|
||||
If these are shared, you will hit config races and port conflicts.
|
||||
|
||||
## Recommended: profiles (`--profile`)
|
||||
|
||||
Profiles auto-scope `OPENCLAW_STATE_DIR` + `OPENCLAW_CONFIG_PATH` and suffix service names.
|
||||
|
||||
```bash
|
||||
# main
|
||||
openclaw --profile main setup
|
||||
openclaw --profile main gateway --port 18789
|
||||
|
||||
# rescue
|
||||
openclaw --profile rescue setup
|
||||
openclaw --profile rescue gateway --port 19001
|
||||
```
|
||||
|
||||
Per-profile services:
|
||||
|
||||
```bash
|
||||
openclaw --profile main gateway install
|
||||
openclaw --profile rescue gateway install
|
||||
```
|
||||
|
||||
## Rescue-bot guide
|
||||
|
||||
Run a second Gateway on the same host with its own:
|
||||
|
||||
- profile/config
|
||||
- state dir
|
||||
- workspace
|
||||
- base port (plus derived ports)
|
||||
|
||||
This keeps the rescue bot isolated from the main bot so it can debug or apply config changes if the primary bot is down.
|
||||
|
||||
Port spacing: leave at least 20 ports between base ports so the derived browser/canvas/CDP ports never collide.
|
||||
|
||||
### How to install (rescue bot)
|
||||
|
||||
```bash
|
||||
# Main bot (existing or fresh, without --profile param)
|
||||
# Runs on port 18789 + Chrome CDC/Canvas/... Ports
|
||||
openclaw onboard
|
||||
openclaw gateway install
|
||||
|
||||
# Rescue bot (isolated profile + ports)
|
||||
openclaw --profile rescue onboard
|
||||
# Notes:
|
||||
# - workspace name will be postfixed with -rescue per default
|
||||
# - Port should be at least 18789 + 20 Ports,
|
||||
# better choose completely different base port, like 19789,
|
||||
# - rest of the onboarding is the same as normal
|
||||
|
||||
# To install the service (if not happened automatically during onboarding)
|
||||
openclaw --profile rescue gateway install
|
||||
```
|
||||
|
||||
## Port mapping (derived)
|
||||
|
||||
Base port = `gateway.port` (or `OPENCLAW_GATEWAY_PORT` / `--port`).
|
||||
|
||||
- browser control service port = base + 2 (loopback only)
|
||||
- canvas host is served on the Gateway HTTP server (same port as `gateway.port`)
|
||||
- Browser profile CDP ports auto-allocate from `browser.controlPort + 9 .. + 108`
|
||||
|
||||
If you override any of these in config or env, you must keep them unique per instance.
|
||||
|
||||
## Browser/CDP notes (common footgun)
|
||||
|
||||
- Do **not** pin `browser.cdpUrl` to the same values on multiple instances.
|
||||
- Each instance needs its own browser control port and CDP range (derived from its gateway port).
|
||||
- If you need explicit CDP ports, set `browser.profiles.<name>.cdpPort` per instance.
|
||||
- Remote Chrome: use `browser.profiles.<name>.cdpUrl` (per profile, per instance).
|
||||
|
||||
## Manual env example
|
||||
|
||||
```bash
|
||||
OPENCLAW_CONFIG_PATH=~/.openclaw/main.json \
|
||||
OPENCLAW_STATE_DIR=~/.openclaw-main \
|
||||
openclaw gateway --port 18789
|
||||
|
||||
OPENCLAW_CONFIG_PATH=~/.openclaw/rescue.json \
|
||||
OPENCLAW_STATE_DIR=~/.openclaw-rescue \
|
||||
openclaw gateway --port 19001
|
||||
```
|
||||
|
||||
## Quick checks
|
||||
|
||||
```bash
|
||||
openclaw --profile main status
|
||||
openclaw --profile rescue status
|
||||
openclaw --profile rescue browser status
|
||||
```
|
||||
20
openclaw/docs/gateway/network-model.md
Normal file
20
openclaw/docs/gateway/network-model.md
Normal file
@@ -0,0 +1,20 @@
|
||||
---
|
||||
summary: "How the Gateway, nodes, and canvas host connect."
|
||||
read_when:
|
||||
- You want a concise view of the Gateway networking model
|
||||
title: "Network model"
|
||||
---
|
||||
|
||||
Most operations flow through the Gateway (`openclaw gateway`), a single long-running
|
||||
process that owns channel connections and the WebSocket control plane.
|
||||
|
||||
## Core rules
|
||||
|
||||
- One Gateway per host is recommended. It is the only process allowed to own the WhatsApp Web session. For rescue bots or strict isolation, run multiple gateways with isolated profiles and ports. See [Multiple gateways](/gateway/multiple-gateways).
|
||||
- Loopback first: the Gateway WS defaults to `ws://127.0.0.1:18789`. The wizard generates a gateway token by default, even for loopback. For tailnet access, run `openclaw gateway --bind tailnet --token ...` because tokens are required for non-loopback binds.
|
||||
- Nodes connect to the Gateway WS over LAN, tailnet, or SSH as needed. The legacy TCP bridge is deprecated.
|
||||
- Canvas host is served by the Gateway HTTP server on the **same port** as the Gateway (default `18789`):
|
||||
- `/__openclaw__/canvas/`
|
||||
- `/__openclaw__/a2ui/`
|
||||
When `gateway.auth` is configured and the Gateway binds beyond loopback, these routes are protected by Gateway auth. Node clients use node-scoped capability URLs tied to their active WS session. See [Gateway configuration](/gateway/configuration) (`canvasHost`, `gateway`).
|
||||
- Remote use is typically SSH tunnel or tailnet VPN. See [Remote access](/gateway/remote) and [Discovery](/gateway/discovery).
|
||||
119
openclaw/docs/gateway/openai-http-api.md
Normal file
119
openclaw/docs/gateway/openai-http-api.md
Normal file
@@ -0,0 +1,119 @@
|
||||
---
|
||||
summary: "Expose an OpenAI-compatible /v1/chat/completions HTTP endpoint from the Gateway"
|
||||
read_when:
|
||||
- Integrating tools that expect OpenAI Chat Completions
|
||||
title: "OpenAI Chat Completions"
|
||||
---
|
||||
|
||||
# OpenAI Chat Completions (HTTP)
|
||||
|
||||
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 `openclaw agent`), so routing/permissions/config match your Gateway.
|
||||
|
||||
## Authentication
|
||||
|
||||
Uses the Gateway auth configuration. Send a bearer token:
|
||||
|
||||
- `Authorization: Bearer <token>`
|
||||
|
||||
Notes:
|
||||
|
||||
- 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`).
|
||||
- If `gateway.auth.rateLimit` is configured and too many auth failures occur, the endpoint returns `429` with `Retry-After`.
|
||||
|
||||
## Choosing an agent
|
||||
|
||||
No custom headers required: encode the agent id in the OpenAI `model` field:
|
||||
|
||||
- `model: "openclaw:<agentId>"` (example: `"openclaw:main"`, `"openclaw:beta"`)
|
||||
- `model: "agent:<agentId>"` (alias)
|
||||
|
||||
Or target a specific OpenClaw agent by header:
|
||||
|
||||
- `x-openclaw-agent-id: <agentId>` (default: `main`)
|
||||
|
||||
Advanced:
|
||||
|
||||
- `x-openclaw-session-key: <sessionKey>` to fully control session routing.
|
||||
|
||||
## Enabling the endpoint
|
||||
|
||||
Set `gateway.http.endpoints.chatCompletions.enabled` to `true`:
|
||||
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
http: {
|
||||
endpoints: {
|
||||
chatCompletions: { enabled: true },
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## Disabling the endpoint
|
||||
|
||||
Set `gateway.http.endpoints.chatCompletions.enabled` to `false`:
|
||||
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
http: {
|
||||
endpoints: {
|
||||
chatCompletions: { enabled: false },
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## Session behavior
|
||||
|
||||
By default the endpoint is **stateless per request** (a new session key is generated each call).
|
||||
|
||||
If the request includes an OpenAI `user` string, the Gateway derives a stable session key from it, so repeated calls can share an agent session.
|
||||
|
||||
## Streaming (SSE)
|
||||
|
||||
Set `stream: true` to receive Server-Sent Events (SSE):
|
||||
|
||||
- `Content-Type: text/event-stream`
|
||||
- Each event line is `data: <json>`
|
||||
- Stream ends with `data: [DONE]`
|
||||
|
||||
## Examples
|
||||
|
||||
Non-streaming:
|
||||
|
||||
```bash
|
||||
curl -sS http://127.0.0.1:18789/v1/chat/completions \
|
||||
-H 'Authorization: Bearer YOUR_TOKEN' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'x-openclaw-agent-id: main' \
|
||||
-d '{
|
||||
"model": "openclaw",
|
||||
"messages": [{"role":"user","content":"hi"}]
|
||||
}'
|
||||
```
|
||||
|
||||
Streaming:
|
||||
|
||||
```bash
|
||||
curl -N http://127.0.0.1:18789/v1/chat/completions \
|
||||
-H 'Authorization: Bearer YOUR_TOKEN' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'x-openclaw-agent-id: main' \
|
||||
-d '{
|
||||
"model": "openclaw",
|
||||
"stream": true,
|
||||
"messages": [{"role":"user","content":"hi"}]
|
||||
}'
|
||||
```
|
||||
333
openclaw/docs/gateway/openresponses-http-api.md
Normal file
333
openclaw/docs/gateway/openresponses-http-api.md
Normal file
@@ -0,0 +1,333 @@
|
||||
---
|
||||
summary: "Expose an OpenResponses-compatible /v1/responses HTTP endpoint from the Gateway"
|
||||
read_when:
|
||||
- Integrating clients that speak the OpenResponses API
|
||||
- You want item-based inputs, client tool calls, or SSE events
|
||||
title: "OpenResponses API"
|
||||
---
|
||||
|
||||
# OpenResponses API (HTTP)
|
||||
|
||||
OpenClaw’s Gateway can serve an OpenResponses-compatible `POST /v1/responses` endpoint.
|
||||
|
||||
This endpoint is **disabled by default**. Enable it in config first.
|
||||
|
||||
- `POST /v1/responses`
|
||||
- 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
|
||||
`openclaw agent`), so routing/permissions/config match your Gateway.
|
||||
|
||||
## Authentication
|
||||
|
||||
Uses the Gateway auth configuration. Send a bearer token:
|
||||
|
||||
- `Authorization: Bearer <token>`
|
||||
|
||||
Notes:
|
||||
|
||||
- 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`).
|
||||
- If `gateway.auth.rateLimit` is configured and too many auth failures occur, the endpoint returns `429` with `Retry-After`.
|
||||
|
||||
## Choosing an agent
|
||||
|
||||
No custom headers required: encode the agent id in the OpenResponses `model` field:
|
||||
|
||||
- `model: "openclaw:<agentId>"` (example: `"openclaw:main"`, `"openclaw:beta"`)
|
||||
- `model: "agent:<agentId>"` (alias)
|
||||
|
||||
Or target a specific OpenClaw agent by header:
|
||||
|
||||
- `x-openclaw-agent-id: <agentId>` (default: `main`)
|
||||
|
||||
Advanced:
|
||||
|
||||
- `x-openclaw-session-key: <sessionKey>` to fully control session routing.
|
||||
|
||||
## Enabling the endpoint
|
||||
|
||||
Set `gateway.http.endpoints.responses.enabled` to `true`:
|
||||
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
http: {
|
||||
endpoints: {
|
||||
responses: { enabled: true },
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## Disabling the endpoint
|
||||
|
||||
Set `gateway.http.endpoints.responses.enabled` to `false`:
|
||||
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
http: {
|
||||
endpoints: {
|
||||
responses: { enabled: false },
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## Session behavior
|
||||
|
||||
By default the endpoint is **stateless per request** (a new session key is generated each call).
|
||||
|
||||
If the request includes an OpenResponses `user` string, the Gateway derives a stable session key
|
||||
from it, so repeated calls can share an agent session.
|
||||
|
||||
## Request shape (supported)
|
||||
|
||||
The request follows the OpenResponses API with item-based input. Current support:
|
||||
|
||||
- `input`: string or array of item objects.
|
||||
- `instructions`: merged into the system prompt.
|
||||
- `tools`: client tool definitions (function tools).
|
||||
- `tool_choice`: filter or require client tools.
|
||||
- `stream`: enables SSE streaming.
|
||||
- `max_output_tokens`: best-effort output limit (provider dependent).
|
||||
- `user`: stable session routing.
|
||||
|
||||
Accepted but **currently ignored**:
|
||||
|
||||
- `max_tool_calls`
|
||||
- `reasoning`
|
||||
- `metadata`
|
||||
- `store`
|
||||
- `previous_response_id`
|
||||
- `truncation`
|
||||
|
||||
## Items (input)
|
||||
|
||||
### `message`
|
||||
|
||||
Roles: `system`, `developer`, `user`, `assistant`.
|
||||
|
||||
- `system` and `developer` are appended to the system prompt.
|
||||
- The most recent `user` or `function_call_output` item becomes the “current message.”
|
||||
- Earlier user/assistant messages are included as history for context.
|
||||
|
||||
### `function_call_output` (turn-based tools)
|
||||
|
||||
Send tool results back to the model:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "function_call_output",
|
||||
"call_id": "call_123",
|
||||
"output": "{\"temperature\": \"72F\"}"
|
||||
}
|
||||
```
|
||||
|
||||
### `reasoning` and `item_reference`
|
||||
|
||||
Accepted for schema compatibility but ignored when building the prompt.
|
||||
|
||||
## Tools (client-side function tools)
|
||||
|
||||
Provide tools with `tools: [{ type: "function", function: { name, description?, parameters? } }]`.
|
||||
|
||||
If the agent decides to call a tool, the response returns a `function_call` output item.
|
||||
You then send a follow-up request with `function_call_output` to continue the turn.
|
||||
|
||||
## Images (`input_image`)
|
||||
|
||||
Supports base64 or URL sources:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "input_image",
|
||||
"source": { "type": "url", "url": "https://example.com/image.png" }
|
||||
}
|
||||
```
|
||||
|
||||
Allowed MIME types (current): `image/jpeg`, `image/png`, `image/gif`, `image/webp`.
|
||||
Max size (current): 10MB.
|
||||
|
||||
## Files (`input_file`)
|
||||
|
||||
Supports base64 or URL sources:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "input_file",
|
||||
"source": {
|
||||
"type": "base64",
|
||||
"media_type": "text/plain",
|
||||
"data": "SGVsbG8gV29ybGQh",
|
||||
"filename": "hello.txt"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Allowed MIME types (current): `text/plain`, `text/markdown`, `text/html`, `text/csv`,
|
||||
`application/json`, `application/pdf`.
|
||||
|
||||
Max size (current): 5MB.
|
||||
|
||||
Current behavior:
|
||||
|
||||
- File content is decoded and added to the **system prompt**, not the user message,
|
||||
so it stays ephemeral (not persisted in session history).
|
||||
- PDFs are parsed for text. If little text is found, the first pages are rasterized
|
||||
into images and passed to the model.
|
||||
|
||||
PDF parsing uses the Node-friendly `pdfjs-dist` legacy build (no worker). The modern
|
||||
PDF.js build expects browser workers/DOM globals, so it is not used in the Gateway.
|
||||
|
||||
URL fetch defaults:
|
||||
|
||||
- `files.allowUrl`: `true`
|
||||
- `images.allowUrl`: `true`
|
||||
- `maxUrlParts`: `8` (total URL-based `input_file` + `input_image` parts per request)
|
||||
- Requests are guarded (DNS resolution, private IP blocking, redirect caps, timeouts).
|
||||
- Optional hostname allowlists are supported per input type (`files.urlAllowlist`, `images.urlAllowlist`).
|
||||
- Exact host: `"cdn.example.com"`
|
||||
- Wildcard subdomains: `"*.assets.example.com"` (does not match apex)
|
||||
|
||||
## File + image limits (config)
|
||||
|
||||
Defaults can be tuned under `gateway.http.endpoints.responses`:
|
||||
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
http: {
|
||||
endpoints: {
|
||||
responses: {
|
||||
enabled: true,
|
||||
maxBodyBytes: 20000000,
|
||||
maxUrlParts: 8,
|
||||
files: {
|
||||
allowUrl: true,
|
||||
urlAllowlist: ["cdn.example.com", "*.assets.example.com"],
|
||||
allowedMimes: [
|
||||
"text/plain",
|
||||
"text/markdown",
|
||||
"text/html",
|
||||
"text/csv",
|
||||
"application/json",
|
||||
"application/pdf",
|
||||
],
|
||||
maxBytes: 5242880,
|
||||
maxChars: 200000,
|
||||
maxRedirects: 3,
|
||||
timeoutMs: 10000,
|
||||
pdf: {
|
||||
maxPages: 4,
|
||||
maxPixels: 4000000,
|
||||
minTextChars: 200,
|
||||
},
|
||||
},
|
||||
images: {
|
||||
allowUrl: true,
|
||||
urlAllowlist: ["images.example.com"],
|
||||
allowedMimes: ["image/jpeg", "image/png", "image/gif", "image/webp"],
|
||||
maxBytes: 10485760,
|
||||
maxRedirects: 3,
|
||||
timeoutMs: 10000,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Defaults when omitted:
|
||||
|
||||
- `maxBodyBytes`: 20MB
|
||||
- `maxUrlParts`: 8
|
||||
- `files.maxBytes`: 5MB
|
||||
- `files.maxChars`: 200k
|
||||
- `files.maxRedirects`: 3
|
||||
- `files.timeoutMs`: 10s
|
||||
- `files.pdf.maxPages`: 4
|
||||
- `files.pdf.maxPixels`: 4,000,000
|
||||
- `files.pdf.minTextChars`: 200
|
||||
- `images.maxBytes`: 10MB
|
||||
- `images.maxRedirects`: 3
|
||||
- `images.timeoutMs`: 10s
|
||||
|
||||
Security note:
|
||||
|
||||
- URL allowlists are enforced before fetch and on redirect hops.
|
||||
- Allowlisting a hostname does not bypass private/internal IP blocking.
|
||||
- For internet-exposed gateways, apply network egress controls in addition to app-level guards.
|
||||
See [Security](/gateway/security).
|
||||
|
||||
## Streaming (SSE)
|
||||
|
||||
Set `stream: true` to receive Server-Sent Events (SSE):
|
||||
|
||||
- `Content-Type: text/event-stream`
|
||||
- Each event line is `event: <type>` and `data: <json>`
|
||||
- Stream ends with `data: [DONE]`
|
||||
|
||||
Event types currently emitted:
|
||||
|
||||
- `response.created`
|
||||
- `response.in_progress`
|
||||
- `response.output_item.added`
|
||||
- `response.content_part.added`
|
||||
- `response.output_text.delta`
|
||||
- `response.output_text.done`
|
||||
- `response.content_part.done`
|
||||
- `response.output_item.done`
|
||||
- `response.completed`
|
||||
- `response.failed` (on error)
|
||||
|
||||
## Usage
|
||||
|
||||
`usage` is populated when the underlying provider reports token counts.
|
||||
|
||||
## Errors
|
||||
|
||||
Errors use a JSON object like:
|
||||
|
||||
```json
|
||||
{ "error": { "message": "...", "type": "invalid_request_error" } }
|
||||
```
|
||||
|
||||
Common cases:
|
||||
|
||||
- `401` missing/invalid auth
|
||||
- `400` invalid request body
|
||||
- `405` wrong method
|
||||
|
||||
## Examples
|
||||
|
||||
Non-streaming:
|
||||
|
||||
```bash
|
||||
curl -sS http://127.0.0.1:18789/v1/responses \
|
||||
-H 'Authorization: Bearer YOUR_TOKEN' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'x-openclaw-agent-id: main' \
|
||||
-d '{
|
||||
"model": "openclaw",
|
||||
"input": "hi"
|
||||
}'
|
||||
```
|
||||
|
||||
Streaming:
|
||||
|
||||
```bash
|
||||
curl -N http://127.0.0.1:18789/v1/responses \
|
||||
-H 'Authorization: Bearer YOUR_TOKEN' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'x-openclaw-agent-id: main' \
|
||||
-d '{
|
||||
"model": "openclaw",
|
||||
"stream": true,
|
||||
"input": "hi"
|
||||
}'
|
||||
```
|
||||
99
openclaw/docs/gateway/pairing.md
Normal file
99
openclaw/docs/gateway/pairing.md
Normal file
@@ -0,0 +1,99 @@
|
||||
---
|
||||
summary: "Gateway-owned node pairing (Option B) for iOS and other remote nodes"
|
||||
read_when:
|
||||
- Implementing node pairing approvals without macOS UI
|
||||
- Adding CLI flows for approving remote nodes
|
||||
- Extending gateway protocol with node management
|
||||
title: "Gateway-Owned Pairing"
|
||||
---
|
||||
|
||||
# Gateway-owned pairing (Option B)
|
||||
|
||||
In Gateway-owned pairing, the **Gateway** is the source of truth for which nodes
|
||||
are allowed to join. UIs (macOS app, future clients) are just frontends that
|
||||
approve or reject pending requests.
|
||||
|
||||
**Important:** WS nodes use **device pairing** (role `node`) during `connect`.
|
||||
`node.pair.*` is a separate pairing store and does **not** gate the WS handshake.
|
||||
Only clients that explicitly call `node.pair.*` use this flow.
|
||||
|
||||
## Concepts
|
||||
|
||||
- **Pending request**: a node asked to join; requires approval.
|
||||
- **Paired node**: approved node with an issued auth token.
|
||||
- **Transport**: the Gateway WS endpoint forwards requests but does not decide
|
||||
membership. (Legacy TCP bridge support is deprecated/removed.)
|
||||
|
||||
## How pairing works
|
||||
|
||||
1. A node connects to the Gateway WS and requests pairing.
|
||||
2. The Gateway stores a **pending request** and emits `node.pair.requested`.
|
||||
3. You approve or reject the request (CLI or UI).
|
||||
4. On approval, the Gateway issues a **new token** (tokens are rotated on re‑pair).
|
||||
5. The node reconnects using the token and is now “paired”.
|
||||
|
||||
Pending requests expire automatically after **5 minutes**.
|
||||
|
||||
## CLI workflow (headless friendly)
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
## API surface (gateway protocol)
|
||||
|
||||
Events:
|
||||
|
||||
- `node.pair.requested` — emitted when a new pending request is created.
|
||||
- `node.pair.resolved` — emitted when a request is approved/rejected/expired.
|
||||
|
||||
Methods:
|
||||
|
||||
- `node.pair.request` — create or reuse a pending request.
|
||||
- `node.pair.list` — list pending + paired nodes.
|
||||
- `node.pair.approve` — approve a pending request (issues token).
|
||||
- `node.pair.reject` — reject a pending request.
|
||||
- `node.pair.verify` — verify `{ nodeId, token }`.
|
||||
|
||||
Notes:
|
||||
|
||||
- `node.pair.request` is idempotent per node: repeated calls return the same
|
||||
pending request.
|
||||
- Approval **always** generates a fresh token; no token is ever returned from
|
||||
`node.pair.request`.
|
||||
- Requests may include `silent: true` as a hint for auto-approval flows.
|
||||
|
||||
## Auto-approval (macOS app)
|
||||
|
||||
The macOS app can optionally attempt a **silent approval** when:
|
||||
|
||||
- the request is marked `silent`, and
|
||||
- the app can verify an SSH connection to the gateway host using the same user.
|
||||
|
||||
If silent approval fails, it falls back to the normal “Approve/Reject” prompt.
|
||||
|
||||
## Storage (local, private)
|
||||
|
||||
Pairing state is stored under the Gateway state directory (default `~/.openclaw`):
|
||||
|
||||
- `~/.openclaw/nodes/paired.json`
|
||||
- `~/.openclaw/nodes/pending.json`
|
||||
|
||||
If you override `OPENCLAW_STATE_DIR`, the `nodes/` folder moves with it.
|
||||
|
||||
Security notes:
|
||||
|
||||
- Tokens are secrets; treat `paired.json` as sensitive.
|
||||
- Rotating a token requires re-approval (or deleting the node entry).
|
||||
|
||||
## Transport behavior
|
||||
|
||||
- The transport is **stateless**; it does not store membership.
|
||||
- If the Gateway is offline or pairing is disabled, nodes cannot pair.
|
||||
- If the Gateway is in remote mode, pairing still happens against the remote Gateway’s store.
|
||||
255
openclaw/docs/gateway/protocol.md
Normal file
255
openclaw/docs/gateway/protocol.md
Normal file
@@ -0,0 +1,255 @@
|
||||
---
|
||||
summary: "Gateway WebSocket protocol: handshake, frames, versioning"
|
||||
read_when:
|
||||
- Implementing or updating gateway WS clients
|
||||
- Debugging protocol mismatches or connect failures
|
||||
- Regenerating protocol schema/models
|
||||
title: "Gateway Protocol"
|
||||
---
|
||||
|
||||
# Gateway protocol (WebSocket)
|
||||
|
||||
The Gateway WS protocol is the **single control plane + node transport** for
|
||||
OpenClaw. All clients (CLI, web UI, macOS app, iOS/Android nodes, headless
|
||||
nodes) connect over WebSocket and declare their **role** + **scope** at
|
||||
handshake time.
|
||||
|
||||
## Transport
|
||||
|
||||
- WebSocket, text frames with JSON payloads.
|
||||
- First frame **must** be a `connect` request.
|
||||
|
||||
## Handshake (connect)
|
||||
|
||||
Gateway → Client (pre-connect challenge):
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "event",
|
||||
"event": "connect.challenge",
|
||||
"payload": { "nonce": "…", "ts": 1737264000000 }
|
||||
}
|
||||
```
|
||||
|
||||
Client → Gateway:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "req",
|
||||
"id": "…",
|
||||
"method": "connect",
|
||||
"params": {
|
||||
"minProtocol": 3,
|
||||
"maxProtocol": 3,
|
||||
"client": {
|
||||
"id": "cli",
|
||||
"version": "1.2.3",
|
||||
"platform": "macos",
|
||||
"mode": "operator"
|
||||
},
|
||||
"role": "operator",
|
||||
"scopes": ["operator.read", "operator.write"],
|
||||
"caps": [],
|
||||
"commands": [],
|
||||
"permissions": {},
|
||||
"auth": { "token": "…" },
|
||||
"locale": "en-US",
|
||||
"userAgent": "openclaw-cli/1.2.3",
|
||||
"device": {
|
||||
"id": "device_fingerprint",
|
||||
"publicKey": "…",
|
||||
"signature": "…",
|
||||
"signedAt": 1737264000000,
|
||||
"nonce": "…"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Gateway → Client:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "res",
|
||||
"id": "…",
|
||||
"ok": true,
|
||||
"payload": { "type": "hello-ok", "protocol": 3, "policy": { "tickIntervalMs": 15000 } }
|
||||
}
|
||||
```
|
||||
|
||||
When a device token is issued, `hello-ok` also includes:
|
||||
|
||||
```json
|
||||
{
|
||||
"auth": {
|
||||
"deviceToken": "…",
|
||||
"role": "operator",
|
||||
"scopes": ["operator.read", "operator.write"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Node example
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "req",
|
||||
"id": "…",
|
||||
"method": "connect",
|
||||
"params": {
|
||||
"minProtocol": 3,
|
||||
"maxProtocol": 3,
|
||||
"client": {
|
||||
"id": "ios-node",
|
||||
"version": "1.2.3",
|
||||
"platform": "ios",
|
||||
"mode": "node"
|
||||
},
|
||||
"role": "node",
|
||||
"scopes": [],
|
||||
"caps": ["camera", "canvas", "screen", "location", "voice"],
|
||||
"commands": ["camera.snap", "canvas.navigate", "screen.record", "location.get"],
|
||||
"permissions": { "camera.capture": true, "screen.record": false },
|
||||
"auth": { "token": "…" },
|
||||
"locale": "en-US",
|
||||
"userAgent": "openclaw-ios/1.2.3",
|
||||
"device": {
|
||||
"id": "device_fingerprint",
|
||||
"publicKey": "…",
|
||||
"signature": "…",
|
||||
"signedAt": 1737264000000,
|
||||
"nonce": "…"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Framing
|
||||
|
||||
- **Request**: `{type:"req", id, method, params}`
|
||||
- **Response**: `{type:"res", id, ok, payload|error}`
|
||||
- **Event**: `{type:"event", event, payload, seq?, stateVersion?}`
|
||||
|
||||
Side-effecting methods require **idempotency keys** (see schema).
|
||||
|
||||
## Roles + scopes
|
||||
|
||||
### Roles
|
||||
|
||||
- `operator` = control plane client (CLI/UI/automation).
|
||||
- `node` = capability host (camera/screen/canvas/system.run).
|
||||
|
||||
### Scopes (operator)
|
||||
|
||||
Common scopes:
|
||||
|
||||
- `operator.read`
|
||||
- `operator.write`
|
||||
- `operator.admin`
|
||||
- `operator.approvals`
|
||||
- `operator.pairing`
|
||||
|
||||
### Caps/commands/permissions (node)
|
||||
|
||||
Nodes declare capability claims at connect time:
|
||||
|
||||
- `caps`: high-level capability categories.
|
||||
- `commands`: command allowlist for invoke.
|
||||
- `permissions`: granular toggles (e.g. `screen.record`, `camera.capture`).
|
||||
|
||||
The Gateway treats these as **claims** and enforces server-side allowlists.
|
||||
|
||||
## Presence
|
||||
|
||||
- `system-presence` returns entries keyed by device identity.
|
||||
- Presence entries include `deviceId`, `roles`, and `scopes` so UIs can show a single row per device
|
||||
even when it connects as both **operator** and **node**.
|
||||
|
||||
### Node helper methods
|
||||
|
||||
- Nodes may call `skills.bins` to fetch the current list of skill executables
|
||||
for auto-allow checks.
|
||||
|
||||
### Operator helper methods
|
||||
|
||||
- Operators may call `tools.catalog` (`operator.read`) to fetch the runtime tool catalog for an
|
||||
agent. The response includes grouped tools and provenance metadata:
|
||||
- `source`: `core` or `plugin`
|
||||
- `pluginId`: plugin owner when `source="plugin"`
|
||||
- `optional`: whether a plugin tool is optional
|
||||
|
||||
## Exec approvals
|
||||
|
||||
- When an exec request needs approval, the gateway broadcasts `exec.approval.requested`.
|
||||
- Operator clients resolve by calling `exec.approval.resolve` (requires `operator.approvals` scope).
|
||||
|
||||
## Versioning
|
||||
|
||||
- `PROTOCOL_VERSION` lives in `src/gateway/protocol/schema.ts`.
|
||||
- Clients send `minProtocol` + `maxProtocol`; the server rejects mismatches.
|
||||
- Schemas + models are generated from TypeBox definitions:
|
||||
- `pnpm protocol:gen`
|
||||
- `pnpm protocol:gen:swift`
|
||||
- `pnpm protocol:check`
|
||||
|
||||
## Auth
|
||||
|
||||
- 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
|
||||
persisted by the client for future connects.
|
||||
- Device tokens can be rotated/revoked via `device.token.rotate` and
|
||||
`device.token.revoke` (requires `operator.pairing` scope).
|
||||
|
||||
## Device identity + pairing
|
||||
|
||||
- Nodes should include a stable device identity (`device.id`) derived from a
|
||||
keypair fingerprint.
|
||||
- Gateways issue tokens per device + role.
|
||||
- Pairing approvals are required for new device IDs unless local auto-approval
|
||||
is enabled.
|
||||
- **Local** connects include loopback and the gateway host’s own tailnet address
|
||||
(so same‑host tailnet binds can still auto‑approve).
|
||||
- All WS clients must include `device` identity during `connect` (operator + node).
|
||||
Control UI can omit it **only** when `gateway.controlUi.dangerouslyDisableDeviceAuth`
|
||||
is enabled for break-glass use.
|
||||
- All connections must sign the server-provided `connect.challenge` nonce.
|
||||
|
||||
### Device auth migration diagnostics
|
||||
|
||||
For legacy clients that still use pre-challenge signing behavior, `connect` now returns
|
||||
`DEVICE_AUTH_*` detail codes under `error.details.code` with a stable `error.details.reason`.
|
||||
|
||||
Common migration failures:
|
||||
|
||||
| Message | details.code | details.reason | Meaning |
|
||||
| --------------------------- | -------------------------------- | ------------------------ | -------------------------------------------------- |
|
||||
| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | Client omitted `device.nonce` (or sent blank). |
|
||||
| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | Client signed with a stale/wrong nonce. |
|
||||
| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | Signature payload does not match v2 payload. |
|
||||
| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | Signed timestamp is outside allowed skew. |
|
||||
| `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id` does not match public key fingerprint. |
|
||||
| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | Public key format/canonicalization failed. |
|
||||
|
||||
Migration target:
|
||||
|
||||
- Always wait for `connect.challenge`.
|
||||
- Sign the v2 payload that includes the server nonce.
|
||||
- Send the same nonce in `connect.params.device.nonce`.
|
||||
- Preferred signature payload is `v3`, which binds `platform` and `deviceFamily`
|
||||
in addition to device/client/role/scopes/token/nonce fields.
|
||||
- Legacy `v2` signatures remain accepted for compatibility, but paired-device
|
||||
metadata pinning still controls command policy on reconnect.
|
||||
|
||||
## TLS + pinning
|
||||
|
||||
- TLS is supported for WS connections.
|
||||
- Clients may optionally pin the gateway cert fingerprint (see `gateway.tls`
|
||||
config plus `gateway.remote.tlsFingerprint` or CLI `--tls-fingerprint`).
|
||||
|
||||
## Scope
|
||||
|
||||
This protocol exposes the **full gateway API** (status, channels, models, chat,
|
||||
agent, sessions, nodes, approvals, etc.). The exact surface is defined by the
|
||||
TypeBox schemas in `src/gateway/protocol/schema.ts`.
|
||||
158
openclaw/docs/gateway/remote-gateway-readme.md
Normal file
158
openclaw/docs/gateway/remote-gateway-readme.md
Normal file
@@ -0,0 +1,158 @@
|
||||
---
|
||||
summary: "SSH tunnel setup for OpenClaw.app connecting to a remote gateway"
|
||||
read_when: "Connecting the macOS app to a remote gateway over SSH"
|
||||
title: "Remote Gateway Setup"
|
||||
---
|
||||
|
||||
# Running OpenClaw.app with a Remote Gateway
|
||||
|
||||
OpenClaw.app uses SSH tunneling to connect to a remote gateway. This guide shows you how to set it up.
|
||||
|
||||
## Overview
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
subgraph Client["Client Machine"]
|
||||
direction TB
|
||||
A["OpenClaw.app"]
|
||||
B["ws://127.0.0.1:18789\n(local port)"]
|
||||
T["SSH Tunnel"]
|
||||
|
||||
A --> B
|
||||
B --> T
|
||||
end
|
||||
subgraph Remote["Remote Machine"]
|
||||
direction TB
|
||||
C["Gateway WebSocket"]
|
||||
D["ws://127.0.0.1:18789"]
|
||||
|
||||
C --> D
|
||||
end
|
||||
T --> C
|
||||
```
|
||||
|
||||
## Quick Setup
|
||||
|
||||
### Step 1: Add SSH Config
|
||||
|
||||
Edit `~/.ssh/config` and add:
|
||||
|
||||
```ssh
|
||||
Host remote-gateway
|
||||
HostName <REMOTE_IP> # e.g., 172.27.187.184
|
||||
User <REMOTE_USER> # e.g., jefferson
|
||||
LocalForward 18789 127.0.0.1:18789
|
||||
IdentityFile ~/.ssh/id_rsa
|
||||
```
|
||||
|
||||
Replace `<REMOTE_IP>` and `<REMOTE_USER>` with your values.
|
||||
|
||||
### Step 2: Copy SSH Key
|
||||
|
||||
Copy your public key to the remote machine (enter password once):
|
||||
|
||||
```bash
|
||||
ssh-copy-id -i ~/.ssh/id_rsa <REMOTE_USER>@<REMOTE_IP>
|
||||
```
|
||||
|
||||
### Step 3: Set Gateway Token
|
||||
|
||||
```bash
|
||||
launchctl setenv OPENCLAW_GATEWAY_TOKEN "<your-token>"
|
||||
```
|
||||
|
||||
### Step 4: Start SSH Tunnel
|
||||
|
||||
```bash
|
||||
ssh -N remote-gateway &
|
||||
```
|
||||
|
||||
### Step 5: Restart OpenClaw.app
|
||||
|
||||
```bash
|
||||
# Quit OpenClaw.app (⌘Q), then reopen:
|
||||
open /path/to/OpenClaw.app
|
||||
```
|
||||
|
||||
The app will now connect to the remote gateway through the SSH tunnel.
|
||||
|
||||
---
|
||||
|
||||
## Auto-Start Tunnel on Login
|
||||
|
||||
To have the SSH tunnel start automatically when you log in, create a Launch Agent.
|
||||
|
||||
### Create the PLIST file
|
||||
|
||||
Save this as `~/Library/LaunchAgents/ai.openclaw.ssh-tunnel.plist`:
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
||||
<plist version="1.0">
|
||||
<dict>
|
||||
<key>Label</key>
|
||||
<string>ai.openclaw.ssh-tunnel</string>
|
||||
<key>ProgramArguments</key>
|
||||
<array>
|
||||
<string>/usr/bin/ssh</string>
|
||||
<string>-N</string>
|
||||
<string>remote-gateway</string>
|
||||
</array>
|
||||
<key>KeepAlive</key>
|
||||
<true/>
|
||||
<key>RunAtLoad</key>
|
||||
<true/>
|
||||
</dict>
|
||||
</plist>
|
||||
```
|
||||
|
||||
### Load the Launch Agent
|
||||
|
||||
```bash
|
||||
launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.openclaw.ssh-tunnel.plist
|
||||
```
|
||||
|
||||
The tunnel will now:
|
||||
|
||||
- Start automatically when you log in
|
||||
- Restart if it crashes
|
||||
- Keep running in the background
|
||||
|
||||
Legacy note: remove any leftover `com.openclaw.ssh-tunnel` LaunchAgent if present.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Check if tunnel is running:**
|
||||
|
||||
```bash
|
||||
ps aux | grep "ssh -N remote-gateway" | grep -v grep
|
||||
lsof -i :18789
|
||||
```
|
||||
|
||||
**Restart the tunnel:**
|
||||
|
||||
```bash
|
||||
launchctl kickstart -k gui/$UID/ai.openclaw.ssh-tunnel
|
||||
```
|
||||
|
||||
**Stop the tunnel:**
|
||||
|
||||
```bash
|
||||
launchctl bootout gui/$UID/ai.openclaw.ssh-tunnel
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## How It Works
|
||||
|
||||
| Component | What It Does |
|
||||
| ------------------------------------ | ------------------------------------------------------------ |
|
||||
| `LocalForward 18789 127.0.0.1:18789` | Forwards local port 18789 to remote port 18789 |
|
||||
| `ssh -N` | SSH without executing remote commands (just port forwarding) |
|
||||
| `KeepAlive` | Automatically restarts tunnel if it crashes |
|
||||
| `RunAtLoad` | Starts tunnel when the agent loads |
|
||||
|
||||
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.
|
||||
146
openclaw/docs/gateway/remote.md
Normal file
146
openclaw/docs/gateway/remote.md
Normal file
@@ -0,0 +1,146 @@
|
||||
---
|
||||
summary: "Remote access using SSH tunnels (Gateway WS) and tailnets"
|
||||
read_when:
|
||||
- Running or troubleshooting remote gateway setups
|
||||
title: "Remote Access"
|
||||
---
|
||||
|
||||
# Remote access (SSH, tunnels, and tailnets)
|
||||
|
||||
This repo supports “remote over SSH” by keeping a single Gateway (the master) running on a dedicated host (desktop/server) and connecting clients to it.
|
||||
|
||||
- For **operators (you / the macOS app)**: SSH tunneling is the universal fallback.
|
||||
- For **nodes (iOS/Android and future devices)**: connect to the Gateway **WebSocket** (LAN/tailnet or SSH tunnel as needed).
|
||||
|
||||
## The core idea
|
||||
|
||||
- The Gateway WebSocket binds to **loopback** on your configured port (defaults to 18789).
|
||||
- For remote use, you forward that loopback port over SSH (or use a tailnet/VPN and tunnel less).
|
||||
|
||||
## Common VPN/tailnet setups (where the agent lives)
|
||||
|
||||
Think of the **Gateway host** as “where the agent lives.” It owns sessions, auth profiles, channels, and state.
|
||||
Your laptop/desktop (and nodes) connect to that host.
|
||||
|
||||
### 1) Always-on Gateway in your tailnet (VPS or home server)
|
||||
|
||||
Run the Gateway on a persistent host and reach it via **Tailscale** or SSH.
|
||||
|
||||
- **Best UX:** keep `gateway.bind: "loopback"` and use **Tailscale Serve** for the Control UI.
|
||||
- **Fallback:** keep loopback + SSH tunnel from any machine that needs access.
|
||||
- **Examples:** [exe.dev](/install/exe-dev) (easy VM) or [Hetzner](/install/hetzner) (production VPS).
|
||||
|
||||
This is ideal when your laptop sleeps often but you want the agent always-on.
|
||||
|
||||
### 2) Home desktop runs the Gateway, laptop is remote control
|
||||
|
||||
The laptop does **not** run the agent. It connects remotely:
|
||||
|
||||
- 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).
|
||||
|
||||
### 3) Laptop runs the Gateway, remote access from other machines
|
||||
|
||||
Keep the Gateway local but expose it safely:
|
||||
|
||||
- SSH tunnel to the laptop from other machines, or
|
||||
- Tailscale Serve the Control UI and keep the Gateway loopback-only.
|
||||
|
||||
Guide: [Tailscale](/gateway/tailscale) and [Web overview](/web).
|
||||
|
||||
## Command flow (what runs where)
|
||||
|
||||
One gateway service owns state + channels. Nodes are peripherals.
|
||||
|
||||
Flow example (Telegram → node):
|
||||
|
||||
- Telegram message arrives at the **Gateway**.
|
||||
- Gateway runs the **agent** and decides whether to call a node tool.
|
||||
- Gateway calls the **node** over the Gateway WebSocket (`node.*` RPC).
|
||||
- Node returns the result; Gateway replies back out to Telegram.
|
||||
|
||||
Notes:
|
||||
|
||||
- **Nodes do not run the gateway service.** Only one gateway should run per host unless you intentionally run isolated profiles (see [Multiple gateways](/gateway/multiple-gateways)).
|
||||
- macOS app “node mode” is just a node client over the Gateway WebSocket.
|
||||
|
||||
## SSH tunnel (CLI + tools)
|
||||
|
||||
Create a local tunnel to the remote Gateway WS:
|
||||
|
||||
```bash
|
||||
ssh -N -L 18789:127.0.0.1:18789 user@host
|
||||
```
|
||||
|
||||
With the tunnel up:
|
||||
|
||||
- `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`/`OPENCLAW_GATEWAY_PORT`).
|
||||
Note: when you pass `--url`, the CLI does not fall back to config or environment credentials.
|
||||
Include `--token` or `--password` explicitly. Missing explicit credentials is an error.
|
||||
|
||||
## CLI remote defaults
|
||||
|
||||
You can persist a remote target so CLI commands use it by default:
|
||||
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
mode: "remote",
|
||||
remote: {
|
||||
url: "ws://127.0.0.1:18789",
|
||||
token: "your-token",
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
When the gateway is loopback-only, keep the URL at `ws://127.0.0.1:18789` and open the SSH tunnel first.
|
||||
|
||||
## Credential precedence
|
||||
|
||||
Gateway call/probe credential resolution now follows one shared contract:
|
||||
|
||||
- Explicit credentials (`--token`, `--password`, or tool `gatewayToken`) always win.
|
||||
- Local mode defaults:
|
||||
- token: `OPENCLAW_GATEWAY_TOKEN` -> `gateway.auth.token` -> `gateway.remote.token`
|
||||
- password: `OPENCLAW_GATEWAY_PASSWORD` -> `gateway.auth.password` -> `gateway.remote.password`
|
||||
- Remote mode defaults:
|
||||
- token: `gateway.remote.token` -> `OPENCLAW_GATEWAY_TOKEN` -> `gateway.auth.token`
|
||||
- password: `OPENCLAW_GATEWAY_PASSWORD` -> `gateway.remote.password` -> `gateway.auth.password`
|
||||
- Remote probe/status token checks are strict by default: they use `gateway.remote.token` only (no local token fallback) when targeting remote mode.
|
||||
- Legacy `CLAWDBOT_GATEWAY_*` env vars are only used by compatibility call paths; probe/status/auth resolution uses `OPENCLAW_GATEWAY_*` only.
|
||||
|
||||
## Chat UI over SSH
|
||||
|
||||
WebChat no longer uses a separate HTTP port. The SwiftUI chat UI connects directly to the Gateway WebSocket.
|
||||
|
||||
- Forward `18789` over SSH (see above), then connect clients to `ws://127.0.0.1:18789`.
|
||||
- On macOS, prefer the app’s “Remote over SSH” mode, which manages the tunnel automatically.
|
||||
|
||||
## macOS app “Remote over SSH”
|
||||
|
||||
The macOS menu bar app can drive the same setup end-to-end (remote status checks, WebChat, and Voice Wake forwarding).
|
||||
|
||||
Runbook: [macOS remote access](/platforms/mac/remote).
|
||||
|
||||
## Security rules (remote/VPN)
|
||||
|
||||
Short version: **keep the Gateway loopback-only** unless you’re sure you need a bind.
|
||||
|
||||
- **Loopback + SSH/Tailscale Serve** is the safest default (no public exposure).
|
||||
- **Non-loopback binds** (`lan`/`tailnet`/`custom`, or `auto` when loopback is unavailable) must use auth tokens/passwords.
|
||||
- `gateway.remote.token` / `.password` are client credential sources. They do **not** configure server auth by themselves.
|
||||
- Local call paths can use `gateway.remote.*` as fallback when `gateway.auth.*` is unset.
|
||||
- `gateway.remote.tlsFingerprint` pins the remote TLS cert when using `wss://`.
|
||||
- **Tailscale Serve** can authenticate Control UI/WebSocket traffic via identity
|
||||
headers when `gateway.auth.allowTailscale: true`; HTTP API endpoints still
|
||||
require token/password auth. This tokenless flow assumes the gateway host is
|
||||
trusted. Set it to `false` if you want tokens/passwords everywhere.
|
||||
- Treat browser control like operator access: tailnet-only + deliberate node pairing.
|
||||
|
||||
Deep dive: [Security](/gateway/security).
|
||||
128
openclaw/docs/gateway/sandbox-vs-tool-policy-vs-elevated.md
Normal file
128
openclaw/docs/gateway/sandbox-vs-tool-policy-vs-elevated.md
Normal file
@@ -0,0 +1,128 @@
|
||||
---
|
||||
title: Sandbox vs Tool Policy vs Elevated
|
||||
summary: "Why a tool is blocked: sandbox runtime, tool allow/deny policy, and elevated exec gates"
|
||||
read_when: "You hit 'sandbox jail' or see a tool/elevated refusal and want the exact config key to change."
|
||||
status: active
|
||||
---
|
||||
|
||||
# Sandbox vs Tool Policy vs Elevated
|
||||
|
||||
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**.
|
||||
3. **Elevated** (`tools.elevated.*`, `agents.list[].tools.elevated.*`) is an **exec-only escape hatch** to run on the host when you’re sandboxed.
|
||||
|
||||
## Quick debug
|
||||
|
||||
Use the inspector to see what OpenClaw is _actually_ doing:
|
||||
|
||||
```bash
|
||||
openclaw sandbox explain
|
||||
openclaw sandbox explain --session agent:main:main
|
||||
openclaw sandbox explain --agent work
|
||||
openclaw sandbox explain --json
|
||||
```
|
||||
|
||||
It prints:
|
||||
|
||||
- effective sandbox mode/scope/workspace access
|
||||
- whether the session is currently sandboxed (main vs non-main)
|
||||
- effective sandbox tool allow/deny (and whether it came from agent/global/default)
|
||||
- elevated gates and fix-it key paths
|
||||
|
||||
## Sandbox: where tools run
|
||||
|
||||
Sandboxing is controlled by `agents.defaults.sandbox.mode`:
|
||||
|
||||
- `"off"`: everything runs on the host.
|
||||
- `"non-main"`: only non-main sessions are sandboxed (common “surprise” for groups/channels).
|
||||
- `"all"`: everything is sandboxed.
|
||||
|
||||
See [Sandboxing](/gateway/sandboxing) for the full matrix (scope, workspace mounts, images).
|
||||
|
||||
### Bind mounts (security quick check)
|
||||
|
||||
- `docker.binds` _pierces_ the sandbox filesystem: whatever you mount is visible inside the container with the mode you set (`:ro` or `:rw`).
|
||||
- Default is read-write if you omit the mode; prefer `:ro` for source/secrets.
|
||||
- `scope: "shared"` ignores per-agent binds (only global binds apply).
|
||||
- Binding `/var/run/docker.sock` effectively hands host control to the sandbox; only do this intentionally.
|
||||
- Workspace access (`workspaceAccess: "ro"`/`"rw"`) is independent of bind modes.
|
||||
|
||||
## Tool policy: which tools exist/are callable
|
||||
|
||||
Two layers matter:
|
||||
|
||||
- **Tool profile**: `tools.profile` and `agents.list[].tools.profile` (base allowlist)
|
||||
- **Provider tool profile**: `tools.byProvider[provider].profile` and `agents.list[].tools.byProvider[provider].profile`
|
||||
- **Global/per-agent tool policy**: `tools.allow`/`tools.deny` and `agents.list[].tools.allow`/`agents.list[].tools.deny`
|
||||
- **Provider tool policy**: `tools.byProvider[provider].allow/deny` and `agents.list[].tools.byProvider[provider].allow/deny`
|
||||
- **Sandbox tool policy** (only applies when sandboxed): `tools.sandbox.tools.allow`/`tools.sandbox.tools.deny` and `agents.list[].tools.sandbox.tools.*`
|
||||
|
||||
Rules of thumb:
|
||||
|
||||
- `deny` always wins.
|
||||
- If `allow` is non-empty, everything else is treated as blocked.
|
||||
- Tool policy is the hard stop: `/exec` cannot override a denied `exec` tool.
|
||||
- `/exec` only changes session defaults for authorized senders; it does not grant tool access.
|
||||
Provider tool keys accept either `provider` (e.g. `google-antigravity`) or `provider/model` (e.g. `openai/gpt-5.2`).
|
||||
|
||||
### Tool groups (shorthands)
|
||||
|
||||
Tool policies (global, agent, sandbox) support `group:*` entries that expand to multiple tools:
|
||||
|
||||
```json5
|
||||
{
|
||||
tools: {
|
||||
sandbox: {
|
||||
tools: {
|
||||
allow: ["group:runtime", "group:fs", "group:sessions", "group:memory"],
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Available groups:
|
||||
|
||||
- `group:runtime`: `exec`, `bash`, `process`
|
||||
- `group:fs`: `read`, `write`, `edit`, `apply_patch`
|
||||
- `group:sessions`: `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `session_status`
|
||||
- `group:memory`: `memory_search`, `memory_get`
|
||||
- `group:ui`: `browser`, `canvas`
|
||||
- `group:automation`: `cron`, `gateway`
|
||||
- `group:messaging`: `message`
|
||||
- `group:nodes`: `nodes`
|
||||
- `group:openclaw`: all built-in OpenClaw tools (excludes provider plugins)
|
||||
|
||||
## Elevated: exec-only “run on host”
|
||||
|
||||
Elevated does **not** grant extra tools; it only affects `exec`.
|
||||
|
||||
- If you’re sandboxed, `/elevated on` (or `exec` with `elevated: true`) runs on the host (approvals may still apply).
|
||||
- Use `/elevated full` to skip exec approvals for the session.
|
||||
- If you’re already running direct, elevated is effectively a no-op (still gated).
|
||||
- Elevated is **not** skill-scoped and does **not** override tool allow/deny.
|
||||
- `/exec` is separate from elevated. It only adjusts per-session exec defaults for authorized senders.
|
||||
|
||||
Gates:
|
||||
|
||||
- Enablement: `tools.elevated.enabled` (and optionally `agents.list[].tools.elevated.enabled`)
|
||||
- Sender allowlists: `tools.elevated.allowFrom.<provider>` (and optionally `agents.list[].tools.elevated.allowFrom.<provider>`)
|
||||
|
||||
See [Elevated Mode](/tools/elevated).
|
||||
|
||||
## Common “sandbox jail” fixes
|
||||
|
||||
### “Tool X blocked by sandbox tool policy”
|
||||
|
||||
Fix-it keys (pick one):
|
||||
|
||||
- Disable sandbox: `agents.defaults.sandbox.mode=off` (or per-agent `agents.list[].sandbox.mode=off`)
|
||||
- Allow the tool inside sandbox:
|
||||
- remove it from `tools.sandbox.tools.deny` (or per-agent `agents.list[].tools.sandbox.tools.deny`)
|
||||
- or add it to `tools.sandbox.tools.allow` (or per-agent allow)
|
||||
|
||||
### “I thought this was main, why is it sandboxed?”
|
||||
|
||||
In `"non-main"` mode, group/channel keys are _not_ main. Use the main session key (shown by `sandbox explain`) or switch mode to `"off"`.
|
||||
210
openclaw/docs/gateway/sandboxing.md
Normal file
210
openclaw/docs/gateway/sandboxing.md
Normal file
@@ -0,0 +1,210 @@
|
||||
---
|
||||
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
|
||||
---
|
||||
|
||||
# Sandboxing
|
||||
|
||||
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
|
||||
when enabled.
|
||||
|
||||
This is not a perfect security boundary, but it materially limits filesystem
|
||||
and process access when the model does something dumb.
|
||||
|
||||
## What gets sandboxed
|
||||
|
||||
- Tool execution (`exec`, `read`, `write`, `edit`, `apply_patch`, `process`, etc.).
|
||||
- Optional sandboxed browser (`agents.defaults.sandbox.browser`).
|
||||
- By default, the sandbox browser auto-starts (ensures CDP is reachable) when the browser tool needs it.
|
||||
Configure via `agents.defaults.sandbox.browser.autoStart` and `agents.defaults.sandbox.browser.autoStartTimeoutMs`.
|
||||
- By default, sandbox browser containers use a dedicated Docker network (`openclaw-sandbox-browser`) instead of the global `bridge` network.
|
||||
Configure with `agents.defaults.sandbox.browser.network`.
|
||||
- Optional `agents.defaults.sandbox.browser.cdpSourceRange` restricts container-edge CDP ingress with a CIDR allowlist (for example `172.21.0.1/32`).
|
||||
- noVNC observer access is password-protected by default; OpenClaw emits a short-lived token URL that resolves to the observer session.
|
||||
- `agents.defaults.sandbox.browser.allowHostControl` lets sandboxed sessions target the host browser explicitly.
|
||||
- Optional allowlists gate `target: "custom"`: `allowedControlUrls`, `allowedControlHosts`, `allowedControlPorts`.
|
||||
|
||||
Not sandboxed:
|
||||
|
||||
- The Gateway process itself.
|
||||
- Any tool explicitly allowed to run on the host (e.g. `tools.elevated`).
|
||||
- **Elevated exec runs on the host and bypasses sandboxing.**
|
||||
- If sandboxing is off, `tools.elevated` does not change execution (already on host). See [Elevated Mode](/tools/elevated).
|
||||
|
||||
## Modes
|
||||
|
||||
`agents.defaults.sandbox.mode` controls **when** sandboxing is used:
|
||||
|
||||
- `"off"`: no sandboxing.
|
||||
- `"non-main"`: sandbox only **non-main** sessions (default if you want normal chats on host).
|
||||
- `"all"`: every session runs in a sandbox.
|
||||
Note: `"non-main"` is based on `session.mainKey` (default `"main"`), not agent id.
|
||||
Group/channel sessions use their own keys, so they count as non-main and will be sandboxed.
|
||||
|
||||
## Scope
|
||||
|
||||
`agents.defaults.sandbox.scope` controls **how many containers** are created:
|
||||
|
||||
- `"session"` (default): one container per session.
|
||||
- `"agent"`: one container per agent.
|
||||
- `"shared"`: one container shared by all sandboxed sessions.
|
||||
|
||||
## Workspace access
|
||||
|
||||
`agents.defaults.sandbox.workspaceAccess` controls **what the sandbox can see**:
|
||||
|
||||
- `"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"`,
|
||||
OpenClaw mirrors eligible skills into the sandbox workspace (`.../skills`) so
|
||||
they can be read. With `"rw"`, workspace skills are readable from
|
||||
`/workspace/skills`.
|
||||
|
||||
## Custom bind mounts
|
||||
|
||||
`agents.defaults.sandbox.docker.binds` mounts additional host directories into the container.
|
||||
Format: `host:container:mode` (e.g., `"/home/user/source:/source:rw"`).
|
||||
|
||||
Global and per-agent binds are **merged** (not replaced). Under `scope: "shared"`, per-agent binds are ignored.
|
||||
|
||||
`agents.defaults.sandbox.browser.binds` mounts additional host directories into the **sandbox browser** container only.
|
||||
|
||||
- When set (including `[]`), it replaces `agents.defaults.sandbox.docker.binds` for the browser container.
|
||||
- When omitted, the browser container falls back to `agents.defaults.sandbox.docker.binds` (backwards compatible).
|
||||
|
||||
Example (read-only source + an extra data directory):
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
sandbox: {
|
||||
docker: {
|
||||
binds: ["/home/user/source:/source:ro", "/var/data/myapp:/data:ro"],
|
||||
},
|
||||
},
|
||||
},
|
||||
list: [
|
||||
{
|
||||
id: "build",
|
||||
sandbox: {
|
||||
docker: {
|
||||
binds: ["/mnt/cache:/cache:rw"],
|
||||
},
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Security notes:
|
||||
|
||||
- Binds bypass the sandbox filesystem: they expose host paths with whatever mode you set (`:ro` or `:rw`).
|
||||
- OpenClaw blocks dangerous bind sources (for example: `docker.sock`, `/etc`, `/proc`, `/sys`, `/dev`, and parent mounts that would expose them).
|
||||
- Sensitive mounts (secrets, SSH keys, service credentials) should be `:ro` unless absolutely required.
|
||||
- Combine with `workspaceAccess: "ro"` if you only need read access to the workspace; bind modes stay independent.
|
||||
- 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: `openclaw-sandbox:bookworm-slim`
|
||||
|
||||
Build it once:
|
||||
|
||||
```bash
|
||||
scripts/sandbox-setup.sh
|
||||
```
|
||||
|
||||
Note: the default image does **not** include Node. If a skill needs Node (or
|
||||
other runtimes), either bake a custom image or install via
|
||||
`sandbox.docker.setupCommand` (requires network egress + writable root +
|
||||
root user).
|
||||
|
||||
Sandboxed browser image:
|
||||
|
||||
```bash
|
||||
scripts/sandbox-browser-setup.sh
|
||||
```
|
||||
|
||||
By default, sandbox containers run with **no network**.
|
||||
Override with `agents.defaults.sandbox.docker.network`.
|
||||
|
||||
Security defaults:
|
||||
|
||||
- `network: "host"` is blocked.
|
||||
- `network: "container:<id>"` is blocked by default (namespace join bypass risk).
|
||||
- Break-glass override: `agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`.
|
||||
|
||||
Docker installs and the containerized gateway live here:
|
||||
[Docker](/install/docker)
|
||||
|
||||
## setupCommand (one-time container setup)
|
||||
|
||||
`setupCommand` runs **once** after the sandbox container is created (not on every run).
|
||||
It executes inside the container via `sh -lc`.
|
||||
|
||||
Paths:
|
||||
|
||||
- Global: `agents.defaults.sandbox.docker.setupCommand`
|
||||
- Per-agent: `agents.list[].sandbox.docker.setupCommand`
|
||||
|
||||
Common pitfalls:
|
||||
|
||||
- Default `docker.network` is `"none"` (no egress), so package installs will fail.
|
||||
- `docker.network: "container:<id>"` requires `dangerouslyAllowContainerNamespaceJoin: true` and is break-glass only.
|
||||
- `readOnlyRoot: true` prevents writes; set `readOnlyRoot: false` or bake a custom image.
|
||||
- `user` must be root for package installs (omit `user` or set `user: "0:0"`).
|
||||
- Sandbox exec does **not** inherit host `process.env`. Use
|
||||
`agents.defaults.sandbox.docker.env` (or a custom image) for skill API keys.
|
||||
|
||||
## Tool policy + escape hatches
|
||||
|
||||
Tool allow/deny policies still apply before sandbox rules. If a tool is denied
|
||||
globally or per-agent, sandboxing doesn’t bring it back.
|
||||
|
||||
`tools.elevated` is an explicit escape hatch that runs `exec` on the host.
|
||||
`/exec` directives only apply for authorized senders and persist per session; to hard-disable
|
||||
`exec`, use tool policy deny (see [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated)).
|
||||
|
||||
Debugging:
|
||||
|
||||
- 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.
|
||||
|
||||
## Multi-agent overrides
|
||||
|
||||
Each agent can override sandbox + tools:
|
||||
`agents.list[].sandbox` and `agents.list[].tools` (plus `agents.list[].tools.sandbox.tools` for sandbox tool policy).
|
||||
See [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) for precedence.
|
||||
|
||||
## Minimal enable example
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
sandbox: {
|
||||
mode: "non-main",
|
||||
scope: "session",
|
||||
workspaceAccess: "none",
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## Related docs
|
||||
|
||||
- [Sandbox Configuration](/gateway/configuration#agentsdefaults-sandbox)
|
||||
- [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools)
|
||||
- [Security](/gateway/security)
|
||||
94
openclaw/docs/gateway/secrets-plan-contract.md
Normal file
94
openclaw/docs/gateway/secrets-plan-contract.md
Normal file
@@ -0,0 +1,94 @@
|
||||
---
|
||||
summary: "Contract for `secrets apply` plans: allowed target paths, validation, and ref-only auth-profile behavior"
|
||||
read_when:
|
||||
- Generating or reviewing `openclaw secrets apply` plan files
|
||||
- Debugging `Invalid plan target path` errors
|
||||
- Understanding how `keyRef` and `tokenRef` influence implicit provider discovery
|
||||
title: "Secrets Apply Plan Contract"
|
||||
---
|
||||
|
||||
# Secrets apply plan contract
|
||||
|
||||
This page defines the strict contract enforced by `openclaw secrets apply`.
|
||||
|
||||
If a target does not match these rules, apply fails before mutating config.
|
||||
|
||||
## Plan file shape
|
||||
|
||||
`openclaw secrets apply --from <plan.json>` expects a `targets` array of plan targets:
|
||||
|
||||
```json5
|
||||
{
|
||||
version: 1,
|
||||
protocolVersion: 1,
|
||||
targets: [
|
||||
{
|
||||
type: "models.providers.apiKey",
|
||||
path: "models.providers.openai.apiKey",
|
||||
pathSegments: ["models", "providers", "openai", "apiKey"],
|
||||
providerId: "openai",
|
||||
ref: { source: "env", provider: "default", id: "OPENAI_API_KEY" },
|
||||
},
|
||||
],
|
||||
}
|
||||
```
|
||||
|
||||
## Allowed target types and paths
|
||||
|
||||
| `target.type` | Allowed `target.path` shape | Optional id match rule |
|
||||
| ------------------------------------ | --------------------------------------------------------- | --------------------------------------------------- |
|
||||
| `models.providers.apiKey` | `models.providers.<providerId>.apiKey` | `providerId` must match `<providerId>` when present |
|
||||
| `skills.entries.apiKey` | `skills.entries.<skillKey>.apiKey` | n/a |
|
||||
| `channels.googlechat.serviceAccount` | `channels.googlechat.serviceAccount` | `accountId` must be empty/omitted |
|
||||
| `channels.googlechat.serviceAccount` | `channels.googlechat.accounts.<accountId>.serviceAccount` | `accountId` must match `<accountId>` when present |
|
||||
|
||||
## Path validation rules
|
||||
|
||||
Each target is validated with all of the following:
|
||||
|
||||
- `type` must be one of the allowed target types above.
|
||||
- `path` must be a non-empty dot path.
|
||||
- `pathSegments` can be omitted. If provided, it must normalize to exactly the same path as `path`.
|
||||
- Forbidden segments are rejected: `__proto__`, `prototype`, `constructor`.
|
||||
- The normalized path must match one of the allowed path shapes for the target type.
|
||||
- If `providerId` / `accountId` is set, it must match the id encoded in the path.
|
||||
|
||||
## Failure behavior
|
||||
|
||||
If a target fails validation, apply exits with an error like:
|
||||
|
||||
```text
|
||||
Invalid plan target path for models.providers.apiKey: models.providers.openai.baseUrl
|
||||
```
|
||||
|
||||
No partial mutation is committed for that invalid target path.
|
||||
|
||||
## Ref-only auth profiles and implicit providers
|
||||
|
||||
Implicit provider discovery also considers auth profiles that store refs instead of plaintext credentials:
|
||||
|
||||
- `type: "api_key"` profiles can use `keyRef` (for example env-backed refs).
|
||||
- `type: "token"` profiles can use `tokenRef`.
|
||||
|
||||
Behavior:
|
||||
|
||||
- For API-key providers (for example `volcengine`, `byteplus`), ref-only profiles can still activate implicit provider entries.
|
||||
- For `github-copilot`, if the profile has no plaintext token, discovery will try `tokenRef` env resolution before token exchange.
|
||||
|
||||
## Operator checks
|
||||
|
||||
```bash
|
||||
# Validate plan without writes
|
||||
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
|
||||
|
||||
# Then apply for real
|
||||
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
|
||||
```
|
||||
|
||||
If apply fails with an invalid target path message, regenerate the plan with `openclaw secrets configure` or fix the target path to one of the allowed shapes above.
|
||||
|
||||
## Related docs
|
||||
|
||||
- [Secrets Management](/gateway/secrets)
|
||||
- [CLI `secrets`](/cli/secrets)
|
||||
- [Configuration Reference](/gateway/configuration-reference)
|
||||
386
openclaw/docs/gateway/secrets.md
Normal file
386
openclaw/docs/gateway/secrets.md
Normal file
@@ -0,0 +1,386 @@
|
||||
---
|
||||
summary: "Secrets management: SecretRef contract, runtime snapshot behavior, and safe one-way scrubbing"
|
||||
read_when:
|
||||
- Configuring SecretRefs for providers, auth profiles, skills, or Google Chat
|
||||
- Operating secrets reload/audit/configure/apply safely in production
|
||||
- Understanding fail-fast and last-known-good behavior
|
||||
title: "Secrets Management"
|
||||
---
|
||||
|
||||
# Secrets management
|
||||
|
||||
OpenClaw supports additive secret references so credentials do not need to be stored as plaintext in config files.
|
||||
|
||||
Plaintext still works. Secret refs are optional.
|
||||
|
||||
## Goals and runtime model
|
||||
|
||||
Secrets are resolved into an in-memory runtime snapshot.
|
||||
|
||||
- Resolution is eager during activation, not lazy on request paths.
|
||||
- Startup fails fast if any referenced credential cannot be resolved.
|
||||
- Reload uses atomic swap: full success or keep last-known-good.
|
||||
- Runtime requests read from the active in-memory snapshot.
|
||||
|
||||
This keeps secret-provider outages off the hot request path.
|
||||
|
||||
## Onboarding reference preflight
|
||||
|
||||
When onboarding runs in interactive mode and you choose secret reference storage, OpenClaw performs a fast preflight check before saving:
|
||||
|
||||
- Env refs: validates env var name and confirms a non-empty value is visible during onboarding.
|
||||
- Provider refs (`file` or `exec`): validates the selected provider, resolves the provided `id`, and checks value type.
|
||||
|
||||
If validation fails, onboarding shows the error and lets you retry.
|
||||
|
||||
## SecretRef contract
|
||||
|
||||
Use one object shape everywhere:
|
||||
|
||||
```json5
|
||||
{ source: "env" | "file" | "exec", provider: "default", id: "..." }
|
||||
```
|
||||
|
||||
### `source: "env"`
|
||||
|
||||
```json5
|
||||
{ source: "env", provider: "default", id: "OPENAI_API_KEY" }
|
||||
```
|
||||
|
||||
Validation:
|
||||
|
||||
- `provider` must match `^[a-z][a-z0-9_-]{0,63}$`
|
||||
- `id` must match `^[A-Z][A-Z0-9_]{0,127}$`
|
||||
|
||||
### `source: "file"`
|
||||
|
||||
```json5
|
||||
{ source: "file", provider: "filemain", id: "/providers/openai/apiKey" }
|
||||
```
|
||||
|
||||
Validation:
|
||||
|
||||
- `provider` must match `^[a-z][a-z0-9_-]{0,63}$`
|
||||
- `id` must be an absolute JSON pointer (`/...`)
|
||||
- RFC6901 escaping in segments: `~` => `~0`, `/` => `~1`
|
||||
|
||||
### `source: "exec"`
|
||||
|
||||
```json5
|
||||
{ source: "exec", provider: "vault", id: "providers/openai/apiKey" }
|
||||
```
|
||||
|
||||
Validation:
|
||||
|
||||
- `provider` must match `^[a-z][a-z0-9_-]{0,63}$`
|
||||
- `id` must match `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$`
|
||||
|
||||
## Provider config
|
||||
|
||||
Define providers under `secrets.providers`:
|
||||
|
||||
```json5
|
||||
{
|
||||
secrets: {
|
||||
providers: {
|
||||
default: { source: "env" },
|
||||
filemain: {
|
||||
source: "file",
|
||||
path: "~/.openclaw/secrets.json",
|
||||
mode: "json", // or "singleValue"
|
||||
},
|
||||
vault: {
|
||||
source: "exec",
|
||||
command: "/usr/local/bin/openclaw-vault-resolver",
|
||||
args: ["--profile", "prod"],
|
||||
passEnv: ["PATH", "VAULT_ADDR"],
|
||||
jsonOnly: true,
|
||||
},
|
||||
},
|
||||
defaults: {
|
||||
env: "default",
|
||||
file: "filemain",
|
||||
exec: "vault",
|
||||
},
|
||||
resolution: {
|
||||
maxProviderConcurrency: 4,
|
||||
maxRefsPerProvider: 512,
|
||||
maxBatchBytes: 262144,
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Env provider
|
||||
|
||||
- Optional allowlist via `allowlist`.
|
||||
- Missing/empty env values fail resolution.
|
||||
|
||||
### File provider
|
||||
|
||||
- Reads local file from `path`.
|
||||
- `mode: "json"` expects JSON object payload and resolves `id` as pointer.
|
||||
- `mode: "singleValue"` expects ref id `"value"` and returns file contents.
|
||||
- Path must pass ownership/permission checks.
|
||||
|
||||
### Exec provider
|
||||
|
||||
- Runs configured absolute binary path, no shell.
|
||||
- By default, `command` must point to a regular file (not a symlink).
|
||||
- Set `allowSymlinkCommand: true` to allow symlink command paths (for example Homebrew shims). OpenClaw validates the resolved target path.
|
||||
- Enable `allowSymlinkCommand` only when required for trusted package-manager paths, and pair it with `trustedDirs` (for example `["/opt/homebrew"]`).
|
||||
- When `trustedDirs` is set, checks apply to the resolved target path.
|
||||
- Supports timeout, no-output timeout, output byte limits, env allowlist, and trusted dirs.
|
||||
- Request payload (stdin):
|
||||
|
||||
```json
|
||||
{ "protocolVersion": 1, "provider": "vault", "ids": ["providers/openai/apiKey"] }
|
||||
```
|
||||
|
||||
- Response payload (stdout):
|
||||
|
||||
```json
|
||||
{ "protocolVersion": 1, "values": { "providers/openai/apiKey": "sk-..." } }
|
||||
```
|
||||
|
||||
Optional per-id errors:
|
||||
|
||||
```json
|
||||
{
|
||||
"protocolVersion": 1,
|
||||
"values": {},
|
||||
"errors": { "providers/openai/apiKey": { "message": "not found" } }
|
||||
}
|
||||
```
|
||||
|
||||
## Exec integration examples
|
||||
|
||||
### 1Password CLI
|
||||
|
||||
```json5
|
||||
{
|
||||
secrets: {
|
||||
providers: {
|
||||
onepassword_openai: {
|
||||
source: "exec",
|
||||
command: "/opt/homebrew/bin/op",
|
||||
allowSymlinkCommand: true, // required for Homebrew symlinked binaries
|
||||
trustedDirs: ["/opt/homebrew"],
|
||||
args: ["read", "op://Personal/OpenClaw QA API Key/password"],
|
||||
passEnv: ["HOME"],
|
||||
jsonOnly: false,
|
||||
},
|
||||
},
|
||||
},
|
||||
models: {
|
||||
providers: {
|
||||
openai: {
|
||||
baseUrl: "https://api.openai.com/v1",
|
||||
models: [{ id: "gpt-5", name: "gpt-5" }],
|
||||
apiKey: { source: "exec", provider: "onepassword_openai", id: "value" },
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### HashiCorp Vault CLI
|
||||
|
||||
```json5
|
||||
{
|
||||
secrets: {
|
||||
providers: {
|
||||
vault_openai: {
|
||||
source: "exec",
|
||||
command: "/opt/homebrew/bin/vault",
|
||||
allowSymlinkCommand: true, // required for Homebrew symlinked binaries
|
||||
trustedDirs: ["/opt/homebrew"],
|
||||
args: ["kv", "get", "-field=OPENAI_API_KEY", "secret/openclaw"],
|
||||
passEnv: ["VAULT_ADDR", "VAULT_TOKEN"],
|
||||
jsonOnly: false,
|
||||
},
|
||||
},
|
||||
},
|
||||
models: {
|
||||
providers: {
|
||||
openai: {
|
||||
baseUrl: "https://api.openai.com/v1",
|
||||
models: [{ id: "gpt-5", name: "gpt-5" }],
|
||||
apiKey: { source: "exec", provider: "vault_openai", id: "value" },
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### `sops`
|
||||
|
||||
```json5
|
||||
{
|
||||
secrets: {
|
||||
providers: {
|
||||
sops_openai: {
|
||||
source: "exec",
|
||||
command: "/opt/homebrew/bin/sops",
|
||||
allowSymlinkCommand: true, // required for Homebrew symlinked binaries
|
||||
trustedDirs: ["/opt/homebrew"],
|
||||
args: ["-d", "--extract", '["providers"]["openai"]["apiKey"]', "/path/to/secrets.enc.json"],
|
||||
passEnv: ["SOPS_AGE_KEY_FILE"],
|
||||
jsonOnly: false,
|
||||
},
|
||||
},
|
||||
},
|
||||
models: {
|
||||
providers: {
|
||||
openai: {
|
||||
baseUrl: "https://api.openai.com/v1",
|
||||
models: [{ id: "gpt-5", name: "gpt-5" }],
|
||||
apiKey: { source: "exec", provider: "sops_openai", id: "value" },
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## In-scope fields (v1)
|
||||
|
||||
### `~/.openclaw/openclaw.json`
|
||||
|
||||
- `models.providers.<provider>.apiKey`
|
||||
- `skills.entries.<skillKey>.apiKey`
|
||||
- `channels.googlechat.serviceAccount`
|
||||
- `channels.googlechat.serviceAccountRef`
|
||||
- `channels.googlechat.accounts.<accountId>.serviceAccount`
|
||||
- `channels.googlechat.accounts.<accountId>.serviceAccountRef`
|
||||
|
||||
### `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
|
||||
|
||||
- `profiles.<profileId>.keyRef` for `type: "api_key"`
|
||||
- `profiles.<profileId>.tokenRef` for `type: "token"`
|
||||
|
||||
OAuth credential storage changes are out of scope.
|
||||
|
||||
## Required behavior and precedence
|
||||
|
||||
- Field without ref: unchanged.
|
||||
- Field with ref: required at activation time.
|
||||
- If plaintext and ref both exist, ref wins at runtime and plaintext is ignored.
|
||||
|
||||
Warning code:
|
||||
|
||||
- `SECRETS_REF_OVERRIDES_PLAINTEXT`
|
||||
|
||||
## Activation triggers
|
||||
|
||||
Secret activation is attempted on:
|
||||
|
||||
- Startup (preflight plus final activation)
|
||||
- Config reload hot-apply path
|
||||
- Config reload restart-check path
|
||||
- Manual reload via `secrets.reload`
|
||||
|
||||
Activation contract:
|
||||
|
||||
- Success swaps the snapshot atomically.
|
||||
- Startup failure aborts gateway startup.
|
||||
- Runtime reload failure keeps last-known-good snapshot.
|
||||
|
||||
## Degraded and recovered operator signals
|
||||
|
||||
When reload-time activation fails after a healthy state, OpenClaw enters degraded secrets state.
|
||||
|
||||
One-shot system event and log codes:
|
||||
|
||||
- `SECRETS_RELOADER_DEGRADED`
|
||||
- `SECRETS_RELOADER_RECOVERED`
|
||||
|
||||
Behavior:
|
||||
|
||||
- Degraded: runtime keeps last-known-good snapshot.
|
||||
- Recovered: emitted once after a successful activation.
|
||||
- Repeated failures while already degraded log warnings but do not spam events.
|
||||
- Startup fail-fast does not emit degraded events because no runtime snapshot exists yet.
|
||||
|
||||
## Audit and configure workflow
|
||||
|
||||
Use this default operator flow:
|
||||
|
||||
```bash
|
||||
openclaw secrets audit --check
|
||||
openclaw secrets configure
|
||||
openclaw secrets audit --check
|
||||
```
|
||||
|
||||
Migration completeness:
|
||||
|
||||
- Include `skills.entries.<skillKey>.apiKey` targets when those skills use API keys.
|
||||
- If `audit --check` still reports plaintext findings after a partial migration, migrate the remaining reported paths and rerun audit.
|
||||
|
||||
### `secrets audit`
|
||||
|
||||
Findings include:
|
||||
|
||||
- plaintext values at rest (`openclaw.json`, `auth-profiles.json`, `.env`)
|
||||
- unresolved refs
|
||||
- precedence shadowing (`auth-profiles` taking priority over config refs)
|
||||
- legacy residues (`auth.json`, OAuth out-of-scope reminders)
|
||||
|
||||
### `secrets configure`
|
||||
|
||||
Interactive helper that:
|
||||
|
||||
- configures `secrets.providers` first (`env`/`file`/`exec`, add/edit/remove)
|
||||
- lets you select secret-bearing fields in `openclaw.json`
|
||||
- captures SecretRef details (`source`, `provider`, `id`)
|
||||
- runs preflight resolution
|
||||
- can apply immediately
|
||||
|
||||
Helpful modes:
|
||||
|
||||
- `openclaw secrets configure --providers-only`
|
||||
- `openclaw secrets configure --skip-provider-setup`
|
||||
|
||||
`configure` apply defaults to:
|
||||
|
||||
- scrub matching static creds from `auth-profiles.json` for targeted providers
|
||||
- scrub legacy static `api_key` entries from `auth.json`
|
||||
- scrub matching known secret lines from `<config-dir>/.env`
|
||||
|
||||
### `secrets apply`
|
||||
|
||||
Apply a saved plan:
|
||||
|
||||
```bash
|
||||
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
|
||||
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
|
||||
```
|
||||
|
||||
For strict target/path contract details and exact rejection rules, see:
|
||||
|
||||
- [Secrets Apply Plan Contract](/gateway/secrets-plan-contract)
|
||||
|
||||
## One-way safety policy
|
||||
|
||||
OpenClaw intentionally does **not** write rollback backups that contain pre-migration plaintext secret values.
|
||||
|
||||
Safety model:
|
||||
|
||||
- preflight must succeed before write mode
|
||||
- runtime activation is validated before commit
|
||||
- apply updates files using atomic file replacement and best-effort in-memory restore on failure
|
||||
|
||||
## `auth.json` compatibility notes
|
||||
|
||||
For static credentials, OpenClaw runtime no longer depends on plaintext `auth.json`.
|
||||
|
||||
- Runtime credential source is the resolved in-memory snapshot.
|
||||
- Legacy `auth.json` static `api_key` entries are scrubbed when discovered.
|
||||
- OAuth-related legacy compatibility behavior remains separate.
|
||||
|
||||
## Related docs
|
||||
|
||||
- CLI commands: [secrets](/cli/secrets)
|
||||
- Plan contract details: [Secrets Apply Plan Contract](/gateway/secrets-plan-contract)
|
||||
- Auth setup: [Authentication](/gateway/authentication)
|
||||
- Security posture: [Security](/gateway/security)
|
||||
- Environment precedence: [Environment Variables](/help/environment)
|
||||
1119
openclaw/docs/gateway/security/index.md
Normal file
1119
openclaw/docs/gateway/security/index.md
Normal file
File diff suppressed because it is too large
Load Diff
132
openclaw/docs/gateway/tailscale.md
Normal file
132
openclaw/docs/gateway/tailscale.md
Normal file
@@ -0,0 +1,132 @@
|
||||
---
|
||||
summary: "Integrated Tailscale Serve/Funnel for the Gateway dashboard"
|
||||
read_when:
|
||||
- Exposing the Gateway Control UI outside localhost
|
||||
- Automating tailnet or public dashboard access
|
||||
title: "Tailscale"
|
||||
---
|
||||
|
||||
# Tailscale (Gateway dashboard)
|
||||
|
||||
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`. OpenClaw requires a shared password.
|
||||
- `off`: Default (no Tailscale automation).
|
||||
|
||||
## Auth
|
||||
|
||||
Set `gateway.auth.mode` to control the handshake:
|
||||
|
||||
- `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`,
|
||||
Control UI/WebSocket auth can use Tailscale identity headers
|
||||
(`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.
|
||||
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.
|
||||
HTTP API endpoints (for example `/v1/*`, `/tools/invoke`, and `/api/channels/*`)
|
||||
still require token/password auth.
|
||||
This tokenless flow assumes the gateway host is trusted. If untrusted local code
|
||||
may run on the same host, disable `gateway.auth.allowTailscale` and require
|
||||
token/password auth instead.
|
||||
To require explicit credentials, set `gateway.auth.allowTailscale: false` or
|
||||
force `gateway.auth.mode: "password"`.
|
||||
|
||||
## Config examples
|
||||
|
||||
### Tailnet-only (Serve)
|
||||
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
bind: "loopback",
|
||||
tailscale: { mode: "serve" },
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Open: `https://<magicdns>/` (or your configured `gateway.controlUi.basePath`)
|
||||
|
||||
### Tailnet-only (bind to Tailnet IP)
|
||||
|
||||
Use this when you want the Gateway to listen directly on the Tailnet IP (no Serve/Funnel).
|
||||
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
bind: "tailnet",
|
||||
auth: { mode: "token", token: "your-token" },
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Connect from another Tailnet device:
|
||||
|
||||
- Control UI: `http://<tailscale-ip>:18789/`
|
||||
- WebSocket: `ws://<tailscale-ip>:18789`
|
||||
|
||||
Note: loopback (`http://127.0.0.1:18789`) will **not** work in this mode.
|
||||
|
||||
### Public internet (Funnel + shared password)
|
||||
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
bind: "loopback",
|
||||
tailscale: { mode: "funnel" },
|
||||
auth: { mode: "password", password: "replace-me" },
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Prefer `OPENCLAW_GATEWAY_PASSWORD` over committing a password to disk.
|
||||
|
||||
## CLI examples
|
||||
|
||||
```bash
|
||||
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 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.
|
||||
- Serve/Funnel only expose the **Gateway control UI + WS**. Nodes connect over
|
||||
the same Gateway WS endpoint, so Serve can work for node access.
|
||||
|
||||
## Browser control (remote Gateway + local browser)
|
||||
|
||||
If you run the Gateway on one machine but want to drive a browser on another machine,
|
||||
run a **node host** on the browser machine and keep both on the same tailnet.
|
||||
The Gateway will proxy browser actions to the node; no separate control server or Serve URL needed.
|
||||
|
||||
Avoid Funnel for browser control; treat node pairing like operator access.
|
||||
|
||||
## Tailscale prerequisites + limits
|
||||
|
||||
- Serve requires HTTPS enabled for your tailnet; the CLI prompts if it is missing.
|
||||
- Serve injects Tailscale identity headers; Funnel does not.
|
||||
- Funnel requires Tailscale v1.38.3+, MagicDNS, HTTPS enabled, and a funnel node attribute.
|
||||
- Funnel only supports ports `443`, `8443`, and `10000` over TLS.
|
||||
- Funnel on macOS requires the open-source Tailscale app variant.
|
||||
|
||||
## Learn more
|
||||
|
||||
- Tailscale Serve overview: [https://tailscale.com/kb/1312/serve](https://tailscale.com/kb/1312/serve)
|
||||
- `tailscale serve` command: [https://tailscale.com/kb/1242/tailscale-serve](https://tailscale.com/kb/1242/tailscale-serve)
|
||||
- Tailscale Funnel overview: [https://tailscale.com/kb/1223/tailscale-funnel](https://tailscale.com/kb/1223/tailscale-funnel)
|
||||
- `tailscale funnel` command: [https://tailscale.com/kb/1311/tailscale-funnel](https://tailscale.com/kb/1311/tailscale-funnel)
|
||||
110
openclaw/docs/gateway/tools-invoke-http-api.md
Normal file
110
openclaw/docs/gateway/tools-invoke-http-api.md
Normal file
@@ -0,0 +1,110 @@
|
||||
---
|
||||
summary: "Invoke a single tool directly via the Gateway HTTP endpoint"
|
||||
read_when:
|
||||
- Calling tools without running a full agent turn
|
||||
- Building automations that need tool policy enforcement
|
||||
title: "Tools Invoke API"
|
||||
---
|
||||
|
||||
# Tools Invoke (HTTP)
|
||||
|
||||
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`
|
||||
|
||||
Default max payload size is 2 MB.
|
||||
|
||||
## Authentication
|
||||
|
||||
Uses the Gateway auth configuration. Send a bearer token:
|
||||
|
||||
- `Authorization: Bearer <token>`
|
||||
|
||||
Notes:
|
||||
|
||||
- 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`).
|
||||
- If `gateway.auth.rateLimit` is configured and too many auth failures occur, the endpoint returns `429` with `Retry-After`.
|
||||
|
||||
## Request body
|
||||
|
||||
```json
|
||||
{
|
||||
"tool": "sessions_list",
|
||||
"action": "json",
|
||||
"args": {},
|
||||
"sessionKey": "main",
|
||||
"dryRun": false
|
||||
}
|
||||
```
|
||||
|
||||
Fields:
|
||||
|
||||
- `tool` (string, required): tool name to invoke.
|
||||
- `action` (string, optional): mapped into args if the tool schema supports `action` and the args payload omitted it.
|
||||
- `args` (object, optional): tool-specific arguments.
|
||||
- `sessionKey` (string, optional): target session key. If omitted or `"main"`, the Gateway uses the configured main session key (honors `session.mainKey` and default agent, or `global` in global scope).
|
||||
- `dryRun` (boolean, optional): reserved for future use; currently ignored.
|
||||
|
||||
## Policy + routing behavior
|
||||
|
||||
Tool availability is filtered through the same policy chain used by Gateway agents:
|
||||
|
||||
- `tools.profile` / `tools.byProvider.profile`
|
||||
- `tools.allow` / `tools.byProvider.allow`
|
||||
- `agents.<id>.tools.allow` / `agents.<id>.tools.byProvider.allow`
|
||||
- group policies (if the session key maps to a group or channel)
|
||||
- subagent policy (when invoking with a subagent session key)
|
||||
|
||||
If a tool is not allowed by policy, the endpoint returns **404**.
|
||||
|
||||
Gateway HTTP also applies a hard deny list by default (even if session policy allows the tool):
|
||||
|
||||
- `sessions_spawn`
|
||||
- `sessions_send`
|
||||
- `gateway`
|
||||
- `whatsapp_login`
|
||||
|
||||
You can customize this deny list via `gateway.tools`:
|
||||
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
tools: {
|
||||
// Additional tools to block over HTTP /tools/invoke
|
||||
deny: ["browser"],
|
||||
// Remove tools from the default deny list
|
||||
allow: ["gateway"],
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
To help group policies resolve context, you can optionally set:
|
||||
|
||||
- `x-openclaw-message-channel: <channel>` (example: `slack`, `telegram`)
|
||||
- `x-openclaw-account-id: <accountId>` (when multiple accounts exist)
|
||||
|
||||
## Responses
|
||||
|
||||
- `200` → `{ ok: true, result }`
|
||||
- `400` → `{ ok: false, error: { type, message } }` (invalid request or tool input error)
|
||||
- `401` → unauthorized
|
||||
- `429` → auth rate-limited (`Retry-After` set)
|
||||
- `404` → tool not available (not found or not allowlisted)
|
||||
- `405` → method not allowed
|
||||
- `500` → `{ ok: false, error: { type, message } }` (unexpected tool execution error; sanitized message)
|
||||
|
||||
## Example
|
||||
|
||||
```bash
|
||||
curl -sS http://127.0.0.1:18789/tools/invoke \
|
||||
-H 'Authorization: Bearer YOUR_TOKEN' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"tool": "sessions_list",
|
||||
"action": "json",
|
||||
"args": {}
|
||||
}'
|
||||
```
|
||||
337
openclaw/docs/gateway/troubleshooting.md
Normal file
337
openclaw/docs/gateway/troubleshooting.md
Normal file
@@ -0,0 +1,337 @@
|
||||
---
|
||||
summary: "Deep troubleshooting runbook for gateway, channels, automation, nodes, and browser"
|
||||
read_when:
|
||||
- The troubleshooting hub pointed you here for deeper diagnosis
|
||||
- You need stable symptom based runbook sections with exact commands
|
||||
title: "Troubleshooting"
|
||||
---
|
||||
|
||||
# Gateway troubleshooting
|
||||
|
||||
This page is the deep runbook.
|
||||
Start at [/help/troubleshooting](/help/troubleshooting) if you want the fast triage flow first.
|
||||
|
||||
## Command ladder
|
||||
|
||||
Run these first, in this order:
|
||||
|
||||
```bash
|
||||
openclaw status
|
||||
openclaw gateway status
|
||||
openclaw logs --follow
|
||||
openclaw doctor
|
||||
openclaw channels status --probe
|
||||
```
|
||||
|
||||
Expected healthy signals:
|
||||
|
||||
- `openclaw gateway status` shows `Runtime: running` and `RPC probe: ok`.
|
||||
- `openclaw doctor` reports no blocking config/service issues.
|
||||
- `openclaw channels status --probe` shows connected/ready channels.
|
||||
|
||||
## No replies
|
||||
|
||||
If channels are up but nothing answers, check routing and policy before reconnecting anything.
|
||||
|
||||
```bash
|
||||
openclaw status
|
||||
openclaw channels status --probe
|
||||
openclaw pairing list --channel <channel> [--account <id>]
|
||||
openclaw config get channels
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
Look for:
|
||||
|
||||
- Pairing pending for DM senders.
|
||||
- Group mention gating (`requireMention`, `mentionPatterns`).
|
||||
- Channel/group allowlist mismatches.
|
||||
|
||||
Common signatures:
|
||||
|
||||
- `drop guild message (mention required` → group message ignored until mention.
|
||||
- `pairing request` → sender needs approval.
|
||||
- `blocked` / `allowlist` → sender/channel was filtered by policy.
|
||||
|
||||
Related:
|
||||
|
||||
- [/channels/troubleshooting](/channels/troubleshooting)
|
||||
- [/channels/pairing](/channels/pairing)
|
||||
- [/channels/groups](/channels/groups)
|
||||
|
||||
## Dashboard control ui connectivity
|
||||
|
||||
When dashboard/control UI will not connect, validate URL, auth mode, and secure context assumptions.
|
||||
|
||||
```bash
|
||||
openclaw gateway status
|
||||
openclaw status
|
||||
openclaw logs --follow
|
||||
openclaw doctor
|
||||
openclaw gateway status --json
|
||||
```
|
||||
|
||||
Look for:
|
||||
|
||||
- Correct probe URL and dashboard URL.
|
||||
- Auth mode/token mismatch between client and gateway.
|
||||
- HTTP usage where device identity is required.
|
||||
|
||||
Common signatures:
|
||||
|
||||
- `device identity required` → non-secure context or missing device auth.
|
||||
- `device nonce required` / `device nonce mismatch` → client is not completing the
|
||||
challenge-based device auth flow (`connect.challenge` + `device.nonce`).
|
||||
- `device signature invalid` / `device signature expired` → client signed the wrong
|
||||
payload (or stale timestamp) for the current handshake.
|
||||
- `unauthorized` / reconnect loop → token/password mismatch.
|
||||
- `gateway connect failed:` → wrong host/port/url target.
|
||||
|
||||
Device auth v2 migration check:
|
||||
|
||||
```bash
|
||||
openclaw --version
|
||||
openclaw doctor
|
||||
openclaw gateway status
|
||||
```
|
||||
|
||||
If logs show nonce/signature errors, update the connecting client and verify it:
|
||||
|
||||
1. waits for `connect.challenge`
|
||||
2. signs the challenge-bound payload
|
||||
3. sends `connect.params.device.nonce` with the same challenge nonce
|
||||
|
||||
Related:
|
||||
|
||||
- [/web/control-ui](/web/control-ui)
|
||||
- [/gateway/authentication](/gateway/authentication)
|
||||
- [/gateway/remote](/gateway/remote)
|
||||
|
||||
## Gateway service not running
|
||||
|
||||
Use this when service is installed but process does not stay up.
|
||||
|
||||
```bash
|
||||
openclaw gateway status
|
||||
openclaw status
|
||||
openclaw logs --follow
|
||||
openclaw doctor
|
||||
openclaw gateway status --deep
|
||||
```
|
||||
|
||||
Look for:
|
||||
|
||||
- `Runtime: stopped` with exit hints.
|
||||
- Service config mismatch (`Config (cli)` vs `Config (service)`).
|
||||
- Port/listener conflicts.
|
||||
|
||||
Common signatures:
|
||||
|
||||
- `Gateway start blocked: set gateway.mode=local` → local gateway mode is not enabled. Fix: set `gateway.mode="local"` in your config (or run `openclaw configure`). If you are running OpenClaw via Podman using the dedicated `openclaw` user, the config lives at `~openclaw/.openclaw/openclaw.json`.
|
||||
- `refusing to bind gateway ... without auth` → non-loopback bind without token/password.
|
||||
- `another gateway instance is already listening` / `EADDRINUSE` → port conflict.
|
||||
|
||||
Related:
|
||||
|
||||
- [/gateway/background-process](/gateway/background-process)
|
||||
- [/gateway/configuration](/gateway/configuration)
|
||||
- [/gateway/doctor](/gateway/doctor)
|
||||
|
||||
## Channel connected messages not flowing
|
||||
|
||||
If channel state is connected but message flow is dead, focus on policy, permissions, and channel specific delivery rules.
|
||||
|
||||
```bash
|
||||
openclaw channels status --probe
|
||||
openclaw pairing list --channel <channel> [--account <id>]
|
||||
openclaw status --deep
|
||||
openclaw logs --follow
|
||||
openclaw config get channels
|
||||
```
|
||||
|
||||
Look for:
|
||||
|
||||
- DM policy (`pairing`, `allowlist`, `open`, `disabled`).
|
||||
- Group allowlist and mention requirements.
|
||||
- Missing channel API permissions/scopes.
|
||||
|
||||
Common signatures:
|
||||
|
||||
- `mention required` → message ignored by group mention policy.
|
||||
- `pairing` / pending approval traces → sender is not approved.
|
||||
- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → channel auth/permissions issue.
|
||||
|
||||
Related:
|
||||
|
||||
- [/channels/troubleshooting](/channels/troubleshooting)
|
||||
- [/channels/whatsapp](/channels/whatsapp)
|
||||
- [/channels/telegram](/channels/telegram)
|
||||
- [/channels/discord](/channels/discord)
|
||||
|
||||
## Cron and heartbeat delivery
|
||||
|
||||
If cron or heartbeat did not run or did not deliver, verify scheduler state first, then delivery target.
|
||||
|
||||
```bash
|
||||
openclaw cron status
|
||||
openclaw cron list
|
||||
openclaw cron runs --id <jobId> --limit 20
|
||||
openclaw system heartbeat last
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
Look for:
|
||||
|
||||
- Cron enabled and next wake present.
|
||||
- Job run history status (`ok`, `skipped`, `error`).
|
||||
- Heartbeat skip reasons (`quiet-hours`, `requests-in-flight`, `alerts-disabled`).
|
||||
|
||||
Common signatures:
|
||||
|
||||
- `cron: scheduler disabled; jobs will not run automatically` → cron disabled.
|
||||
- `cron: timer tick failed` → scheduler tick failed; check file/log/runtime errors.
|
||||
- `heartbeat skipped` with `reason=quiet-hours` → outside active hours window.
|
||||
- `heartbeat: unknown accountId` → invalid account id for heartbeat delivery target.
|
||||
- `heartbeat skipped` with `reason=dm-blocked` → heartbeat target resolved to a DM-style destination while `agents.defaults.heartbeat.directPolicy` (or per-agent override) is set to `block`.
|
||||
|
||||
Related:
|
||||
|
||||
- [/automation/troubleshooting](/automation/troubleshooting)
|
||||
- [/automation/cron-jobs](/automation/cron-jobs)
|
||||
- [/gateway/heartbeat](/gateway/heartbeat)
|
||||
|
||||
## Node paired tool fails
|
||||
|
||||
If a node is paired but tools fail, isolate foreground, permission, and approval state.
|
||||
|
||||
```bash
|
||||
openclaw nodes status
|
||||
openclaw nodes describe --node <idOrNameOrIp>
|
||||
openclaw approvals get --node <idOrNameOrIp>
|
||||
openclaw logs --follow
|
||||
openclaw status
|
||||
```
|
||||
|
||||
Look for:
|
||||
|
||||
- Node online with expected capabilities.
|
||||
- OS permission grants for camera/mic/location/screen.
|
||||
- Exec approvals and allowlist state.
|
||||
|
||||
Common signatures:
|
||||
|
||||
- `NODE_BACKGROUND_UNAVAILABLE` → node app must be in foreground.
|
||||
- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → missing OS permission.
|
||||
- `SYSTEM_RUN_DENIED: approval required` → exec approval pending.
|
||||
- `SYSTEM_RUN_DENIED: allowlist miss` → command blocked by allowlist.
|
||||
|
||||
Related:
|
||||
|
||||
- [/nodes/troubleshooting](/nodes/troubleshooting)
|
||||
- [/nodes/index](/nodes/index)
|
||||
- [/tools/exec-approvals](/tools/exec-approvals)
|
||||
|
||||
## Browser tool fails
|
||||
|
||||
Use this when browser tool actions fail even though the gateway itself is healthy.
|
||||
|
||||
```bash
|
||||
openclaw browser status
|
||||
openclaw browser start --browser-profile openclaw
|
||||
openclaw browser profiles
|
||||
openclaw logs --follow
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
Look for:
|
||||
|
||||
- Valid browser executable path.
|
||||
- CDP profile reachability.
|
||||
- Extension relay tab attachment for `profile="chrome"`.
|
||||
|
||||
Common signatures:
|
||||
|
||||
- `Failed to start Chrome CDP on port` → browser process failed to launch.
|
||||
- `browser.executablePath not found` → configured path is invalid.
|
||||
- `Chrome extension relay is running, but no tab is connected` → extension relay not attached.
|
||||
- `Browser attachOnly is enabled ... not reachable` → attach-only profile has no reachable target.
|
||||
|
||||
Related:
|
||||
|
||||
- [/tools/browser-linux-troubleshooting](/tools/browser-linux-troubleshooting)
|
||||
- [/tools/chrome-extension](/tools/chrome-extension)
|
||||
- [/tools/browser](/tools/browser)
|
||||
|
||||
## If you upgraded and something suddenly broke
|
||||
|
||||
Most post-upgrade breakage is config drift or stricter defaults now being enforced.
|
||||
|
||||
### 1) Auth and URL override behavior changed
|
||||
|
||||
```bash
|
||||
openclaw gateway status
|
||||
openclaw config get gateway.mode
|
||||
openclaw config get gateway.remote.url
|
||||
openclaw config get gateway.auth.mode
|
||||
```
|
||||
|
||||
What to check:
|
||||
|
||||
- If `gateway.mode=remote`, CLI calls may be targeting remote while your local service is fine.
|
||||
- Explicit `--url` calls do not fall back to stored credentials.
|
||||
|
||||
Common signatures:
|
||||
|
||||
- `gateway connect failed:` → wrong URL target.
|
||||
- `unauthorized` → endpoint reachable but wrong auth.
|
||||
|
||||
### 2) Bind and auth guardrails are stricter
|
||||
|
||||
```bash
|
||||
openclaw config get gateway.bind
|
||||
openclaw config get gateway.auth.token
|
||||
openclaw gateway status
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
What to check:
|
||||
|
||||
- Non-loopback binds (`lan`, `tailnet`, `custom`) need auth configured.
|
||||
- Old keys like `gateway.token` do not replace `gateway.auth.token`.
|
||||
|
||||
Common signatures:
|
||||
|
||||
- `refusing to bind gateway ... without auth` → bind+auth mismatch.
|
||||
- `RPC probe: failed` while runtime is running → gateway alive but inaccessible with current auth/url.
|
||||
|
||||
### 3) Pairing and device identity state changed
|
||||
|
||||
```bash
|
||||
openclaw devices list
|
||||
openclaw pairing list --channel <channel> [--account <id>]
|
||||
openclaw logs --follow
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
What to check:
|
||||
|
||||
- Pending device approvals for dashboard/nodes.
|
||||
- Pending DM pairing approvals after policy or identity changes.
|
||||
|
||||
Common signatures:
|
||||
|
||||
- `device identity required` → device auth not satisfied.
|
||||
- `pairing required` → sender/device must be approved.
|
||||
|
||||
If the service config and runtime still disagree after checks, reinstall service metadata from the same profile/state directory:
|
||||
|
||||
```bash
|
||||
openclaw gateway install --force
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
Related:
|
||||
|
||||
- [/gateway/pairing](/gateway/pairing)
|
||||
- [/gateway/authentication](/gateway/authentication)
|
||||
- [/gateway/background-process](/gateway/background-process)
|
||||
329
openclaw/docs/gateway/trusted-proxy-auth.md
Normal file
329
openclaw/docs/gateway/trusted-proxy-auth.md
Normal file
@@ -0,0 +1,329 @@
|
||||
---
|
||||
summary: "Delegate gateway authentication to a trusted reverse proxy (Pomerium, Caddy, nginx + OAuth)"
|
||||
read_when:
|
||||
- Running OpenClaw behind an identity-aware proxy
|
||||
- Setting up Pomerium, Caddy, or nginx with OAuth in front of OpenClaw
|
||||
- Fixing WebSocket 1008 unauthorized errors with reverse proxy setups
|
||||
- Deciding where to set HSTS and other HTTP hardening headers
|
||||
---
|
||||
|
||||
# Trusted Proxy Auth
|
||||
|
||||
> ⚠️ **Security-sensitive feature.** This mode delegates authentication entirely to your reverse proxy. Misconfiguration can expose your Gateway to unauthorized access. Read this page carefully before enabling.
|
||||
|
||||
## When to Use
|
||||
|
||||
Use `trusted-proxy` auth mode when:
|
||||
|
||||
- You run OpenClaw behind an **identity-aware proxy** (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + forward auth)
|
||||
- Your proxy handles all authentication and passes user identity via headers
|
||||
- You're in a Kubernetes or container environment where the proxy is the only path to the Gateway
|
||||
- You're hitting WebSocket `1008 unauthorized` errors because browsers can't pass tokens in WS payloads
|
||||
|
||||
## When NOT to Use
|
||||
|
||||
- If your proxy doesn't authenticate users (just a TLS terminator or load balancer)
|
||||
- If there's any path to the Gateway that bypasses the proxy (firewall holes, internal network access)
|
||||
- If you're unsure whether your proxy correctly strips/overwrites forwarded headers
|
||||
- If you only need personal single-user access (consider Tailscale Serve + loopback for simpler setup)
|
||||
|
||||
## How It Works
|
||||
|
||||
1. Your reverse proxy authenticates users (OAuth, OIDC, SAML, etc.)
|
||||
2. Proxy adds a header with the authenticated user identity (e.g., `x-forwarded-user: nick@example.com`)
|
||||
3. OpenClaw checks that the request came from a **trusted proxy IP** (configured in `gateway.trustedProxies`)
|
||||
4. OpenClaw extracts the user identity from the configured header
|
||||
5. If everything checks out, the request is authorized
|
||||
|
||||
## Control UI Pairing Behavior
|
||||
|
||||
When `gateway.auth.mode = "trusted-proxy"` is active and the request passes
|
||||
trusted-proxy checks, Control UI WebSocket sessions can connect without device
|
||||
pairing identity.
|
||||
|
||||
Implications:
|
||||
|
||||
- Pairing is no longer the primary gate for Control UI access in this mode.
|
||||
- Your reverse proxy auth policy and `allowUsers` become the effective access control.
|
||||
- Keep gateway ingress locked to trusted proxy IPs only (`gateway.trustedProxies` + firewall).
|
||||
|
||||
## Configuration
|
||||
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
// Use loopback for same-host proxy setups; use lan/custom for remote proxy hosts
|
||||
bind: "loopback",
|
||||
|
||||
// CRITICAL: Only add your proxy's IP(s) here
|
||||
trustedProxies: ["10.0.0.1", "172.17.0.1"],
|
||||
|
||||
auth: {
|
||||
mode: "trusted-proxy",
|
||||
trustedProxy: {
|
||||
// Header containing authenticated user identity (required)
|
||||
userHeader: "x-forwarded-user",
|
||||
|
||||
// Optional: headers that MUST be present (proxy verification)
|
||||
requiredHeaders: ["x-forwarded-proto", "x-forwarded-host"],
|
||||
|
||||
// Optional: restrict to specific users (empty = allow all)
|
||||
allowUsers: ["nick@example.com", "admin@company.org"],
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
If `gateway.bind` is `loopback`, include a loopback proxy address in
|
||||
`gateway.trustedProxies` (`127.0.0.1`, `::1`, or an equivalent loopback CIDR).
|
||||
|
||||
### Configuration Reference
|
||||
|
||||
| Field | Required | Description |
|
||||
| ------------------------------------------- | -------- | --------------------------------------------------------------------------- |
|
||||
| `gateway.trustedProxies` | Yes | Array of proxy IP addresses to trust. Requests from other IPs are rejected. |
|
||||
| `gateway.auth.mode` | Yes | Must be `"trusted-proxy"` |
|
||||
| `gateway.auth.trustedProxy.userHeader` | Yes | Header name containing the authenticated user identity |
|
||||
| `gateway.auth.trustedProxy.requiredHeaders` | No | Additional headers that must be present for the request to be trusted |
|
||||
| `gateway.auth.trustedProxy.allowUsers` | No | Allowlist of user identities. Empty means allow all authenticated users. |
|
||||
|
||||
## TLS termination and HSTS
|
||||
|
||||
Use one TLS termination point and apply HSTS there.
|
||||
|
||||
### Recommended pattern: proxy TLS termination
|
||||
|
||||
When your reverse proxy handles HTTPS for `https://control.example.com`, set
|
||||
`Strict-Transport-Security` at the proxy for that domain.
|
||||
|
||||
- Good fit for internet-facing deployments.
|
||||
- Keeps certificate + HTTP hardening policy in one place.
|
||||
- OpenClaw can stay on loopback HTTP behind the proxy.
|
||||
|
||||
Example header value:
|
||||
|
||||
```text
|
||||
Strict-Transport-Security: max-age=31536000; includeSubDomains
|
||||
```
|
||||
|
||||
### Gateway TLS termination
|
||||
|
||||
If OpenClaw itself serves HTTPS directly (no TLS-terminating proxy), set:
|
||||
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
tls: { enabled: true },
|
||||
http: {
|
||||
securityHeaders: {
|
||||
strictTransportSecurity: "max-age=31536000; includeSubDomains",
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
`strictTransportSecurity` accepts a string header value, or `false` to disable explicitly.
|
||||
|
||||
### Rollout guidance
|
||||
|
||||
- Start with a short max age first (for example `max-age=300`) while validating traffic.
|
||||
- Increase to long-lived values (for example `max-age=31536000`) only after confidence is high.
|
||||
- Add `includeSubDomains` only if every subdomain is HTTPS-ready.
|
||||
- Use preload only if you intentionally meet preload requirements for your full domain set.
|
||||
- Loopback-only local development does not benefit from HSTS.
|
||||
|
||||
## Proxy Setup Examples
|
||||
|
||||
### Pomerium
|
||||
|
||||
Pomerium passes identity in `x-pomerium-claim-email` (or other claim headers) and a JWT in `x-pomerium-jwt-assertion`.
|
||||
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
bind: "lan",
|
||||
trustedProxies: ["10.0.0.1"], // Pomerium's IP
|
||||
auth: {
|
||||
mode: "trusted-proxy",
|
||||
trustedProxy: {
|
||||
userHeader: "x-pomerium-claim-email",
|
||||
requiredHeaders: ["x-pomerium-jwt-assertion"],
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Pomerium config snippet:
|
||||
|
||||
```yaml
|
||||
routes:
|
||||
- from: https://openclaw.example.com
|
||||
to: http://openclaw-gateway:18789
|
||||
policy:
|
||||
- allow:
|
||||
or:
|
||||
- email:
|
||||
is: nick@example.com
|
||||
pass_identity_headers: true
|
||||
```
|
||||
|
||||
### Caddy with OAuth
|
||||
|
||||
Caddy with the `caddy-security` plugin can authenticate users and pass identity headers.
|
||||
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
bind: "lan",
|
||||
trustedProxies: ["127.0.0.1"], // Caddy's IP (if on same host)
|
||||
auth: {
|
||||
mode: "trusted-proxy",
|
||||
trustedProxy: {
|
||||
userHeader: "x-forwarded-user",
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Caddyfile snippet:
|
||||
|
||||
```
|
||||
openclaw.example.com {
|
||||
authenticate with oauth2_provider
|
||||
authorize with policy1
|
||||
|
||||
reverse_proxy openclaw:18789 {
|
||||
header_up X-Forwarded-User {http.auth.user.email}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### nginx + oauth2-proxy
|
||||
|
||||
oauth2-proxy authenticates users and passes identity in `x-auth-request-email`.
|
||||
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
bind: "lan",
|
||||
trustedProxies: ["10.0.0.1"], // nginx/oauth2-proxy IP
|
||||
auth: {
|
||||
mode: "trusted-proxy",
|
||||
trustedProxy: {
|
||||
userHeader: "x-auth-request-email",
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
nginx config snippet:
|
||||
|
||||
```nginx
|
||||
location / {
|
||||
auth_request /oauth2/auth;
|
||||
auth_request_set $user $upstream_http_x_auth_request_email;
|
||||
|
||||
proxy_pass http://openclaw:18789;
|
||||
proxy_set_header X-Auth-Request-Email $user;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
}
|
||||
```
|
||||
|
||||
### Traefik with Forward Auth
|
||||
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
bind: "lan",
|
||||
trustedProxies: ["172.17.0.1"], // Traefik container IP
|
||||
auth: {
|
||||
mode: "trusted-proxy",
|
||||
trustedProxy: {
|
||||
userHeader: "x-forwarded-user",
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## Security Checklist
|
||||
|
||||
Before enabling trusted-proxy auth, verify:
|
||||
|
||||
- [ ] **Proxy is the only path**: The Gateway port is firewalled from everything except your proxy
|
||||
- [ ] **trustedProxies is minimal**: Only your actual proxy IPs, not entire subnets
|
||||
- [ ] **Proxy strips headers**: Your proxy overwrites (not appends) `x-forwarded-*` headers from clients
|
||||
- [ ] **TLS termination**: Your proxy handles TLS; users connect via HTTPS
|
||||
- [ ] **allowUsers is set** (recommended): Restrict to known users rather than allowing anyone authenticated
|
||||
|
||||
## Security Audit
|
||||
|
||||
`openclaw security audit` will flag trusted-proxy auth with a **critical** severity finding. This is intentional — it's a reminder that you're delegating security to your proxy setup.
|
||||
|
||||
The audit checks for:
|
||||
|
||||
- Missing `trustedProxies` configuration
|
||||
- Missing `userHeader` configuration
|
||||
- Empty `allowUsers` (allows any authenticated user)
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "trusted_proxy_untrusted_source"
|
||||
|
||||
The request didn't come from an IP in `gateway.trustedProxies`. Check:
|
||||
|
||||
- Is the proxy IP correct? (Docker container IPs can change)
|
||||
- Is there a load balancer in front of your proxy?
|
||||
- Use `docker inspect` or `kubectl get pods -o wide` to find actual IPs
|
||||
|
||||
### "trusted_proxy_user_missing"
|
||||
|
||||
The user header was empty or missing. Check:
|
||||
|
||||
- Is your proxy configured to pass identity headers?
|
||||
- Is the header name correct? (case-insensitive, but spelling matters)
|
||||
- Is the user actually authenticated at the proxy?
|
||||
|
||||
### "trusted*proxy_missing_header*\*"
|
||||
|
||||
A required header wasn't present. Check:
|
||||
|
||||
- Your proxy configuration for those specific headers
|
||||
- Whether headers are being stripped somewhere in the chain
|
||||
|
||||
### "trusted_proxy_user_not_allowed"
|
||||
|
||||
The user is authenticated but not in `allowUsers`. Either add them or remove the allowlist.
|
||||
|
||||
### WebSocket Still Failing
|
||||
|
||||
Make sure your proxy:
|
||||
|
||||
- Supports WebSocket upgrades (`Upgrade: websocket`, `Connection: upgrade`)
|
||||
- Passes the identity headers on WebSocket upgrade requests (not just HTTP)
|
||||
- Doesn't have a separate auth path for WebSocket connections
|
||||
|
||||
## Migration from Token Auth
|
||||
|
||||
If you're moving from token auth to trusted-proxy:
|
||||
|
||||
1. Configure your proxy to authenticate users and pass headers
|
||||
2. Test the proxy setup independently (curl with headers)
|
||||
3. Update OpenClaw config with trusted-proxy auth
|
||||
4. Restart the Gateway
|
||||
5. Test WebSocket connections from the Control UI
|
||||
6. Run `openclaw security audit` and review findings
|
||||
|
||||
## Related
|
||||
|
||||
- [Security](/gateway/security) — full security guide
|
||||
- [Configuration](/gateway/configuration) — config reference
|
||||
- [Remote Access](/gateway/remote) — other remote access patterns
|
||||
- [Tailscale](/gateway/tailscale) — simpler alternative for tailnet-only access
|
||||
Reference in New Issue
Block a user