openclaw

OpenClaw 维护技能

OpenClaw 是一个可自托管的开源（MIT）网关，可同时通过 WhatsApp、Telegram、Discord、Slack、iMessage、Signal 和其他 15 多个渠道路由 AI Agent。它可在 macOS、Linux 或 Windows 上运行。

参考文件

参考	涵盖内容
channels.md	各渠道的设置（WhatsApp、Telegram、Discord 等）
channel_troubleshooting.md	各渠道的故障特征与排查指南
tools.md	工具清单（配置文件、群组、所有内置工具）
exec.md	Exec 工具：参数、配置、PATH、安全性、进程工具
exec_approvals.md	Exec 审批：允许列表、安全二进制文件、审批流程
browser.md	浏览器插件：配置文件、CDP、Chrome MCP、快照、SSRF、Control API
web_tools.md	Web 工具：Brave、Perplexity、Gemini 搜索提供商
pdf_tool.md	PDF 工具：原生/回退模式、配置、页面筛选
elevated.md	提权模式：/elevated 指令、沙箱逃逸
lobster.md	Lobster：支持审批的类型化工作流运行时
llm_task.md	LLM Task：仅输出 JSON 的大模型步骤，用于生成结构化输出
openprose.md	OpenProse：多 Agent 程序运行时
plugins.md	插件：功能模型、官方列表、配置、钩子、SDK、编写
skills.md	技能：位置、配置、ClawHub、监视器、令牌影响
providers.md	模型提供商设置
multi_agent.md	多 Agent 路由
nodes.md	节点（iOS/Android/macOS/无头）
security.md	安全加固
secrets.md	密钥管理（SecretRef、保管库）
sandboxing.md	沙箱隔离（Docker 隔离）
config_reference.md	完整配置字段参考
gateway_ops.md	网关运维
remote_access.md	远程访问、SSH、Tailscale、Web 控制面板
sessions.md	会话管理、私信隔离、生命周期、压缩
hooks.md	钩子：内部事件钩子、HTTP Webhook、编写、CLI
automation.md	Cron 作业、Webhook、Gmail Pub/Sub、后台任务、常设指令
acp_agents.md	ACP Agent：启动外部 AI 运行时（Codex、Claude、Gemini、14+ 种执行框架）
install.md	安装、更新、回滚、迁移、卸载
web_ui.md	Web 界面：Dashboard、Control UI、WebChat
slash_commands.md	聊天斜杠命令（/new、/model、/acp 等）
platforms.md	平台专属指南（macOS、iOS、Android、Linux、Windows）
diffs_firecrawl.md	Diffs 插件 + Firecrawl 反机器人回退方案
subagents.md	子 Agent：嵌套启动、线程绑定、通知、工具策略
memory.md	记忆系统、向量搜索、混合 BM25、压缩、QMD 后端
architecture.md	网关架构、线路协议、配对、不变量
agent_runtime.md	Agent 运行时、引导文件、Agent 循环、上下文引擎、钩子、超时
streaming.md	流式传输 + 分块：区块流式传输、合并、预览模式
queue.md	命令队列：模式（steer/followup/collect）、并发、按会话处理
model_failover.md	模型故障转移、OAuth、身份验证配置文件、冷却、计费停用
clawhub.md	ClawHub：公共技能注册表、CLI 命令、发布/安装
thinking.md	思考级别、详细程度指令、推理可见性
polls.md	投票：Telegram、WhatsApp、Discord、MS Teams
voice.md	对话模式（语音交互）+ 语音唤醒（唤醒词）
presence_discovery.md	在线状态系统、发现（Bonjour/Tailscale）、传输方式
gateway_internals.md	网络模型、网关锁、健康检查、doctor、日志记录、后台执行
heartbeat.md	心跳：配置、传递、可见性、HEARTBEAT.md、按 Agent 设置
bonjour.md	Bonjour/mDNS：TXT 键、广域 DNS-SD、调试、故障模式
pairing.md	网关配对：节点审批、CLI、API、自动审批、存储
tui.md	TUI：键盘快捷键、斜杠命令、选择器、本地 Shell、传递
media.md	媒体：摄像头捕获、图像、音频/语音便笺、转录
channel_routing.md	渠道路由、会话键、Agent 选择、Mattermost、BlueBubbles

快速参考

关键路径

路径	用途
~/.openclaw/openclaw.json	主配置（JSON5）
~/.openclaw/.env	全局环境变量回退
~/.openclaw/workspace	默认 Agent 工作区
~/.openclaw/agents/<id>/	每个 Agent 的状态和会话
~/.openclaw/skills/	已管理/本地技能
~/.openclaw/agents/<id>/qmd/	QMD 记忆后端状态
~/.openclaw/agents/<id>/agent/auth-profiles.json	认证配置和 OAuth 令牌
OPENCLAW_CONFIG_PATH	覆盖配置位置
OPENCLAW_STATE_DIR	覆盖状态目录
OPENCLAW_HOME	覆盖主目录

基本命令

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 tasks list                # List background/detached task runs
openclaw tasks show <id>           # Show specific task details
openclaw tasks cancel <id>         # Cancel a running task
openclaw tasks audit               # Identify problematic task runs
openclaw agent --message "..."     # Run single agent turn (scripted/testing)
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

默认网关

• 绑定：127.0.0.1:18789（环回地址）
• 控制面板：http://127.0.0.1:18789/
• 协议：WebSocket（JSON 文本帧）

核心工作流

诊断问题

始终按以下命令顺序操作：

1. openclaw status — 快速概览
2. openclaw gateway status — 守护进程是否正在运行？RPC 探测是否正常？
3. openclaw logs --follow — 查看错误
4. openclaw doctor — 配置/服务诊断
5. openclaw channels status --probe — 检查各频道的运行状况

启动/重启网关

# 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

配置

可通过任意方式编辑配置：

# 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")

最小配置示例：

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

频道设置

各频道的详细设置请参阅 references/channels.md。 各频道的故障排除（故障特征、设置步骤）请参阅 references/channel_troubleshooting.md。 可添加新频道的插件（Matrix、Nostr、MS Teams 等）请参阅 references/plugins.md。

快速添加频道：

# 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

模型提供方设置

提供方的详细设置请参阅 references/providers.md。

# 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

配置示例：

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

多 Agent 路由

多 Agent 配置的详细信息请参阅 references/multi_agent.md。

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

节点（iOS / Android / macOS / 无头模式）

节点的详细设置请参阅 references/nodes.md。

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

安全

安全加固的详细信息请参阅 references/security.md。 密钥管理（SecretRef、保管库集成）请参阅 references/secrets.md。 沙箱（工具的 Docker 隔离）请参阅 references/sandboxing.md。 完整的配置字段参考请参阅 references/config_reference.md。 远程访问（SSH、Tailscale、VPN）请参阅 references/remote_access.md。

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

更新/卸载

有关安装、更新、回滚和迁移的详细指南，请参阅 references/install.md。

# 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

工具参考

有关各工具的详细文档，请参阅 references/tools.md。

有关特定工具，请参阅：

• references/exec.md — Exec 工具深入介绍
• references/exec_approvals.md — Exec 审批和允许列表
• references/browser.md — 浏览器自动化深入介绍
• references/web_tools.md — 使用多个提供商进行网页搜索/抓取
• references/lobster.md — Lobster 工作流运行时
• references/llm_task.md — 用于结构化 JSON 输出的 LLM Task
• references/openprose.md — OpenProse 多 Agent 程序
• references/plugins.md — 插件系统（安装、编写、分发）
• references/skills.md — Skills 系统（加载、配置、ClawHub）

有关 ACP Agent（Codex、Claude Code、Gemini CLI 等），请参阅 references/acp_agents.md。 有关 Diffs 插件和 Firecrawl 反机器人回退方案，请参阅 references/diffs_firecrawl.md。 有关聊天斜杠命令（/new、/model、/acp 等），请参阅 references/slash_commands.md。 有关思考级别（/think、/verbose、/reasoning），请参阅 references/thinking.md。 有关投票（Telegram、WhatsApp、Discord、MS Teams），请参阅 references/polls.md。 有关 Talk Mode 和 Voice Wake，请参阅 references/voice.md。 有关 Gateway 架构和线协议，请参阅 references/architecture.md。 有关 Agent 运行时和循环详情，请参阅 references/agent_runtime.md。 有关命令队列系统，请参阅 references/queue.md。 有关模型故障转移和 OAuth，请参阅 references/model_failover.md。 有关 ClawHub 技能注册表，请参阅 references/clawhub.md。 有关在线状态和发现，请参阅 references/presence_discovery.md。 有关流式传输和分块，请参阅 references/streaming.md。 有关 Gateway 内部机制（网络模型、锁、运行状况、doctor、日志记录），请参阅 references/gateway_internals.md。 有关心跳系统，请参阅 references/heartbeat.md。 有关 Bonjour/mDNS 发现详情，请参阅 references/bonjour.md。 有关 Gateway 节点配对，请参阅 references/pairing.md。 有关终端 UI（TUI），请参阅 references/tui.md。 有关媒体（摄像头、图像、音频），请参阅 references/media.md。 有关渠道路由和会话密钥，请参阅 references/channel_routing.md。

工具配置：minimal、coding、messaging、full（默认）。

工具组（用于允许/拒绝）：

• 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 — 所有内置 OpenClaw 工具（不包括提供商插件）

常见故障特征

错误	原因	修复方法
refusing to bind gateway ... without auth	绑定到非环回地址时未设置令牌	设置 gateway.auth.token 或 gateway.auth.password
another gateway instance is already listening / EADDRINUSE	端口冲突	运行 openclaw gateway --force 或更改端口
Gateway start blocked: set gateway.mode=local	未启用本地模式	设置 gateway.mode="local"
unauthorized / reconnect loop	令牌／密码不匹配	检查 OPENCLAW_GATEWAY_TOKEN 或配置中的身份验证设置
device identity required	缺少设备身份验证	确保客户端完成 connect.challenge 流程
机器人没有回复	配对／允许列表／提及限制	检查 openclaw pairing list、私信策略和提及模式
Embedding provider authentication failed (401)	.env 中的 API 密钥是占位符（例如 your-jina-api-key-here）	在 ~/.openclaw/.env 中替换为真实的 API 密钥，然后重启 Gateway
openclaw flows list / ClawFlow 引用	ClawFlow 已弃用	改用 openclaw tasks list/show/cancel/audit
config change requires gateway restart (plugins.*)	插件配置更改无法热重载	完整重启 openclaw gateway restart，或运行 launchctl kickstart -k
Bootstrap failed: 5: Input/output error	LaunchAgent plist 处于过期／卡住状态	运行 openclaw gateway install，然后运行 launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway
Missing env var "X" referenced at config path: ...	.env 缺失或未定义该变量	将变量添加到 ~/.openclaw/.env，然后重启 Gateway

环境变量

变量	用途
OPENCLAW_GATEWAY_TOKEN	Gateway 身份验证令牌
OPENCLAW_GATEWAY_PASSWORD	Gateway 身份验证密码
OPENCLAW_GATEWAY_PORT	覆盖 Gateway 端口
OPENCLAW_CONFIG_PATH	覆盖配置文件路径
OPENCLAW_STATE_DIR	覆盖状态目录
OPENCLAW_HOME	覆盖主目录
OPENCLAW_LOAD_SHELL_ENV	导入 shell 环境变量（设为 1）
OPENCLAW_VERBOSE	详细日志记录
OPENCLAW_LOG_FILE	日志文件路径
OPENCLAW_LOG_LEVEL	日志级别控制
OPENCLAW_SHELL	由 OpenClaw 在 exec/acp/tui 运行时设置
BRAVE_API_KEY	用于 web_search 工具
FIRECRAWL_API_KEY	用于 Firecrawl 反机器人备用方案
ELEVENLABS_API_KEY	用于 Talk Mode TTS
ELEVENLABS_VOICE_ID	Talk Mode 的默认语音
CLAWHUB_TOKEN	用于 CI／自动化的 ClawHub API 令牌
CLAWHUB_WORKDIR	覆盖 ClawHub 工作目录
OLLAMA_API_KEY	用于 Ollama 嵌入提供商
OPENCLAW_SKIP_CRON	禁用 cron 调度器（设为 1）
OPENCLAW_HIDE_BANNER	隐藏横幅输出
OPENCLAW_SUPPRESS_NOTES	隐藏提示信息