mirror of
https://github.com/openclaw/openclaw.git
synced 2026-03-12 07:20:45 +00:00
docs: modernize gateway configuration page (Phase 1) (#14111)
* docs(configuration): split into overview + full reference with Mintlify components * docs(configuration): use tooltip for JSON5 format note * docs(configuration): fix Accordion closing tags inside list contexts * docs(configuration): expand intro to reflect full config surface * docs(configuration): trim intro to three concise bullets * docs(configuration-examples): revert all branch changes * docs(configuration): improve hot-reload section with tabs and accordion * docs(configuration): uncramp hot-reload — subheadings, bullet list, warning * docs(configuration): restore hot-apply vs restart table * docs(configuration): fix hot-reload table against codebase * docs: add configuration-reference.md — full field-by-field reference * docs(gateway): refresh runbook and align config reference * docs: include pending docs updates and install graphic
This commit is contained in:
Seb Slight
1
.gitignore
vendored
1
.gitignore
vendored
@@ -69,6 +69,7 @@ apps/ios/*.mobileprovision
|
|||||||
|
|
||||||
# Local untracked files
|
# Local untracked files
|
||||||
.local/
|
.local/
|
||||||
|
docs/.local/
|
||||||
IDENTITY.md
|
IDENTITY.md
|
||||||
USER.md
|
USER.md
|
||||||
.tgz
|
.tgz
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
{
|
{
|
||||||
"globs": ["docs/**/*.md", "docs/**/*.mdx", "README.md"],
|
"globs": ["docs/**/*.md", "docs/**/*.mdx", "README.md"],
|
||||||
"ignores": ["docs/zh-CN/**", "docs/.i18n/**", "docs/reference/templates/**"],
|
"ignores": ["docs/zh-CN/**", "docs/.i18n/**", "docs/reference/templates/**", "**/.local/**"],
|
||||||
"config": {
|
"config": {
|
||||||
"default": true,
|
"default": true,
|
||||||
|
|
||||||
|
|||||||
1
docs/assets/install-script.svg
Normal file
1
docs/assets/install-script.svg
Normal file
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 295 KiB |
@@ -24,6 +24,14 @@
|
|||||||
"dark": "#FF5A36",
|
"dark": "#FF5A36",
|
||||||
"light": "#FF8A6B"
|
"light": "#FF8A6B"
|
||||||
},
|
},
|
||||||
|
"styling": {
|
||||||
|
"codeblocks": {
|
||||||
|
"theme": {
|
||||||
|
"dark": "min-dark",
|
||||||
|
"light": "min-light"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
"navbar": {
|
"navbar": {
|
||||||
"links": [
|
"links": [
|
||||||
{
|
{
|
||||||
@@ -1100,6 +1108,7 @@
|
|||||||
"group": "Configuration and operations",
|
"group": "Configuration and operations",
|
||||||
"pages": [
|
"pages": [
|
||||||
"gateway/configuration",
|
"gateway/configuration",
|
||||||
|
"gateway/configuration-reference",
|
||||||
"gateway/configuration-examples",
|
"gateway/configuration-examples",
|
||||||
"gateway/authentication",
|
"gateway/authentication",
|
||||||
"gateway/health",
|
"gateway/health",
|
||||||
|
|||||||
@@ -67,7 +67,11 @@ Save to `~/.openclaw/openclaw.json` and you can DM the bot from that number.
|
|||||||
// Auth profile metadata (secrets live in auth-profiles.json)
|
// Auth profile metadata (secrets live in auth-profiles.json)
|
||||||
auth: {
|
auth: {
|
||||||
profiles: {
|
profiles: {
|
||||||
"anthropic:me@example.com": { provider: "anthropic", mode: "oauth", email: "me@example.com" },
|
"anthropic:me@example.com": {
|
||||||
|
provider: "anthropic",
|
||||||
|
mode: "oauth",
|
||||||
|
email: "me@example.com",
|
||||||
|
},
|
||||||
"anthropic:work": { provider: "anthropic", mode: "api_key" },
|
"anthropic:work": { provider: "anthropic", mode: "api_key" },
|
||||||
"openai:default": { provider: "openai", mode: "api_key" },
|
"openai:default": { provider: "openai", mode: "api_key" },
|
||||||
"openai-codex:default": { provider: "openai-codex", mode: "oauth" },
|
"openai-codex:default": { provider: "openai-codex", mode: "oauth" },
|
||||||
@@ -375,7 +379,10 @@ Save to `~/.openclaw/openclaw.json` and you can DM the bot from that number.
|
|||||||
to: "+15555550123",
|
to: "+15555550123",
|
||||||
thinking: "low",
|
thinking: "low",
|
||||||
timeoutSeconds: 300,
|
timeoutSeconds: 300,
|
||||||
transform: { module: "./transforms/gmail.js", export: "transformGmail" },
|
transform: {
|
||||||
|
module: "./transforms/gmail.js",
|
||||||
|
export: "transformGmail",
|
||||||
|
},
|
||||||
},
|
},
|
||||||
],
|
],
|
||||||
gmail: {
|
gmail: {
|
||||||
|
|||||||
2318
docs/gateway/configuration-reference.md
Normal file
2318
docs/gateway/configuration-reference.md
Normal file
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -5,120 +5,173 @@ read_when:
|
|||||||
title: "Gateway Runbook"
|
title: "Gateway Runbook"
|
||||||
---
|
---
|
||||||
|
|
||||||
# Gateway service runbook
|
# Gateway runbook
|
||||||
|
|
||||||
Last updated: 2025-12-09
|
Use this page for day-1 startup and day-2 operations of the Gateway service.
|
||||||
|
|
||||||
## What it is
|
<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>
|
||||||
|
</CardGroup>
|
||||||
|
|
||||||
- The always-on process that owns the single Baileys/Telegram connection and the control/event plane.
|
## 5-minute local startup
|
||||||
- Replaces the legacy `gateway` command. CLI entry point: `openclaw gateway`.
|
|
||||||
- Runs until stopped; exits non-zero on fatal errors so the supervisor restarts it.
|
|
||||||
|
|
||||||
## How to run (local)
|
<Steps>
|
||||||
|
<Step title="Start the Gateway">
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
openclaw gateway --port 18789
|
openclaw gateway --port 18789
|
||||||
# for full debug/trace logs in stdio:
|
# debug/trace mirrored to stdio
|
||||||
openclaw gateway --port 18789 --verbose
|
openclaw gateway --port 18789 --verbose
|
||||||
# if the port is busy, terminate listeners then start:
|
# force-kill listener on selected port, then start
|
||||||
openclaw gateway --force
|
openclaw gateway --force
|
||||||
# dev loop (auto-reload on TS changes):
|
|
||||||
pnpm gateway:watch
|
|
||||||
```
|
```
|
||||||
|
|
||||||
- Config hot reload watches `~/.openclaw/openclaw.json` (or `OPENCLAW_CONFIG_PATH`).
|
</Step>
|
||||||
- Default mode: `gateway.reload.mode="hybrid"` (hot-apply safe changes, restart on critical).
|
|
||||||
- Hot reload uses in-process restart via **SIGUSR1** when needed.
|
<Step title="Verify service health">
|
||||||
- Disable with `gateway.reload.mode="off"`.
|
|
||||||
- Binds WebSocket control plane to `127.0.0.1:<port>` (default 18789).
|
```bash
|
||||||
- The same port also serves HTTP (control UI, hooks, A2UI). Single-port multiplex.
|
openclaw gateway status
|
||||||
- OpenAI Chat Completions (HTTP): [`/v1/chat/completions`](/gateway/openai-http-api).
|
openclaw status
|
||||||
- OpenResponses (HTTP): [`/v1/responses`](/gateway/openresponses-http-api).
|
openclaw logs --follow
|
||||||
- Tools Invoke (HTTP): [`/tools/invoke`](/gateway/tools-invoke-http-api).
|
```
|
||||||
- Starts a Canvas file server by default on `canvasHost.port` (default `18793`), serving `http://<gateway-host>:18793/__openclaw__/canvas/` from `~/.openclaw/workspace/canvas`. Disable with `canvasHost.enabled=false` or `OPENCLAW_SKIP_CANVAS_HOST=1`.
|
|
||||||
- Logs to stdout; use launchd/systemd to keep it alive and rotate logs.
|
Healthy baseline: `Runtime: running` and `RPC probe: ok`.
|
||||||
- Pass `--verbose` to mirror debug logging (handshakes, req/res, events) from the log file into stdio when troubleshooting.
|
|
||||||
- `--force` uses `lsof` to find listeners on the chosen port, sends SIGTERM, logs what it killed, then starts the gateway (fails fast if `lsof` is missing).
|
</Step>
|
||||||
- If you run under a supervisor (launchd/systemd/mac app child-process mode), a stop/restart typically sends **SIGTERM**; older builds may surface this as `pnpm` `ELIFECYCLE` exit code **143** (SIGTERM), which is a normal shutdown, not a crash.
|
|
||||||
- **SIGUSR1** triggers an in-process restart when authorized (gateway tool/config apply/update, or enable `commands.restart` for manual restarts).
|
<Step title="Validate channel readiness">
|
||||||
- Gateway auth is required by default: set `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`) or `gateway.auth.password`. Clients must send `connect.params.auth.token/password` unless using Tailscale Serve identity.
|
|
||||||
- The wizard now generates a token by default, even on loopback.
|
```bash
|
||||||
- Port precedence: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > default `18789`.
|
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 logs --follow
|
||||||
|
openclaw doctor
|
||||||
|
```
|
||||||
|
|
||||||
## Remote access
|
## Remote access
|
||||||
|
|
||||||
- Tailscale/VPN preferred; otherwise SSH tunnel:
|
Preferred: Tailscale/VPN.
|
||||||
|
Fallback: SSH tunnel.
|
||||||
```bash
|
|
||||||
ssh -N -L 18789:127.0.0.1:18789 user@host
|
|
||||||
```
|
|
||||||
|
|
||||||
- Clients then connect to `ws://127.0.0.1:18789` through the tunnel.
|
|
||||||
- If a token is configured, clients must include it in `connect.params.auth.token` even over the tunnel.
|
|
||||||
|
|
||||||
## Multiple gateways (same host)
|
|
||||||
|
|
||||||
Usually unnecessary: one Gateway can serve multiple messaging channels and agents. Use multiple Gateways only for redundancy or strict isolation (ex: rescue bot).
|
|
||||||
|
|
||||||
Supported if you isolate state + config and use unique ports. Full guide: [Multiple gateways](/gateway/multiple-gateways).
|
|
||||||
|
|
||||||
Service names are profile-aware:
|
|
||||||
|
|
||||||
- macOS: `bot.molt.<profile>` (legacy `com.openclaw.*` may still exist)
|
|
||||||
- Linux: `openclaw-gateway-<profile>.service`
|
|
||||||
- Windows: `OpenClaw Gateway (<profile>)`
|
|
||||||
|
|
||||||
Install metadata is embedded in the service config:
|
|
||||||
|
|
||||||
- `OPENCLAW_SERVICE_MARKER=openclaw`
|
|
||||||
- `OPENCLAW_SERVICE_KIND=gateway`
|
|
||||||
- `OPENCLAW_SERVICE_VERSION=<version>`
|
|
||||||
|
|
||||||
Rescue-Bot Pattern: keep a second Gateway isolated with its own profile, state dir, workspace, and base port spacing. Full guide: [Rescue-bot guide](/gateway/multiple-gateways#rescue-bot-guide).
|
|
||||||
|
|
||||||
### Dev profile (`--dev`)
|
|
||||||
|
|
||||||
Fast path: run a fully-isolated dev instance (config/state/workspace) without touching your primary setup.
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
openclaw --dev setup
|
ssh -N -L 18789:127.0.0.1:18789 user@host
|
||||||
openclaw --dev gateway --allow-unconfigured
|
|
||||||
# then target the dev instance:
|
|
||||||
openclaw --dev status
|
|
||||||
openclaw --dev health
|
|
||||||
```
|
```
|
||||||
|
|
||||||
Defaults (can be overridden via env/flags/config):
|
Then connect clients to `ws://127.0.0.1:18789` locally.
|
||||||
|
|
||||||
- `OPENCLAW_STATE_DIR=~/.openclaw-dev`
|
<Warning>
|
||||||
- `OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json`
|
If gateway auth is configured, clients still must send auth (`token`/`password`) even over SSH tunnels.
|
||||||
- `OPENCLAW_GATEWAY_PORT=19001` (Gateway WS + HTTP)
|
</Warning>
|
||||||
- browser control service port = `19003` (derived: `gateway.port+2`, loopback only)
|
|
||||||
- `canvasHost.port=19005` (derived: `gateway.port+4`)
|
|
||||||
- `agents.defaults.workspace` default becomes `~/.openclaw/workspace-dev` when you run `setup`/`onboard` under `--dev`.
|
|
||||||
|
|
||||||
Derived ports (rules of thumb):
|
See: [Remote Gateway](/gateway/remote), [Authentication](/gateway/authentication), [Tailscale](/gateway/tailscale).
|
||||||
|
|
||||||
- Base port = `gateway.port` (or `OPENCLAW_GATEWAY_PORT` / `--port`)
|
## Supervision and service lifecycle
|
||||||
- browser control service port = base + 2 (loopback only)
|
|
||||||
- `canvasHost.port = base + 4` (or `OPENCLAW_CANVAS_HOST_PORT` / config override)
|
Use supervised runs for production-like reliability.
|
||||||
- Browser profile CDP ports auto-allocate from `browser.controlPort + 9 .. + 108` (persisted per profile).
|
|
||||||
|
<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:
|
Checklist per instance:
|
||||||
|
|
||||||
- unique `gateway.port`
|
- Unique `gateway.port`
|
||||||
- unique `OPENCLAW_CONFIG_PATH`
|
- Unique `OPENCLAW_CONFIG_PATH`
|
||||||
- unique `OPENCLAW_STATE_DIR`
|
- Unique `OPENCLAW_STATE_DIR`
|
||||||
- unique `agents.defaults.workspace`
|
- Unique `agents.defaults.workspace`
|
||||||
- separate WhatsApp numbers (if using WA)
|
|
||||||
|
|
||||||
Service install per profile:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
openclaw --profile main gateway install
|
|
||||||
openclaw --profile rescue gateway install
|
|
||||||
```
|
|
||||||
|
|
||||||
Example:
|
Example:
|
||||||
|
|
||||||
@@ -127,204 +180,75 @@ OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a opencla
|
|||||||
OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002
|
OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002
|
||||||
```
|
```
|
||||||
|
|
||||||
## Protocol (operator view)
|
See: [Multiple gateways](/gateway/multiple-gateways).
|
||||||
|
|
||||||
- Full docs: [Gateway protocol](/gateway/protocol) and [Bridge protocol (legacy)](/gateway/bridge-protocol).
|
### Dev profile quick path
|
||||||
- Mandatory first frame from client: `req {type:"req", id, method:"connect", params:{minProtocol,maxProtocol,client:{id,displayName?,version,platform,deviceFamily?,modelIdentifier?,mode,instanceId?}, caps, auth?, locale?, userAgent? } }`.
|
|
||||||
- Gateway replies `res {type:"res", id, ok:true, payload:hello-ok }` (or `ok:false` with an error, then closes).
|
|
||||||
- After handshake:
|
|
||||||
- Requests: `{type:"req", id, method, params}` → `{type:"res", id, ok, payload|error}`
|
|
||||||
- Events: `{type:"event", event, payload, seq?, stateVersion?}`
|
|
||||||
- Structured presence entries: `{host, ip, version, platform?, deviceFamily?, modelIdentifier?, mode, lastInputSeconds?, ts, reason?, tags?[], instanceId? }` (for WS clients, `instanceId` comes from `connect.client.instanceId`).
|
|
||||||
- `agent` responses are two-stage: first `res` ack `{runId,status:"accepted"}`, then a final `res` `{runId,status:"ok"|"error",summary}` after the run finishes; streamed output arrives as `event:"agent"`.
|
|
||||||
|
|
||||||
## Methods (initial set)
|
|
||||||
|
|
||||||
- `health` — full health snapshot (same shape as `openclaw health --json`).
|
|
||||||
- `status` — short summary.
|
|
||||||
- `system-presence` — current presence list.
|
|
||||||
- `system-event` — post a presence/system note (structured).
|
|
||||||
- `send` — send a message via the active channel(s).
|
|
||||||
- `agent` — run an agent turn (streams events back on same connection).
|
|
||||||
- `node.list` — list paired + currently-connected nodes (includes `caps`, `deviceFamily`, `modelIdentifier`, `paired`, `connected`, and advertised `commands`).
|
|
||||||
- `node.describe` — describe a node (capabilities + supported `node.invoke` commands; works for paired nodes and for currently-connected unpaired nodes).
|
|
||||||
- `node.invoke` — invoke a command on a node (e.g. `canvas.*`, `camera.*`).
|
|
||||||
- `node.pair.*` — pairing lifecycle (`request`, `list`, `approve`, `reject`, `verify`).
|
|
||||||
|
|
||||||
See also: [Presence](/concepts/presence) for how presence is produced/deduped and why a stable `client.instanceId` matters.
|
|
||||||
|
|
||||||
## Events
|
|
||||||
|
|
||||||
- `agent` — streamed tool/output events from the agent run (seq-tagged).
|
|
||||||
- `presence` — presence updates (deltas with stateVersion) pushed to all connected clients.
|
|
||||||
- `tick` — periodic keepalive/no-op to confirm liveness.
|
|
||||||
- `shutdown` — Gateway is exiting; payload includes `reason` and optional `restartExpectedMs`. Clients should reconnect.
|
|
||||||
|
|
||||||
## WebChat integration
|
|
||||||
|
|
||||||
- WebChat is a native SwiftUI UI that talks directly to the Gateway WebSocket for history, sends, abort, and events.
|
|
||||||
- Remote use goes through the same SSH/Tailscale tunnel; if a gateway token is configured, the client includes it during `connect`.
|
|
||||||
- macOS app connects via a single WS (shared connection); it hydrates presence from the initial snapshot and listens for `presence` events to update the UI.
|
|
||||||
|
|
||||||
## Typing and validation
|
|
||||||
|
|
||||||
- Server validates every inbound frame with AJV against JSON Schema emitted from the protocol definitions.
|
|
||||||
- Clients (TS/Swift) consume generated types (TS directly; Swift via the repo’s generator).
|
|
||||||
- Protocol definitions are the source of truth; regenerate schema/models with:
|
|
||||||
- `pnpm protocol:gen`
|
|
||||||
- `pnpm protocol:gen:swift`
|
|
||||||
|
|
||||||
## Connection snapshot
|
|
||||||
|
|
||||||
- `hello-ok` includes a `snapshot` with `presence`, `health`, `stateVersion`, and `uptimeMs` plus `policy {maxPayload,maxBufferedBytes,tickIntervalMs}` so clients can render immediately without extra requests.
|
|
||||||
- `health`/`system-presence` remain available for manual refresh, but are not required at connect time.
|
|
||||||
|
|
||||||
## Error codes (res.error shape)
|
|
||||||
|
|
||||||
- Errors use `{ code, message, details?, retryable?, retryAfterMs? }`.
|
|
||||||
- Standard codes:
|
|
||||||
- `NOT_LINKED` — WhatsApp not authenticated.
|
|
||||||
- `AGENT_TIMEOUT` — agent did not respond within the configured deadline.
|
|
||||||
- `INVALID_REQUEST` — schema/param validation failed.
|
|
||||||
- `UNAVAILABLE` — Gateway is shutting down or a dependency is unavailable.
|
|
||||||
|
|
||||||
## Keepalive behavior
|
|
||||||
|
|
||||||
- `tick` events (or WS ping/pong) are emitted periodically so clients know the Gateway is alive even when no traffic occurs.
|
|
||||||
- Send/agent acknowledgements remain separate responses; do not overload ticks for sends.
|
|
||||||
|
|
||||||
## Replay / gaps
|
|
||||||
|
|
||||||
- Events are not replayed. Clients detect seq gaps and should refresh (`health` + `system-presence`) before continuing. WebChat and macOS clients now auto-refresh on gap.
|
|
||||||
|
|
||||||
## Supervision (macOS example)
|
|
||||||
|
|
||||||
- Use launchd to keep the service alive:
|
|
||||||
- Program: path to `openclaw`
|
|
||||||
- Arguments: `gateway`
|
|
||||||
- KeepAlive: true
|
|
||||||
- StandardOut/Err: file paths or `syslog`
|
|
||||||
- On failure, launchd restarts; fatal misconfig should keep exiting so the operator notices.
|
|
||||||
- LaunchAgents are per-user and require a logged-in session; for headless setups use a custom LaunchDaemon (not shipped).
|
|
||||||
- `openclaw gateway install` writes `~/Library/LaunchAgents/bot.molt.gateway.plist`
|
|
||||||
(or `bot.molt.<profile>.plist`; legacy `com.openclaw.*` is cleaned up).
|
|
||||||
- `openclaw doctor` audits the LaunchAgent config and can update it to current defaults.
|
|
||||||
|
|
||||||
## Gateway service management (CLI)
|
|
||||||
|
|
||||||
Use the Gateway CLI for install/start/stop/restart/status:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
openclaw gateway status
|
openclaw --dev setup
|
||||||
openclaw gateway install
|
openclaw --dev gateway --allow-unconfigured
|
||||||
openclaw gateway stop
|
openclaw --dev status
|
||||||
openclaw gateway restart
|
|
||||||
openclaw logs --follow
|
|
||||||
```
|
```
|
||||||
|
|
||||||
Notes:
|
Defaults include isolated state/config and base gateway port `19001`.
|
||||||
|
|
||||||
- `gateway status` probes the Gateway RPC by default using the service’s resolved port/config (override with `--url`).
|
## Protocol quick reference (operator view)
|
||||||
- `gateway status --deep` adds system-level scans (LaunchDaemons/system units).
|
|
||||||
- `gateway status --no-probe` skips the RPC probe (useful when networking is down).
|
|
||||||
- `gateway status --json` is stable for scripts.
|
|
||||||
- `gateway status` reports **supervisor runtime** (launchd/systemd running) separately from **RPC reachability** (WS connect + status RPC).
|
|
||||||
- `gateway status` prints config path + probe target to avoid “localhost vs LAN bind” confusion and profile mismatches.
|
|
||||||
- `gateway status` includes the last gateway error line when the service looks running but the port is closed.
|
|
||||||
- `logs` tails the Gateway file log via RPC (no manual `tail`/`grep` needed).
|
|
||||||
- If other gateway-like services are detected, the CLI warns unless they are OpenClaw profile services.
|
|
||||||
We still recommend **one gateway per machine** for most setups; use isolated profiles/ports for redundancy or a rescue bot. See [Multiple gateways](/gateway/multiple-gateways).
|
|
||||||
- Cleanup: `openclaw gateway uninstall` (current service) and `openclaw doctor` (legacy migrations).
|
|
||||||
- `gateway install` is a no-op when already installed; use `openclaw gateway install --force` to reinstall (profile/env/path changes).
|
|
||||||
|
|
||||||
Bundled mac app:
|
- 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`.
|
||||||
|
|
||||||
- OpenClaw.app can bundle a Node-based gateway relay and install a per-user LaunchAgent labeled
|
Agent runs are two-stage:
|
||||||
`bot.molt.gateway` (or `bot.molt.<profile>`; legacy `com.openclaw.*` labels still unload cleanly).
|
|
||||||
- To stop it cleanly, use `openclaw gateway stop` (or `launchctl bootout gui/$UID/bot.molt.gateway`).
|
|
||||||
- To restart, use `openclaw gateway restart` (or `launchctl kickstart -k gui/$UID/bot.molt.gateway`).
|
|
||||||
- `launchctl` only works if the LaunchAgent is installed; otherwise use `openclaw gateway install` first.
|
|
||||||
- Replace the label with `bot.molt.<profile>` when running a named profile.
|
|
||||||
|
|
||||||
## Supervision (systemd user unit)
|
1. Immediate accepted ack (`status:"accepted"`)
|
||||||
|
2. Final completion response (`status:"ok"|"error"`), with streamed `agent` events in between.
|
||||||
|
|
||||||
OpenClaw installs a **systemd user service** by default on Linux/WSL2. We
|
See full protocol docs: [Gateway Protocol](/gateway/protocol).
|
||||||
recommend user services for single-user machines (simpler env, per-user config).
|
|
||||||
Use a **system service** for multi-user or always-on servers (no lingering
|
|
||||||
required, shared supervision).
|
|
||||||
|
|
||||||
`openclaw gateway install` writes the user unit. `openclaw doctor` audits the
|
|
||||||
unit and can update it to match the current recommended defaults.
|
|
||||||
|
|
||||||
Create `~/.config/systemd/user/openclaw-gateway[-<profile>].service`:
|
|
||||||
|
|
||||||
```
|
|
||||||
[Unit]
|
|
||||||
Description=OpenClaw Gateway (profile: <profile>, v<version>)
|
|
||||||
After=network-online.target
|
|
||||||
Wants=network-online.target
|
|
||||||
|
|
||||||
[Service]
|
|
||||||
ExecStart=/usr/local/bin/openclaw gateway --port 18789
|
|
||||||
Restart=always
|
|
||||||
RestartSec=5
|
|
||||||
Environment=OPENCLAW_GATEWAY_TOKEN=
|
|
||||||
WorkingDirectory=/home/youruser
|
|
||||||
|
|
||||||
[Install]
|
|
||||||
WantedBy=default.target
|
|
||||||
```
|
|
||||||
|
|
||||||
Enable lingering (required so the user service survives logout/idle):
|
|
||||||
|
|
||||||
```
|
|
||||||
sudo loginctl enable-linger youruser
|
|
||||||
```
|
|
||||||
|
|
||||||
Onboarding runs this on Linux/WSL2 (may prompt for sudo; writes `/var/lib/systemd/linger`).
|
|
||||||
Then enable the service:
|
|
||||||
|
|
||||||
```
|
|
||||||
systemctl --user enable --now openclaw-gateway[-<profile>].service
|
|
||||||
```
|
|
||||||
|
|
||||||
**Alternative (system service)** - for always-on or multi-user servers, you can
|
|
||||||
install a systemd **system** unit instead of a user unit (no lingering needed).
|
|
||||||
Create `/etc/systemd/system/openclaw-gateway[-<profile>].service` (copy the unit above,
|
|
||||||
switch `WantedBy=multi-user.target`, set `User=` + `WorkingDirectory=`), then:
|
|
||||||
|
|
||||||
```
|
|
||||||
sudo systemctl daemon-reload
|
|
||||||
sudo systemctl enable --now openclaw-gateway[-<profile>].service
|
|
||||||
```
|
|
||||||
|
|
||||||
## Windows (WSL2)
|
|
||||||
|
|
||||||
Windows installs should use **WSL2** and follow the Linux systemd section above.
|
|
||||||
|
|
||||||
## Operational checks
|
## Operational checks
|
||||||
|
|
||||||
- Liveness: open WS and send `req:connect` → expect `res` with `payload.type="hello-ok"` (with snapshot).
|
### Liveness
|
||||||
- Readiness: call `health` → expect `ok: true` and a linked channel in `linkChannel` (when applicable).
|
|
||||||
- Debug: subscribe to `tick` and `presence` events; ensure `status` shows linked/auth age; presence entries show Gateway host and connected clients.
|
- 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
|
## Safety guarantees
|
||||||
|
|
||||||
- Assume one Gateway per host by default; if you run multiple profiles, isolate ports/state and target the right instance.
|
- Gateway protocol clients fail fast when Gateway is unavailable (no implicit direct-channel fallback).
|
||||||
- No fallback to direct Baileys connections; if the Gateway is down, sends fail fast.
|
- Invalid/non-connect first frames are rejected and closed.
|
||||||
- Non-connect first frames or malformed JSON are rejected and the socket is closed.
|
- Graceful shutdown emits `shutdown` event before socket close.
|
||||||
- Graceful shutdown: emit `shutdown` event before closing; clients must handle close + reconnect.
|
|
||||||
|
|
||||||
## CLI helpers
|
---
|
||||||
|
|
||||||
- `openclaw gateway health|status` — request health/status over the Gateway WS.
|
Related:
|
||||||
- `openclaw message send --target <num> --message "hi" [--media ...]` — send via Gateway (idempotent for WhatsApp).
|
|
||||||
- `openclaw agent --message "hi" --to <num>` — run an agent turn (waits for final by default).
|
|
||||||
- `openclaw gateway call <method> --params '{"k":"v"}'` — raw method invoker for debugging.
|
|
||||||
- `openclaw gateway stop|restart` — stop/restart the supervised gateway service (launchd/systemd).
|
|
||||||
- Gateway helper subcommands assume a running gateway on `--url`; they no longer auto-spawn one.
|
|
||||||
|
|
||||||
## Migration guidance
|
- [Troubleshooting](/gateway/troubleshooting)
|
||||||
|
- [Background Process](/gateway/background-process)
|
||||||
- Retire uses of `openclaw gateway` and the legacy TCP control port.
|
- [Configuration](/gateway/configuration)
|
||||||
- Update clients to speak the WS protocol with mandatory connect and structured presence.
|
- [Health](/gateway/health)
|
||||||
|
- [Doctor](/gateway/doctor)
|
||||||
|
- [Authentication](/gateway/authentication)
|
||||||
|
|||||||
@@ -34,6 +34,11 @@ Check your Node version with `node --version` if you are unsure.
|
|||||||
```bash
|
```bash
|
||||||
curl -fsSL https://openclaw.ai/install.sh | bash
|
curl -fsSL https://openclaw.ai/install.sh | bash
|
||||||
```
|
```
|
||||||
|
<img
|
||||||
|
src="/assets/install-script.svg"
|
||||||
|
alt="Install Script Process"
|
||||||
|
className="rounded-lg"
|
||||||
|
/>
|
||||||
</Tab>
|
</Tab>
|
||||||
<Tab title="Windows (PowerShell)">
|
<Tab title="Windows (PowerShell)">
|
||||||
```powershell
|
```powershell
|
||||||
|
|||||||
Reference in New Issue
Block a user