⚡

OpenClaw维护指南Skill openclaw

OpenClaw 维护指南是一份面向自托管、开源的多渠道 AI 智能体网关 OpenClaw 的综合运维手册，覆盖安装、配置、运行与故障排查全流程。内容包括：多渠道接入（WhatsApp、Telegram、Discord、Slack、iMessage、Signal 等 20+ 渠道）、模型提供商与多智能体路由配置、Gateway 守护进程运维、认证与安全加固、密钥与沙箱隔离、会话/记忆/流式传输、定时任务与 Webhook 自动化、节点配对与远程访问，以及大量常见故障签名与一键修复命令。适用于部署或维护本地 OpenClaw 实例、排查 openclaw CLI 或网关守护进程报错的技术人员。关键词：OpenClaw、AI 网关、多渠道消息、AI 智能体、自托管、网关运维、渠道接入、模型提供商、多智能体路由、安全加固、密钥管理、沙箱隔离、故障排查、WhatsApp、Telegram、Discord、Slack、iMessage、Signal、Gateway、CLI、Webhook、定时任务。

AI智能体 0 次安装 0 次浏览 更新于 11/10/2026

OpenClaw 维护技能

OpenClaw 是一个自托管、开源（MIT）的网关，可同时将 AI 智能体路由到 WhatsApp、Telegram、Discord、Slack、iMessage、Signal 以及其他 15+ 个渠道。它运行在 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、控制 API
web_tools.md Web 工具：Brave、Perplexity、Gemini 搜索提供商
pdf_tool.md PDF 工具：原生/回退模式、配置、页面过滤
elevated.md 提权模式：/elevated 指令、沙箱突破
lobster.md Lobster：带审批的类型化工作流运行时
llm_task.md LLM Task：用于结构化输出的纯 JSON LLM 步骤
openprose.md OpenProse：多智能体程序运行时
plugins.md 插件：能力模型、官方列表、配置、钩子、SDK、编写
skills.md 技能：位置、配置、ClawHub、监听器、token 影响
providers.md 模型提供商设置
multi_agent.md 多智能体路由
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 会话管理、DM 隔离、生命周期、压缩
hooks.md 钩子：内部事件钩子、HTTP webhooks、编写、CLI
automation.md 定时任务、webhooks、Gmail Pub/Sub、后台任务、常驻命令
acp_agents.md ACP 智能体：生成外部 AI 运行时（Codex、Claude、Gemini、14+ harnesses）
install.md 安装、更新、回滚、迁移、卸载
web_ui.md Web 界面：仪表盘、控制 UI、WebChat
slash_commands.md 聊天斜杠命令（/new、/model、/acp 等）
platforms.md 平台专属指南（macOS、iOS、Android、Linux、Windows）
diffs_firecrawl.md Diffs 插件 + Firecrawl 反爬回退
subagents.md 子智能体：嵌套生成、线程绑定、announce、工具策略
memory.md 记忆系统、向量搜索、混合 BM25、压缩、QMD 后端
architecture.md 网关架构、线协议、配对、不变量
agent_runtime.md 智能体运行时、引导文件、智能体循环、上下文引擎、钩子、超时
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 Talk Mode（语音交互）+ Voice Wake（唤醒词）
presence_discovery.md 存在系统、发现（Bonjour/Tailscale）、传输
gateway_internals.md 网络模型、网关锁、健康检查、doctor、日志、后台 exec
heartbeat.md 心跳：配置、投递、可见性、HEARTBEAT.md、每智能体
bonjour.md Bonjour/mDNS：TXT 键、广域 DNS-SD、调试、故障模式
pairing.md 网关配对：节点审批、CLI、API、自动审批、存储
tui.md TUI：键盘快捷键、斜杠命令、选择器、本地 shell、投递
media.md 媒体：摄像头捕获、图像、音频/语音笔记、转录
channel_routing.md 渠道路由、会话键、智能体选择、Mattermost、BlueBubbles

快速参考

关键路径

路径 用途
~/.openclaw/openclaw.json 主配置（JSON5）
~/.openclaw/.env 全局环境变量回退
~/.openclaw/workspace 默认智能体工作区
~/.openclaw/agents/<id>/ 每智能体状态 + 会话
~/.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                    # 整体状态
openclaw gateway status            # 网关守护进程状态
openclaw gateway status --deep     # 深度扫描，包含系统服务
openclaw doctor                    # 诊断配置/服务问题
openclaw doctor --fix              # 自动修复安全的问题
openclaw logs --follow             # 跟踪网关日志
openclaw channels status --probe   # 渠道健康检查
openclaw security audit            # 安全态势检查
openclaw security audit --fix      # 自动修复安全问题
openclaw update                    # 自更新
openclaw dashboard                 # 在浏览器中打开控制 UI
openclaw tui                       # 终端 UI（交互式 REPL）
openclaw agent                     # 通过 CLI 直接与智能体交互
openclaw health                    # 健康检查
openclaw usage                     # 用量追踪
openclaw config validate           # 校验配置文件
openclaw config file               # 打印当前生效的配置路径
openclaw sessions cleanup          # 会话磁盘清理
openclaw agents bindings           # 智能体-渠道绑定
openclaw agents bind               # 绑定智能体到账号
openclaw agents unbind             # 解绑智能体
openclaw update --dry-run          # 预览更新
openclaw system presence           # 查看已连接的客户端/节点
openclaw system heartbeat last     # 最近一次心跳信息
openclaw system heartbeat now      # 立即触发心跳
openclaw memory search <query>     # CLI 记忆搜索
openclaw docs <query>              # 搜索 OpenClaw 文档
openclaw tasks list                # 列出后台/分离任务运行
openclaw tasks show <id>           # 查看特定任务详情
openclaw tasks cancel <id>         # 取消运行中的任务
openclaw tasks audit               # 识别有问题的任务运行
openclaw agent --message "..."     # 运行单次智能体回合（脚本/测试）
openclaw nodes pending             # 列出待处理配对请求
openclaw nodes approve <id>        # 批准节点配对
openclaw nodes status              # 显示所有已配对节点
openclaw health --json             # 完整健康快照（JSON）
openclaw message send --media <p>  # 发送媒体消息

默认网关

  • 绑定：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 — 各渠道健康

启动/重启网关

# 前台运行并开启详细日志
openclaw gateway --port 18789 --verbose

# 强制终止现有监听进程后启动
openclaw gateway --force

# 服务管理（macOS 上为 launchd，Linux 上为 systemd）
openclaw gateway install
openclaw gateway start
openclaw gateway stop
openclaw gateway restart

配置

通过任意方式编辑配置：

# 交互式向导
openclaw onboard                    # 完整设置
openclaw configure                  # 配置向导

# CLI 单行命令
openclaw config get <path>          # 读取值
openclaw config set <path> <value>  # 设置值（JSON5 或原始字符串）
openclaw config unset <path>        # 移除值

# 直接编辑
# 编辑 ~/.openclaw/openclaw.json（JSON5 格式）
# 保存后网关热重载（若 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。

快速添加渠道：

# 交互式向导
openclaw channels add

# 非交互式
openclaw channels add --channel telegram --account default --name "My Bot" --token $BOT_TOKEN
openclaw channels login --channel whatsapp     # WhatsApp 二维码配对
openclaw channels status --probe               # 验证

模型提供商设置

详细的提供商设置见 references/providers.md。

# 设置默认模型
openclaw models set anthropic/claude-sonnet-4-5

# 列出可用模型
openclaw models list --all

# 检查认证/令牌状态
openclaw models status --probe

# 交互式添加认证
openclaw models auth add

配置示例：

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

多智能体路由

详细的多智能体配置见 references/multi_agent.md。

openclaw agents add <id>                # 创建智能体
openclaw agents list --bindings         # 显示智能体-渠道绑定
openclaw agents delete <id>             # 移除智能体

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

详细的节点设置见 references/nodes.md。

openclaw nodes status                   # 列出已连接节点
openclaw nodes describe --node <id>     # 节点能力
openclaw devices list                   # 待处理设备审批
openclaw devices approve <requestId>    # 批准设备
openclaw node run --host <host> --port 18789  # 启动无头节点主机

安全

详细的安全加固见 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                 # 检查态势
openclaw security audit --deep          # 实时网关探测
openclaw security audit --fix           # 自动修复安全问题
openclaw secrets reload                 # 重新解析密钥引用
openclaw secrets audit                  # 扫描明文泄露

更新/卸载

详细的安装、更新、回滚、迁移指南见 references/install.md。

# 安装（推荐）
curl -fsSL https://openclaw.ai/install.sh | bash

# 更新
openclaw update                    # 自更新命令
# 或：npm install -g openclaw@latest
openclaw doctor                    # 更新后运行以应用迁移

# 卸载
openclaw uninstall

工具参考

详细的逐工具文档见 references/tools.md。

特定工具见：

ACP 智能体（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。 网关架构与线协议见 references/architecture.md。 智能体运行时与循环细节见 references/agent_runtime.md。 命令队列系统见 references/queue.md。 模型故障转移与 OAuth 见 references/model_failover.md。 ClawHub 技能注册表见 references/clawhub.md。 存在与发现见 references/presence_discovery.md。 流式传输与分块见 references/streaming.md。 网关内部（网络模型、锁、健康、doctor、日志）见 references/gateway_internals.md。 心跳系统见 references/heartbeat.md。 Bonjour/mDNS 发现细节见 references/bonjour.md。 网关节点配对见 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 / 重连循环 令牌/密码不匹配 检查 OPENCLAW_GATEWAY_TOKEN 或配置认证
device identity required 缺少设备认证 确保客户端完成 connect.challenge 流程
机器人无回复 配对/白名单/@提及门控 检查 openclaw pairing list、DM 策略、提及模式
Embedding provider authentication failed (401) .env 中有占位符 API 密钥（如 your-jina-api-key-here） 在 ~/.openclaw/.env 中替换为真实 API 密钥，重启网关
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 中添加变量并重启网关

环境变量

变量 用途
OPENCLAW_GATEWAY_TOKEN 网关认证令牌
OPENCLAW_GATEWAY_PASSWORD 网关认证密码
OPENCLAW_GATEWAY_PORT 覆盖网关端口
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 文本转语音
ELEVENLABS_VOICE_ID Talk Mode 默认语音
CLAWHUB_TOKEN 用于 CI/自动化的 ClawHub API 令牌
CLAWHUB_WORKDIR 覆盖 ClawHub 工作目录
OLLAMA_API_KEY 用于 Ollama 嵌入提供商
OPENCLAW_SKIP_CRON 禁用定时任务调度器（设为 1）
OPENCLAW_HIDE_BANNER 抑制 banner 输出
OPENCLAW_SUPPRESS_NOTES 抑制信息性提示