Gateway runbook

Use this page for day-1 startup and day-2 operations of the Gateway service.

5-minute local startup

text
Copy
Healthy baseline: `Runtime: running`, `Connectivity probe: ok`, and `Capability: ...` that matches what you expect. Use `openclaw gateway status --require-rpc` when you need read-scope RPC proof, not just reachability.

text
Copy
With a reachable gateway this runs live per-account channel probes and optional audits.
If the gateway is unreachable, the CLI falls back to config-only channel summaries instead
of live probe output.

Runtime model

• One always-on process for routing, control plane, and channel connections.
• Single multiplexed port for:
  • WebSocket control/RPC
  • HTTP APIs, OpenAI compatible (
    text

    Copy

    /v1/models
    ,
    text

    Copy

    /v1/embeddings
    ,
    text

    Copy

    /v1/chat/completions
    ,
    text

    Copy

    /v1/responses
    ,
    text

    Copy

    /tools/invoke
    )
  • Control UI and hooks
• Default bind mode:
  text

  Copy

  loopback
  .
• Auth is required by default. Shared-secret setups use
  text

  Copy

  gateway.auth.token
  /
  text

  Copy

  gateway.auth.password
  (or
  text

  Copy

  OPENCLAW_GATEWAY_TOKEN
  /
  text

  Copy

  OPENCLAW_GATEWAY_PASSWORD
  ), and non-loopback reverse-proxy setups can use
  text

  Copy

  gateway.auth.mode: "trusted-proxy"
  .

OpenAI-compatible endpoints

OpenClaw’s highest-leverage compatibility surface is now:

• text

  Copy

  GET /v1/models
• text

  Copy

  GET /v1/models/{id}
• text

  Copy

  POST /v1/embeddings
• text

  Copy

  POST /v1/chat/completions
• text

  Copy

  POST /v1/responses

Why this set matters:

• Most Open WebUI, LobeChat, and LibreChat integrations probe
  text

  Copy

  /v1/models
  first.
• Many RAG and memory pipelines expect
  text

  Copy

  /v1/embeddings
  .
• Agent-native clients increasingly prefer
  text

  Copy

  /v1/responses
  .

Planning note:

• text

  Copy

  /v1/models
  is agent-first: it returns
  text

  Copy

  openclaw
  ,
  text

  Copy

  openclaw/default
  , and
  text

  Copy

  openclaw/<agentId>
  .
• text

  Copy

  openclaw/default
  is the stable alias that always maps to the configured default agent.
• Use
  text

  Copy

  x-openclaw-model
  when you want a backend provider/model override; otherwise the selected agent's normal model and embedding setup stays in control.

All of these run on the main Gateway port and use the same trusted operator auth boundary as the rest of the Gateway HTTP API.

Port and bind precedence

Installed gateway services record the resolved

Gateway startup uses the same effective port and bind when it seeds local Control UI origins for non-loopback binds. For example,

Hot reload modes

Operator command set

bash
Copy
openclaw gateway status
openclaw gateway status --deep   # adds a system-level service scan
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw secrets reload
openclaw logs --follow
openclaw doctor

Multiple gateways (same host)

Most installs should run one gateway per machine. A single gateway can host multiple agents and channels.

You only need multiple gateways when you intentionally want isolation or a rescue bot.

Useful checks:

bash
Copy
openclaw gateway status --deep
openclaw gateway probe

What to expect:

• text

  Copy

  gateway status --deep
  can report
  text

  Copy

  Other gateway-like services detected (best effort)
  and print cleanup hints when stale launchd/systemd/schtasks installs are still around.
• text

  Copy

  gateway probe
  can warn about
  text

  Copy

  multiple reachable gateways
  when more than one target answers.
• If that is intentional, isolate ports, config/state, and workspace roots per gateway.

Checklist per instance:

• Unique
  text

  Copy

  gateway.port
• Unique
  text

  Copy

  OPENCLAW_CONFIG_PATH
• Unique
  text

  Copy

  OPENCLAW_STATE_DIR
• Unique
  text

  Copy

  agents.defaults.workspace

Example:

bash
Copy
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

Detailed setup: /gateway/multiple-gateways.

VoiceClaw real-time brain endpoint

OpenClaw exposes a VoiceClaw-compatible real-time WebSocket endpoint at

The endpoint uses Gemini Live for real-time audio and calls OpenClaw as the brain by exposing OpenClaw tools directly to Gemini Live. Tool calls return an immediate

Real-time brain access runs owner-authorized OpenClaw agent commands. Keep

For an isolated test gateway, run a separate instance with its own port, config, and state:

bash
Copy
OPENCLAW_CONFIG_PATH=/path/to/openclaw-realtime/openclaw.json \
OPENCLAW_STATE_DIR=/path/to/openclaw-realtime/state \
OPENCLAW_SKIP_CHANNELS=1 \
GEMINI_API_KEY=... \
openclaw gateway --port 19789

Then configure VoiceClaw to use:

text
Copy
ws://127.0.0.1:19789/voiceclaw/realtime

Remote access

Preferred: Tailscale/VPN. Fallback: SSH tunnel.

bash
Copy
ssh -N -L 18789:127.0.0.1:18789 user@host

Then connect clients locally to

See: Remote Gateway, Authentication, Tailscale.

Supervision and service lifecycle

Use supervised runs for production-like reliability.

text
Copy
Use `openclaw gateway restart` for restarts. Do not chain `openclaw gateway stop` and `openclaw gateway start`; on macOS, `gateway stop` intentionally disables the LaunchAgent before stopping it.

LaunchAgent labels are `ai.openclaw.gateway` (default) or `ai.openclaw.<profile>` (named profile). `openclaw doctor` audits and repairs service config drift.

text
Copy
For persistence after logout, enable lingering:

```bash}
sudo loginctl enable-linger <user>
```

Manual user-unit example when you need a custom install path:

```ini}
[Unit]
Description=OpenClaw Gateway
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/openclaw gateway --port 18789
Restart=always
RestartSec=5
TimeoutStopSec=30
TimeoutStartSec=30
SuccessExitStatus=0 143
KillMode=control-group

[Install]
WantedBy=default.target
```

text
Copy
Native Windows managed startup uses a Scheduled Task named `OpenClaw Gateway`
(or `OpenClaw Gateway (<profile>)` for named profiles). If Scheduled Task
creation is denied, OpenClaw falls back to a per-user Startup-folder launcher
that points at `gateway.cmd` inside the state directory.

text
Copy
```bash}
sudo systemctl daemon-reload
sudo systemctl enable --now openclaw-gateway[-<profile>].service
```

Use the same service body as the user unit, but install it under
`/etc/systemd/system/openclaw-gateway[-<profile>].service` and adjust
`ExecStart=` if your `openclaw` binary lives elsewhere.

Do not also let `openclaw doctor --fix` install a user-level gateway service for the same profile/port. Doctor refuses that automatic install when it finds a system-level OpenClaw gateway service; use `OPENCLAW_SERVICE_REPAIR_POLICY=external` when the system unit owns the lifecycle.

Dev profile quick path

bash
Copy
openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status

Defaults include isolated state/config and base gateway port

Protocol quick reference (operator view)

• First client frame must be
  text

  Copy

  connect
  .
• Gateway returns
  text

  Copy

  hello-ok
  snapshot (
  text

  Copy

  presence
  ,
  text

  Copy

  health
  ,
  text

  Copy

  stateVersion
  ,
  text

  Copy

  uptimeMs
  , limits/policy).
• text

  Copy

  hello-ok.features.methods
  /
  text

  Copy

  events
  are a conservative discovery list, not a generated dump of every callable helper route.
• Requests:
  text

  Copy

  req(method, params)
  →
  text

  Copy

  res(ok/payload|error)
  .
• Common events include
  text

  Copy

  connect.challenge
  ,
  text

  Copy

  agent
  ,
  text

  Copy

  chat
  ,
  text

  Copy

  session.message
  ,
  text

  Copy

  session.tool
  ,
  text

  Copy

  sessions.changed
  ,
  text

  Copy

  presence
  ,
  text

  Copy

  tick
  ,
  text

  Copy

  health
  ,
  text

  Copy

  heartbeat
  , pairing/approval lifecycle events, and
  text

  Copy

  shutdown
  .

Agent runs are two-stage:

1. Immediate accepted ack (
   text

   Copy

   status:"accepted"
   )
2. Final completion response (
   text

   Copy

   status:"ok"|"error"
   ), with streamed
   text

   Copy

   agent
   events in between.

See full protocol docs: Gateway Protocol.

Operational checks

Liveness

• Open WS and send
  text

  Copy

  connect
  .
• Expect
  text

  Copy

  hello-ok
  response with snapshot.

Readiness

bash
Copy
openclaw gateway status
openclaw channels status --probe
openclaw health

Gap recovery

Events are not replayed. On sequence gaps, refresh state (

Common failure signatures

For full diagnosis ladders, use 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
  text

  Copy

  shutdown
  event before socket close.

Related:

• Troubleshooting
• Background Process
• Configuration
• Health
• Doctor
• Authentication

Related

• Configuration
• Gateway troubleshooting
• Remote access
• Secrets management