LeoYeAI/agent-master-skills / skills/bengii-gemini-fix
openclaw
FlaggedComprehensive guide for installing, configuring, operating, and troubleshooting OpenClaw — a self-hosted, multi-channel AI agent gateway. Use when the user asks about OpenClaw setup, configuration, channel management (WhatsApp/Telegram/Discord/Slack/iMessage/etc.), model provider setup, Gateway operations, multi-agent routing, security hardening, troubleshooting, or any maintenance task related to their local OpenClaw installation. Also use when encountering errors from `openclaw` CLI commands or the Gateway daemon.
references/gateway_ops.md
View on GitHub# OpenClaw Gateway Operations Reference
## Table of Contents
- [Architecture](#architecture)
- [Starting the Gateway](#starting-the-gateway)
- [Service Management](#service-management)
- [Port and Bind Configuration](#port-and-bind-configuration)
- [Hot Reload](#hot-reload)
- [Remote Access](#remote-access)
- [Multiple Gateways](#multiple-gateways)
- [Health Checks](#health-checks)
- [Operator Commands](#operator-commands)
- [Gateway Protocol](#gateway-protocol)
- [Install / Update / Uninstall](#install--update--uninstall)
- [Troubleshooting](#troubleshooting)
## Architecture
- Single long-lived daemon owns all messaging surfaces
- One multiplexed port for WebSocket RPC, HTTP APIs, Control UI, and hooks
- One Gateway per host controls a single WhatsApp/Baileys session
- Canvas served at `/__openclaw__/canvas/` and `/__openclaw__/a2ui/` on same port
- Default bind: `127.0.0.1:18789` (loopback)
Components:
- **Gateway daemon**: provider connections, typed WS API, JSON Schema validation
- **Clients** (macOS app / CLI / web admin): one WS connection each
- **Nodes** (macOS / iOS / Android / headless): WS with `role: node`, expose device commands
- **WebChat**: static UI using Gateway WS API
## Starting the Gateway
```bash
# Foreground (dev/debug)
openclaw gateway --port 18789
openclaw gateway --port 18789 --verbose # Debug/trace to stdout
openclaw gateway --force # Kill existing listener first
# With auth
openclaw gateway --token <token>
openclaw gateway --password <password>
# With Tailscale
openclaw gateway --tailscale serve # Tailscale Serve
openclaw gateway --tailscale funnel # Tailscale Funnel (public)
# Dev profile (separate port 19001)
openclaw --dev gateway --allow-unconfigured
```
## Service Management
### macOS (launchd)
```bash
openclaw gateway install # Install launch agent (ai.openclaw.gateway)
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway status # Probe RPC
openclaw gateway uninstall
```
### Linux (systemd user)
```bash
openclaw gateway install
systemctl --user enable --now openclaw-gateway.service
openclaw gateway status
```
### Linux (system service)
```bash
sudo systemctl daemon-reload
sudo systemctl enable --now openclaw-gateway.service
sudo loginctl enable-linger <user> # Keep user service running
```
### Service Install Options
```bash
openclaw gateway install --port <port> --runtime <node|bun> --token <token> --force
```
Note: Node runtime recommended; Bun has WhatsApp/Telegram bugs.
## Port and Bind Configuration
Precedence (highest to lowest):
1. `--port` CLI flag
2. `OPENCLAW_GATEWAY_PORT` env var
3. `gateway.port` in config
4. Default: `18789`
Bind modes:
- `loopback` (default) — localhost only
- `tailnet` — Tailscale network only
- `lan` — local network
- `auto` — auto-detect
- `custom` — manual bind address
## Hot Reload
Config setting: `gateway.reload.mode`
| Mode | Behavior |
|---|---|
| `off` | No automatic reload |
| `hot` | Hot-apply supported changes without restart |
| `restart` | Full restart on config change |
| `hybrid` | Hot-apply what it can, restart for the rest |
What hot-applies: system prompt changes, model selection, tool config.
What needs restart: port/bind changes, channel add/remove, auth changes.
## Remote Access
### SSH Tunnel (simple)
```bash
ssh -N -L 18789:127.0.0.1:18789 user@host
```
Then connect clients to `ws://127.0.0.1:18789` with same token/password.
### Tailscale
```bash
openclaw gateway --tailscale serve # Private (tailnet only)
openclaw gateway --tailscale funnel # Public (internet-accessible)
```
### VPN
Any VPN that provides network-level access. Gateway auth still required.
## Multiple Gateways
Requirements per instance:
- Unique `gateway.port`
- Unique `OPENCLAW_CONFIG_PATH`
- Unique `OPENCLAW_STATE_DIR`
- Unique `agents.defaults.workspace`
```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
```
## Health Checks
### Liveness
Open WS → send `connect` → expect `hello-ok` response.
### Readiness
```bash
openclaw gateway status # Runtime: running, RPC probe: ok
openclaw channels status --probe # Connected/ready channels
openclaw health # Overall health check
```
### Operational Checks
```bash
openclaw gateway status --deep # System-level scan
openclaw gateway status --json # JSON output for scripting
openclaw doctor # Full diagnostics
openclaw doctor --fix # Auto-repair
```
## Operator Commands
```bash
openclaw gateway status [--deep] [--json]
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw secrets reload
openclaw logs --follow
openclaw logs --limit 200
openclaw logs --json
openclaw doctor
```
## Gateway Protocol
- Transport: WebSocket, text frames, JSON payloads
- First frame must be `connect`
- After handshake: `hello-ok` snapshot (presence, health, stateVersion, uptimeMs)
- Requests: `{type:"req", id, method, params}` → `{type:"res", id, ok, payload|error}`
- Events: `{type:"event", event, payload, seq?, stateVersion?}`
- Auth token via `connect.params.auth.token` or `OPENCLAW_GATEWAY_TOKEN`
- Idempotency keys required for `send`, `agent` methods
- Nodes declare `role: "node"` with capabilities in `connect`
Common events: `connect.challenge`, `agent`, `chat`, `presence`, `tick`, `health`, `heartbeat`, `shutdown`.
## Install / Update / Uninstall
### Install Methods
```bash
# Installer script (macOS / Linux)
curl -fsSL https://openclaw.ai/install.sh | bash
# npm
npm install -g openclaw@latest
openclaw onboard --install-daemon
# From source
git clone https://github.com/openclaw/openclaw.git
cd openclaw && pnpm install && pnpm ui:build && pnpm build
pnpm link --global
openclaw onboard --install-daemon
```
System requirements: Node 22+, macOS/Linux/Windows.
### Update
```bash
npm install -g openclaw@latest
openclaw doctor # Apply any migrations
```
### Uninstall
```bash
openclaw uninstall
```
## Troubleshooting
### Gateway Service Not Running
```bash
openclaw gateway status --deep
openclaw doctor
openclaw logs --follow
```
Common errors:
- `Runtime: stopped` — check exit hints
- `Config (cli) vs Config (service)` mismatch — re-install service
- Port conflict — `openclaw gateway --force`
### Dashboard/UI Not Loading
```bash
openclaw gateway status --json # Check probe URL
openclaw doctor
```
Check: correct URL, auth mode/token match, device identity flow.
### After Upgrade Issues
Run `openclaw doctor` immediately after updating. Common breaking changes:
1. Auth/URL override behavior changes
2. Bind/auth guardrails stricter
3. Pairing/device identity state changes
### Browser Tool Fails
```bash
openclaw browser status
openclaw browser start --browser-profile openclaw
openclaw browser profiles
openclaw doctor
```
Check: valid browser path, CDP profile reachability, Chrome extension relay.
### Config File Replacement Pitfalls
When replacing `openclaw.json` entirely (e.g. restoring from backup, pasting a new config):
1. **`.env` variable placeholders**: Config uses `${VAR_NAME}` references (e.g. `${JINA_API_KEY}`, `${TELEGRAM_MAIN_BOT_TOKEN}`). If `.env` contains placeholder values like `your-jina-api-key-here` instead of real keys, the Gateway will start but affected features will fail with auth errors (e.g. `401` from Jina embedding API).
2. **Plugin changes require full restart**: If the new config modifies `plugins.allow` or `plugins.entries` (e.g. removing `a2a-gateway`), hot-reload cannot apply these changes. The Gateway will log:
```
[reload] config change requires gateway restart (plugins.allow, plugins.entries.a2a-gateway)
```
You must do a full `openclaw gateway restart` or `launchctl kickstart`.
3. **Verify `.env` before restarting**: Always check that `~/.openclaw/.env` has real values for all referenced variables before restarting the Gateway. Missing or placeholder env vars silently degrade features.
**Checklist after config replacement:**
```bash
# 1. Validate the config
openclaw config validate
# 2. Check .env has real values (no placeholders)
cat ~/.openclaw/.env
# 3. Full restart (not just hot-reload)
openclaw gateway restart
# 4. Verify all systems
openclaw gateway status
openclaw logs --follow # Watch for auth errors
```
### LaunchAgent Stuck State (macOS)
When `openclaw gateway restart` reports "Gateway service not loaded" but `launchctl bootstrap` fails with I/O error:
```
Bootstrap failed: 5: Input/output error
```
This happens when the LaunchAgent plist has a stale/inconsistent state in launchd (e.g. after config changes that crashed the Gateway, or after `launchctl bootout` didn't fully clean up).
**Recovery sequence:**
```bash
# Step 1: Re-install the plist
openclaw gateway install
# Step 2: Force kickstart (bypasses stale state)
launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway
# Step 3: Verify
ps aux | grep openclaw-gateway | grep -v grep
openclaw gateway status
```
The `-k` flag in `launchctl kickstart` kills any existing instance and starts fresh, which resolves the stuck state that `bootstrap` cannot handle.
**If kickstart also fails**, try the nuclear option:
```bash
launchctl bootout gui/$(id -u)/ai.openclaw.gateway 2>/dev/null
openclaw gateway uninstall
sleep 2
openclaw gateway install
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist
```
### Cron/Heartbeat Not Firing
```bash
openclaw cron status
openclaw system heartbeat last
```
Verify Gateway is running and cron jobs are enabled.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |