S
SkillNav

OpenClaw网关

openclaw

by bengii

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.

4.5kDevOps未扫描2026年3月23日

安装

claude skill add --url github.com/openclaw/skills/tree/main/skills/bengii/bengii-gemini-fix

文档

OpenClaw Maintenance Skill

OpenClaw is a self-hosted, open-source (MIT) gateway that routes AI agents across WhatsApp, Telegram, Discord, Slack, iMessage, Signal, and 15+ other channels simultaneously. It runs on macOS, Linux, or Windows.

Reference Files

ReferenceCoverage
channels.mdPer-channel setup (WhatsApp, Telegram, Discord, etc.)
channel_troubleshooting.mdPer-channel failure signatures and walkthroughs
tools.mdTools inventory (profiles, groups, all built-in tools)
exec.mdExec tool: parameters, config, PATH, security, process tool
exec_approvals.mdExec approvals: allowlists, safe bins, approval flow
browser.mdBrowser tool: profiles, CDP, relay, SSRF, Control API
web_tools.mdWeb tools: Brave, Perplexity, Gemini search providers
pdf_tool.mdPDF tool: native/fallback modes, config, page filtering
elevated.mdElevated mode: /elevated directives, sandbox breakout
lobster.mdLobster: typed workflow runtime with approvals
llm_task.mdLLM Task: JSON-only LLM step for structured output
openprose.mdOpenProse: multi-agent program runtime
plugins.mdPlugins: official list, config, manifest, CLI, authoring
skills.mdSkills: locations, config, ClawHub, watcher, token impact
providers.mdModel provider setup
multi_agent.mdMulti-agent routing
nodes.mdNodes (iOS/Android/macOS/headless)
security.mdSecurity hardening
secrets.mdSecrets management (SecretRef, vault)
sandboxing.mdSandboxing (Docker isolation)
config_reference.mdFull config field reference
gateway_ops.mdGateway operations
remote_access.mdRemote access, SSH, Tailscale, web dashboard
sessions.mdSession management, DM isolation, lifecycle, compaction
hooks.mdHooks: internal event hooks, HTTP webhooks, authoring, CLI
automation.mdCron jobs, webhooks, Gmail Pub/Sub
acp_agents.mdACP agents: spawn external AI runtimes (Codex, Claude, etc.)
install.mdInstallation, updating, rollback, migration, uninstall
web_ui.mdWeb surfaces: Dashboard, Control UI, WebChat
slash_commands.mdChat slash commands (/new, /model, /acp, etc.)
platforms.mdPlatform-specific guides (macOS, iOS, Android, Linux, Windows)
diffs_firecrawl.mdDiffs plugin + Firecrawl anti-bot fallback
subagents.mdSub-agents: nested spawning, thread binding, announce, tool policy
memory.mdMemory system, vector search, hybrid BM25, compaction, QMD backend
architecture.mdGateway architecture, wire protocol, pairing, invariants
agent_runtime.mdAgent runtime, bootstrap files, agent loop, hooks, timeouts
streaming.mdStreaming + chunking: block streaming, coalescing, preview modes
queue.mdCommand queue: modes (steer/followup/collect), concurrency, per-session
model_failover.mdModel failover, OAuth, auth profiles, cooldowns, billing disables
clawhub.mdClawHub: public skill registry, CLI commands, publish/install
thinking.mdThinking levels, verbose directives, reasoning visibility
polls.mdPolls: Telegram, WhatsApp, Discord, MS Teams
voice.mdTalk Mode (voice interaction) + Voice Wake (wake words)
presence_discovery.mdPresence system, discovery (Bonjour/Tailscale), transports
gateway_internals.mdNetwork model, gateway lock, health checks, doctor, logging, background exec
heartbeat.mdHeartbeat: config, delivery, visibility, HEARTBEAT.md, per-agent
bonjour.mdBonjour/mDNS: TXT keys, wide-area DNS-SD, debugging, failure modes
pairing.mdGateway pairing: node approval, CLI, API, auto-approval, storage
tui.mdTUI: keyboard shortcuts, slash commands, pickers, local shell, delivery
media.mdMedia: camera capture, images, audio/voice notes, transcription
channel_routing.mdChannel routing, session keys, agent selection, Mattermost, BlueBubbles

Quick Reference

Key Paths

PathPurpose
~/.openclaw/openclaw.jsonMain config (JSON5)
~/.openclaw/.envGlobal env fallback
~/.openclaw/workspaceDefault agent workspace
~/.openclaw/agents/<id>/Per-agent state + sessions
~/.openclaw/skills/Managed/local skills
~/.openclaw/agents/<id>/qmd/QMD memory backend state
~/.openclaw/agents/<id>/agent/auth-profiles.jsonAuth profiles + OAuth tokens
OPENCLAW_CONFIG_PATHOverride config location
OPENCLAW_STATE_DIROverride state directory
OPENCLAW_HOMEOverride home directory

Essential Commands

code
openclaw status                    # Overall status
openclaw gateway status            # Gateway daemon status
openclaw gateway status --deep     # Deep scan including system services
openclaw doctor                    # Diagnose config/service issues
openclaw doctor --fix              # Auto-fix safe issues
openclaw logs --follow             # Tail gateway logs
openclaw channels status --probe   # Channel health check
openclaw security audit            # Security posture check
openclaw security audit --fix      # Auto-fix security issues
openclaw update                    # Self-update
openclaw dashboard                 # Open Control UI in browser
openclaw tui                       # Terminal UI (interactive REPL)
openclaw agent                     # Direct agent interaction via CLI
openclaw health                    # Health check
openclaw usage                     # Usage tracking
openclaw config validate           # Validate config file
openclaw config file               # Print active config path
openclaw sessions cleanup          # Session disk cleanup
openclaw agents bindings           # Agent-channel bindings
openclaw agents bind               # Bind agent to account
openclaw agents unbind             # Unbind agent
openclaw update --dry-run          # Preview update
openclaw system presence           # View connected clients/nodes
openclaw system heartbeat last     # Last heartbeat info
openclaw system heartbeat now      # Trigger heartbeat immediately
openclaw memory search <query>     # CLI memory search
openclaw docs <query>              # Search OpenClaw docs
openclaw nodes pending             # List pending pairing requests
openclaw nodes approve <id>        # Approve node pairing
openclaw nodes status              # Show all paired nodes
openclaw health --json             # Full health snapshot (JSON)
openclaw message send --media <p>  # Send media message

Default Gateway

  • Bind: 127.0.0.1:18789 (loopback)
  • Dashboard: http://127.0.0.1:18789/
  • Protocol: WebSocket (JSON text frames)

Core Workflow

Diagnosing Issues

Always follow this command ladder:

  1. openclaw status — quick overview
  2. openclaw gateway status — daemon running? RPC probe ok?
  3. openclaw logs --follow — watch for errors
  4. openclaw doctor — config/service diagnostics
  5. openclaw channels status --probe — per-channel health

Starting / Restarting Gateway

bash
# Foreground with verbose logging
openclaw gateway --port 18789 --verbose

# Force-kill existing listener then start
openclaw gateway --force

# Service management (launchd on macOS, systemd on Linux)
openclaw gateway install
openclaw gateway start
openclaw gateway stop
openclaw gateway restart

Configuration

Edit config via any method:

bash
# Interactive wizard
openclaw onboard                    # Full setup
openclaw configure                  # Config wizard

# CLI one-liners
openclaw config get <path>          # Read value
openclaw config set <path> <value>  # Set value (JSON5 or raw string)
openclaw config unset <path>        # Remove value

# Direct edit
# Edit ~/.openclaw/openclaw.json (JSON5 format)
# Gateway hot-reloads on save (if gateway.reload.mode != "off")

Minimal config example:

json5
{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

Channel Setup

For detailed per-channel setup, see references/channels.md. For per-channel troubleshooting (failure signatures, setup walkthroughs), see references/channel_troubleshooting.md. For plugins adding new channels (Matrix, Nostr, MS Teams, etc.), see references/plugins.md.

Quick channel add:

bash
# Interactive wizard
openclaw channels add

# Non-interactive
openclaw channels add --channel telegram --account default --name "My Bot" --token $BOT_TOKEN
openclaw channels login --channel whatsapp     # QR pairing for WhatsApp
openclaw channels status --probe               # Verify

Model Provider Setup

For detailed provider setup, see references/providers.md.

bash
# Set default model
openclaw models set anthropic/claude-sonnet-4-5

# List available models
openclaw models list --all

# Check auth/token status
openclaw models status --probe

# Add auth interactively
openclaw models auth add

Config example:

json5
{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.2"],
      },
    },
  },
}

Multi-Agent Routing

For detailed multi-agent config, see references/multi_agent.md.

bash
openclaw agents add <id>                # Create agent
openclaw agents list --bindings         # Show agent-channel bindings
openclaw agents delete <id>             # Remove agent

Nodes (iOS / Android / macOS / Headless)

For detailed node setup, see references/nodes.md.

bash
openclaw nodes status                   # List connected nodes
openclaw nodes describe --node <id>     # Node capabilities
openclaw devices list                   # Pending device approvals
openclaw devices approve <requestId>    # Approve a device
openclaw node run --host <host> --port 18789  # Start headless node host

Security

For detailed security hardening, see references/security.md. For secrets management (SecretRef, vault integration), see references/secrets.md. For sandboxing (Docker isolation for tools), see references/sandboxing.md. For full config field reference, see references/config_reference.md. For remote access (SSH, Tailscale, VPN), see references/remote_access.md.

bash
openclaw security audit                 # Check posture
openclaw security audit --deep          # Live gateway probe
openclaw security audit --fix           # Auto-fix safe issues
openclaw secrets reload                 # Re-resolve secret refs
openclaw secrets audit                  # Scan for plaintext leaks

Update / Uninstall

For detailed installation, updating, rollback, and migration guide, see references/install.md.

bash
# Install (recommended)
curl -fsSL https://openclaw.ai/install.sh | bash

# Update
openclaw update                    # Self-update command
# Or: npm install -g openclaw@latest
openclaw doctor                    # Run after update to apply migrations

# Uninstall
openclaw uninstall

Tools Reference

For detailed per-tool documentation, see references/tools.md.

For specific tools, see:

For ACP agents (Codex, Claude Code, Gemini CLI, etc.), see references/acp_agents.md. For Diffs plugin and Firecrawl anti-bot fallback, see references/diffs_firecrawl.md. For chat slash commands (/new, /model, /acp, etc.), see references/slash_commands.md. For thinking levels (/think, /verbose, /reasoning), see references/thinking.md. For polls (Telegram, WhatsApp, Discord, MS Teams), see references/polls.md. For Talk Mode and Voice Wake, see references/voice.md. For Gateway architecture and wire protocol, see references/architecture.md. For agent runtime and loop details, see references/agent_runtime.md. For command queue system, see references/queue.md. For model failover and OAuth, see references/model_failover.md. For ClawHub skill registry, see references/clawhub.md. For presence and discovery, see references/presence_discovery.md. For streaming and chunking, see references/streaming.md. For Gateway internals (network model, lock, health, doctor, logging), see references/gateway_internals.md. For heartbeat system, see references/heartbeat.md. For Bonjour/mDNS discovery details, see references/bonjour.md. For Gateway node pairing, see references/pairing.md. For Terminal UI (TUI), see references/tui.md. For media (camera, images, audio), see references/media.md. For channel routing and session keys, see references/channel_routing.md.

Tool profiles: minimal, coding, messaging, full (default).

Tool groups (for allow/deny):

  • group:runtime — exec, bash, process
  • group:fs — read, write, edit, apply_patch
  • group:sessions — sessions_list/history/send/spawn, session_status
  • group:memory — memory_search, memory_get
  • group:web — web_search, web_fetch
  • group:ui — browser, canvas
  • group:automation — cron, gateway
  • group:messaging — message
  • group:nodes — nodes
  • group:openclaw — all built-in OpenClaw tools (excludes provider plugins)

Common Failure Signatures

ErrorCauseFix
refusing to bind gateway ... without authNon-loopback bind without tokenSet gateway.auth.token or gateway.auth.password
another gateway instance is already listening / EADDRINUSEPort conflictopenclaw gateway --force or change port
Gateway start blocked: set gateway.mode=localLocal mode not enabledSet gateway.mode="local"
unauthorized / reconnect loopToken/password mismatchCheck OPENCLAW_GATEWAY_TOKEN or config auth
device identity requiredMissing device authEnsure client completes connect.challenge flow
No replies from botPairing/allowlist/mention gatingCheck openclaw pairing list, DM policy, mention patterns
Embedding provider authentication failed (401).env has placeholder API key (e.g. your-jina-api-key-here)Replace with real API key in ~/.openclaw/.env, restart Gateway
config change requires gateway restart (plugins.*)Plugin config changes can't hot-reloadFull openclaw gateway restart or launchctl kickstart -k
Bootstrap failed: 5: Input/output errorLaunchAgent plist in stale/stuck stateopenclaw gateway install then launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway
Missing env var "X" referenced at config path: ....env missing or variable not definedAdd variable to ~/.openclaw/.env and restart Gateway

Environment Variables

VariablePurpose
OPENCLAW_GATEWAY_TOKENGateway auth token
OPENCLAW_GATEWAY_PASSWORDGateway auth password
OPENCLAW_GATEWAY_PORTOverride gateway port
OPENCLAW_CONFIG_PATHOverride config file path
OPENCLAW_STATE_DIROverride state directory
OPENCLAW_HOMEOverride home directory
OPENCLAW_LOAD_SHELL_ENVImport shell env (set to 1)
OPENCLAW_VERBOSEVerbose logging
OPENCLAW_LOG_FILEFile logging path
OPENCLAW_LOG_LEVELLog level control
OPENCLAW_SHELLSet by OpenClaw in exec/acp/tui runtimes
BRAVE_API_KEYFor web_search tool
FIRECRAWL_API_KEYFor Firecrawl anti-bot fallback
ELEVENLABS_API_KEYFor Talk Mode TTS
ELEVENLABS_VOICE_IDDefault voice for Talk Mode
CLAWHUB_TOKENClawHub API token for CI/automation
CLAWHUB_WORKDIRClawHub working directory override
OLLAMA_API_KEYFor Ollama embeddings provider

相关 Skills

环境密钥管理

by alirezarezvani

Universal
热门

统一梳理dev/staging/prod的.env和密钥流程，自动生成.env.example、校验必填变量、扫描Git历史泄漏，并联动Vault、AWS SSM、1Password、Doppler完成轮换。

✎ 统一管理环境变量、密钥与配置，减少泄露和部署混乱，安全治理与团队协作一起做好，DevOps 场景很省心。

DevOps
未扫描15.8k

可观测性设计

by alirezarezvani

Universal
热门

面向生产系统规划可落地的可观测性体系，串起指标、日志、链路追踪与 SLI/SLO、错误预算、告警和仪表盘设计，适合搭建监控平台与优化故障响应。

✎ 把监控、日志、链路追踪串起来，帮助团队从设计阶段构建可观测性，排障更快、系统演进更稳。

DevOps
未扫描15.8k

更新日志

by alirezarezvani

Universal
热门

基于 Conventional Commits 自动解析提交记录、判断语义化版本升级并生成规范 changelog，适合在 CI、发版前检查提交格式并批量输出可审计发布说明。

✎ 自动生成和管理更新日志与发布说明，帮团队把版本变更说清楚；聚焦版本化与流程自动化，省时又更规范。

DevOps
未扫描15.8k

相关 MCP 服务

kubefwd

编辑精选

by txn2

热门

kubefwd 是让 AI 帮你批量转发 Kubernetes 服务到本地的开发神器。

✎ 微服务开发者最头疼的本地调试问题，它一键搞定——自动分配 IP 避免端口冲突，还能用自然语言查询状态。但依赖 AI 工作流，纯命令行爱好者可能觉得不够直接。

DevOps
4.1k

Cloudflare

编辑精选

by Cloudflare

热门

Cloudflare MCP Server 是让你用自然语言管理 Workers、KV 和 R2 等云资源的工具。

✎ 这个工具解决了开发者频繁切换控制台和文档的痛点，特别适合那些在 Cloudflare 上部署无服务器应用、需要快速调试或管理配置的团队。不过，由于它依赖多个子服务器，初次设置可能有点繁琐，建议先从 Workers Bindings 这类核心功能入手。

DevOps
3.8k

Terraform

编辑精选

by hashicorp

热门

Terraform MCP Server 是让 AI 助手直接操作 Terraform Registry 和 HCP Terraform 的桥梁。

✎ 如果你经常在 Terraform 里翻文档找模块配置，这个服务器能省不少时间——直接问 Claude 就能生成准确的代码片段。最适合管理多云基础设施的团队，但注意它目前只适合本地使用，别在生产环境里暴露 HTTP 端点。

DevOps
1.4k

相关资讯

Red Hat 工程师用容器让 OpenClaw 更安全

Tank OS 将 OpenClaw 运行在 Podman 容器中，形成可启动镜像，隔离智能体与宿主机，支持多实例无密码共享，适合企业 IT 人员管理大量智能体。

指南·4月28日·3 分钟

印度初创 Emergent 推出聊天式 AI 助手 Wingman

Emergent 从 vibe-coding 平台扩展到 AI 助手领域，推出 Wingman，主打通过聊天平台集成和“信任边界”设计。该助手旨在处理跨工具工作流，目前面临模糊情境下的稳定性挑战。

指南·4月15日·2 分钟

微软正开发企业级 OpenClaw 式智能体

微软计划推出类似 OpenClaw 的智能体，集成到 Microsoft 365 Copilot 中，主打企业级安全控制。该智能体可能本地运行，支持多步骤、长时间任务，预计在 Build 大会上亮相。

深度·4月13日·2 分钟

评论