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_internals.md

View on GitHub
# Gateway Internals Reference

> Sources: network-model, gateway-lock, health, doctor, logging, background-process

## Network Model

> Source: https://docs.openclaw.ai/gateway/network-model

### Core Rules

- **One Gateway per host** recommended. For rescue bots or strict isolation, use multiple gateways with isolated profiles and unique ports.
- **Loopback first**: Gateway WS defaults to `ws://127.0.0.1:18789`. Wizard generates a token even for loopback. For tailnet access: `openclaw gateway --bind tailnet --token ...` (tokens required for non-loopback).
- **Nodes** connect via LAN, tailnet, or SSH. Legacy TCP bridge is deprecated.
- **Canvas/UI routes** served on same port as Gateway HTTP:
  - `/__openclaw__/canvas/`
  - `/__openclaw__/a2ui/`
  - Protected by `gateway.auth` when binding beyond loopback.
  - Node clients use node-scoped capability URLs tied to their active WS session.
- **Remote use**: typically SSH tunnel or Tailscale VPN.

## Gateway Lock

> Source: https://docs.openclaw.ai/gateway/gateway-lock

### Why
- Ensure only one gateway instance per base port per host.
- Survive crashes/SIGKILL without stale lock files.
- Fail fast when the control port is occupied.

### Mechanism
- Gateway binds WebSocket listener (default `ws://127.0.0.1:18789`) immediately on startup using exclusive TCP.
- If bind fails with `EADDRINUSE`: `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")`.
- OS releases the listener automatically on any process exit (including crashes, SIGKILL) — no lock file needed.
- On shutdown, Gateway closes WS server and HTTP server to free the port promptly.

### Error Surface
| Error | Cause |
|---|---|
| `GatewayLockError("another gateway instance is already listening...")` | Another process holds the port |
| `GatewayLockError("failed to bind gateway socket...")` | Other bind failure |

### Fix
- Free the port or choose another: `openclaw gateway --port <port>`
- macOS app maintains its own PID guard before spawning; runtime lock enforced by WS bind.

## Health Checks

> Source: https://docs.openclaw.ai/gateway/health

### Quick Checks
| Command | Purpose |
|---|---|
| `openclaw status` | Local summary: reachability, mode, update hint, channel auth age, sessions |
| `openclaw status --all` | Full local diagnosis (read-only, safe to paste for debugging) |
| `openclaw status --deep` | Also probes running Gateway (per-channel probes) |
| `openclaw health --json` | Asks running Gateway for full health snapshot (WS-only) |
| `/status` (in WhatsApp/WebChat) | Status reply without invoking agent |

### 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`
- **Relink flow**: `openclaw channels logout && openclaw channels login --verbose` when status codes 409–515 or `loggedOut` appear
- **Logs**: `tail /tmp/openclaw/openclaw-*.log` and filter for `web-heartbeat`, `web-reconnect`, `web-auto-reply`, `web-inbound`

### When Something Fails
| Symptom | Fix |
|---|---|
| `logged out` or status 409–515 | Relink: `openclaw channels logout` then `openclaw channels login` |
| Gateway unreachable | Start it: `openclaw gateway --port 18789` (`--force` if busy) |
| No inbound messages | Check `channels.whatsapp.allowFrom`, group `mentionPatterns` |

## Doctor

> Source: https://docs.openclaw.ai/gateway/doctor

### Quick Start
```bash
openclaw doctor       # Interactive diagnosis + healing
openclaw doctor --fix # Auto-fix safe issues (non-interactive)
```

### What It Does (19 Steps)
1. Optional pre-flight update (git installs, interactive only)
2. UI protocol freshness check (rebuilds Control UI when schema is newer)
3. Config normalization for legacy values
4. OpenCode Zen provider override warnings (`models.providers.opencode`)
5. Legacy on-disk state migration (sessions/agent dir/WhatsApp auth)
6. State integrity + permissions checks (sessions, transcripts, state dir, chmod 600)
7. Model auth health: OAuth expiry, token refresh, profile cooldown/disabled states
8. Extra workspace dir detection (`~/openclaw`)
9. Sandbox image repair (when sandboxing enabled)
10. Legacy service migration + extra gateway detection
11. Skills status summary (eligible/missing/blocked)
12. Gateway auth checks (local token mode, offers token generation)
13. SecretRef-aware read-only repairs
14. Gateway health check + restart prompt
15. Channel status warnings (probed from running gateway)
16. Supervisor config audit + repair (launchd/systemd/schtasks)
17. Gateway runtime + port diagnostics (default 18789)
18. Gateway runtime best-practice checks (Node vs Bun, version-manager paths)
19. Config write + wizard metadata

### Headless / Automation
```bash
openclaw doctor --fix   # Non-interactive mode
openclaw doctor --json  # Machine-readable output
```

## Logging

> Source: https://docs.openclaw.ai/gateway/logging

### File-Based Logger
- Default rolling log file: `/tmp/openclaw/openclaw-YYYY-MM-DD.log` (one per day, local timezone)
- Configure via `logging.file` and `logging.level` in `openclaw.json`
- Tail logs: `openclaw logs --follow`
- `--verbose` only affects console verbosity, **not** file log level
- For verbose details in file logs: set `logging.level` to `debug` or `trace`

### Console Capture
- `logging.consoleLevel` (default: `info`)
- `logging.consoleStyle`: `pretty` | `compact` | `json`

### Tool Summary Redaction
- `logging.redactSensitive`: `off` | `tools` (default: `tools`)
- `logging.redactPatterns`: array of regex strings (overrides defaults)
- Masks: keeps first 6 + last 4 chars (length ≥ 18), otherwise `***`
- Defaults cover: key assignments, CLI flags, JSON fields, bearer headers, PEM blocks, token prefixes

### Gateway WebSocket Logs
- **Normal mode**: only "interesting" results — errors (`ok=false`), slow calls (≥ 50ms), parse errors
- **Verbose mode** (`--verbose`): prints all WS request/response traffic

## Background Exec + Process Tool

> Source: https://docs.openclaw.ai/gateway/background-process

### exec Tool Parameters
| Parameter | Default | Description |
|---|---|---|
| `command` | (required) | Command to run |
| `yieldMs` | 10000 | Auto-background after this delay |
| `background` | false | Background immediately |
| `timeout` | 1800 sec | Kill process after timeout |
| `elevated` | false | Run on host if elevated mode allowed |
| `pty` | false | Set `true` for real TTY |
| `workdir` | workspace | Working directory |
| `env` | — | Environment variables |

- Foreground runs return output directly
- When backgrounded: returns `status: "running"` + `sessionId` and short tail
- Spawned exec commands receive `OPENCLAW_SHELL=exec`

### Config Tuning
| Key | Default | Description |
|---|---|---|
| `tools.exec.backgroundMs` | 10000 | Auto-background threshold |
| `tools.exec.timeoutSec` | 1800 | Process timeout |
| `tools.exec.cleanupMs` | 1800000 | Cleanup TTL |
| `tools.exec.notifyOnExit` | true | Enqueue event on background exit |
| `tools.exec.notifyOnExitEmptySuccess` | false | Also notify on empty success |

### process Tool Actions
| Action | Description |
|---|---|
| `list` | Running + finished sessions |
| `poll` | Drain new output (reports exit status) |
| `log` | Read aggregated output (offset + limit) |
| `write` | Send stdin (data, optional eof) |
| `kill` | Terminate background session |
| `clear` | Remove finished session |
| `remove` | Kill if running, clear if finished |

- Sessions are **not** persisted to disk — lost on restart
- Process scoped per agent; only sees sessions from that agent

## See Also

- [architecture.md](architecture.md) — Gateway architecture overview
- [remote_access.md](remote_access.md) — SSH, Tailscale, web dashboard
- [presence_discovery.md](presence_discovery.md) — Presence and discovery
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