Skip to content

LeoYeAI/agent-master-skills / skills/bengii-gemini-fix

openclaw

Flagged

Comprehensive 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.

FileKindSize
README.mdmarkdown7.5 KB
README_CN.mdmarkdown7.3 KB
SKILL.mdskill md18.7 KB
_meta.jsonconfig286 B
references/acp_agents.mdmarkdown12.6 KB
references/agent_runtime.mdmarkdown5.6 KB
references/architecture.mdmarkdown3.8 KB
references/automation.mdmarkdown5.8 KB
references/bonjour.mdmarkdown3.3 KB
references/browser.mdmarkdown8.5 KB
references/channel_routing.mdmarkdown4.0 KB
references/channel_troubleshooting.mdmarkdown11.6 KB
references/channels.mdmarkdown6.2 KB
references/clawhub.mdmarkdown3.6 KB
references/config_reference.mdmarkdown11.2 KB
references/diffs_firecrawl.mdmarkdown3.3 KB
references/elevated.mdmarkdown2.8 KB
references/exec.mdmarkdown6.5 KB
references/exec_approvals.mdmarkdown3.1 KB
references/gateway_internals.mdmarkdown7.7 KB
references/gateway_ops.mdmarkdown9.6 KB
references/heartbeat.mdmarkdown4.9 KB
references/hooks.mdmarkdown14.6 KB
references/install.mdmarkdown4.1 KB
references/llm_task.mdmarkdown2.6 KB
references/lobster.mdmarkdown7.8 KB
references/media.mdmarkdown4.2 KB
references/memory.mdmarkdown11.9 KB
references/model_failover.mdmarkdown3.1 KB
references/multi_agent.mdmarkdown4.4 KB
references/nodes.mdmarkdown8.8 KB
references/openprose.mdmarkdown2.6 KB
references/pairing.mdmarkdown3.1 KB
references/pdf_tool.mdmarkdown3.5 KB
references/platforms.mdmarkdown2.7 KB
references/plugins.mdmarkdown6.9 KB
references/polls.mdmarkdown2.2 KB
references/presence_discovery.mdmarkdown2.2 KB
references/providers.mdmarkdown6.0 KB
references/queue.mdmarkdown2.1 KB
references/remote_access.mdmarkdown4.7 KB
references/sandboxing.mdmarkdown5.6 KB
references/secrets.mdmarkdown5.4 KB
references/security.mdmarkdown24.5 KB
references/sessions.mdmarkdown8.9 KB
references/skills.mdmarkdown4.4 KB
references/slash_commands.mdmarkdown5.1 KB
references/streaming.mdmarkdown1.8 KB
references/subagents.mdmarkdown12.3 KB
references/thinking.mdmarkdown2.8 KB
references/tools.mdmarkdown13.3 KB
references/tui.mdmarkdown4.0 KB
references/voice.mdmarkdown2.7 KB
references/web_tools.mdmarkdown2.7 KB
references/web_ui.mdmarkdown4.5 KB

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.
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall