🦞 OpenClaw 使用说明书（官方文档版）

1. 认识 OpenClaw（官方定位）

根据官方文档，OpenClaw 是一个自托管 Gateway 网关：通过渠道插件，把你常用的聊天应用（Discord、Google Chat、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp、Zalo 等）连接到 AI 编码智能体。你在自己的计算机（或服务器）上运行单个 Gateway 网关进程，它就成为消息应用与始终在线的 AI 助手之间的桥梁。

它与众不同的地方

• 自托管：在你的硬件上按你的规则运行，不放弃数据控制权
• 多渠道：一个 Gateway 网关同时服务所有已配置的渠道插件
• 智能体原生：专为具备工具使用、会话、记忆和多智能体路由能力的编码智能体构建
• 开源：采用 MIT 许可证，由 OpenClaw 基金会（openclaw.org）以开放方式开发，社区驱动

需要什么？

• Node.js：24.15+（推荐）或 22.22.3+（LTS 兼容）或 25.9+
• API 密钥：来自所选模型提供商（Anthropic、OpenAI、Google 等）
• 时间：约 5 分钟即可完成设置

工作原理

聊天应用 + 插件 ──▶ Gateway 网关 ──▶ OpenClaw 智能体
                          ├──▶ CLI
                          ├──▶ Web Control UI
                          ├──▶ macOS 应用
                          └──▶ iOS / Android 节点

Gateway 网关是会话、路由和渠道连接的唯一事实来源。

2. 快速开始（5 分钟上手）

安装 OpenClaw → 运行新手引导 → 大约 5 分钟内与你的 AI 助手聊天。完成后你将拥有：正在运行的 Gateway 网关、已配置的身份验证、可用的聊天会话。

步骤 1：安装 OpenClaw

# macOS / Linux / WSL2
curl -fsSL https://openclaw.ai/install.sh | bash

# Windows（PowerShell）
iwr -useb https://openclaw.ai/install.ps1 | iex

安装脚本会自动检测系统、在需要时安装 Node、安装 OpenClaw 并启动新手引导。

步骤 2：运行新手引导

openclaw onboard --install-daemon

向导将引导你：选择模型提供商 → 设置 API key → 配置 Gateway 网关。可跳过可选步骤，稍后用 openclaw configure 返回继续。

步骤 3：验证 Gateway 正在运行

openclaw gateway status
# 应显示 Gateway 网关正在监听端口 18789

步骤 4：打开仪表板并发送第一条消息

openclaw dashboard   # 在浏览器中打开 Control UI（http://127.0.0.1:18789/）

在 Control UI 聊天中输入一条消息，收到 AI 回复即成功。想用手机聊天？设置最快的渠道是 Telegram（只需一个机器人令牌）。

后续步骤

• 连接渠道：Discord、Feishu、iMessage、Signal、Telegram、WhatsApp 等
• 配置 Gateway 网关：模型、工具、沙箱和高级设置
• 浏览工具：浏览器、Exec、Web 搜索、Skills 和插件

3. 安装指南

系统要求

• Node：22.22.3+、24.15+ 或 25.9+（Node 24 是默认目标版本；安装脚本会自动处理）
• 系统：macOS、Linux 或 Windows（Windows 可从原生 Hub 应用、PowerShell CLI 或 WSL2 开始）
• 仅在从源代码构建时才需要 pnpm

安装方式总览

3.1 验证安装与托管

openclaw --version       # 确认 CLI 可用
openclaw doctor          # 检查配置问题
openclaw gateway status  # 验证 Gateway 网关正在运行

托管启动（开机自启）：通过 openclaw onboard --install-daemon 或 openclaw gateway install——macOS 使用 LaunchAgent、Linux/WSL2 使用 systemd 用户服务、原生 Windows 优先使用计划任务。

云服务器 / VPS 部署：官方提供 DigitalOcean、Hetzner、Fly.io、GCP、Azure、Railway、Oracle Cloud、Raspberry Pi 等提供商选择器（docs.openclaw.ai/vps），另有 Docker VM、Kubernetes 等部署路径。

更新 / 迁移 / 卸载

openclaw update                          # 更新到最新版
openclaw update --channel stable|dev     # 切换发布渠道
openclaw migrate                         # 迁移到新计算机
openclaw uninstall                       # 完全移除

3.2 常见安装问题：找不到 openclaw 命令

这几乎总是 PATH 问题：npm 的全局二进制目录不在 shell 的 PATH 中。按顺序排查：

node -v        # 是否已安装 Node？
npm prefix -g  # 全局软件包位于何处？
echo "$PATH"   # 全局二进制目录是否在 PATH 中？

4. 新手引导（onboard）

官方 CLI 将设置命令按用途划分：

• openclaw setup / openclaw onboard：首先验证推理，然后启动 OpenClaw，设置 Gateway 网关、工作区、渠道、Skills 和健康状态
• openclaw setup --baseline：创建基础配置和工作区，不进入引导式流程
• openclaw configure：更改现有设置的特定部分（模型身份验证、Gateway 网关、渠道、插件或 Skills）
• openclaw channels add：基础配置就绪后配置渠道账户

5. 消息渠道

OpenClaw 可以通过你已经使用的任何聊天应用与你交流，每个渠道都通过 Gateway 网关连接。所有渠道都支持文本；媒体和表情回应支持情况因渠道而异。

渠道类型

• 核心内置 iMessage、Telegram、WebChat 随核心安装提供，无需插件
• 官方插件 其余渠道用一条命令安装：openclaw plugins install @openclaw/<id>，或在 openclaw onboard / openclaw channels add 期间按需安装，之后重启 Gateway
• 外部插件 由 OpenClaw 仓库之外的维护者维护（如微信、腾讯元宝、Zalo ClawBot）

支持的渠道一览（官方）

投递说明

• 包含 Markdown 图片语法（如 ![alt](url)）的 Telegram 回复，会尽可能在最终出站路径上转换为媒体回复
• Slack 多人私信按群聊进行路由，因此群组策略、提及行为和群组会话规则适用于 MPIM 对话
• WhatsApp 采用按需安装方式：安装插件包之前新手引导即可显示设置流程，仅当该渠道实际处于活动状态时 Gateway 才会加载外部 ClawHub / npm 插件
• 接受机器人入站消息的渠道可使用共享的机器人循环保护，防止成对的机器人无限期地相互回复
• 支持的常驻房间可使用环境房间事件：未提及智能体的房间聊天会作为静默上下文，除非智能体使用 message 工具主动发送消息

注意事项

• 多个渠道可以同时运行；配置多个渠道后，OpenClaw 将按聊天进行路由
• 通常设置最快的是 Telegram（简单机器人令牌，无需安装插件）；WhatsApp 需要二维码配对并存储更多状态
• 为确保安全，会强制执行私信配对和允许列表
• 群组行为因渠道而异（见官方"群组"文档）

私信安全（dmPolicy）

所有渠道都采用相同的私信策略模式，dmPolicy 默认值为 "pairing"：

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",    // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"],  // 仅用于 allowlist / open
    },
  },
}

• "pairing"：未知发送者会收到一次性配对码，以供批准
• "allowlist"：仅允许 allowFrom 中的发送者
• "open"：允许所有传入私信（需 allowFrom: ["*"]）
• "disabled"：忽略所有私信

6. 核心功能

智能体

• 支持工具流式传输的嵌入式智能体运行时
• 按工作区或发送者隔离会话的多智能体路由
• 会话：直接聊天合并到共享的 main；群组则相互隔离
• 针对长回复的流式传输和分块

身份验证和模型提供商

• 35+ 个模型提供商（Anthropic、OpenAI、Google 等）
• 通过 OAuth 进行订阅身份验证（例如 OpenAI Codex）
• 支持自定义 / 自托管提供商：vLLM、SGLang、Ollama、llama.cpp、LM Studio 以及任何兼容 OpenAI 或 Anthropic 的端点

工具与自动化

• 浏览器自动化、Exec、沙箱隔离
• Web 搜索（Brave、DuckDuckGo、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax Search、Perplexity、SearXNG、Tavily 等）
• 定时任务（cron）和 Heartbeat 调度
• Skills、插件和工作流流水线（Lobster）
• Webhooks（HTTP 事件触发）、Hooks

7. Gateway 配置

OpenClaw 从 ~/.openclaw/openclaw.json 读取可选的 JSON5 配置。如果文件不存在，OpenClaw 使用安全默认值。

最小配置

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

四种编辑方式

# CLI 示例
openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config unset plugins.entries.brave.config.webSearch.apiKey

⚠️ 严格验证（重要）

• 验证失败时：Gateway 不会启动，只有诊断命令可用（openclaw doctor、openclaw logs、openclaw health、openclaw status）
• 运行 openclaw doctor 查看具体问题；运行 openclaw doctor --fix 应用修复（会从"最后已知良好副本"恢复）
• 被拒绝的写入会保存为 <path>.rejected.<timestamp> 供检查
• Gateway 会阻止看似意外覆盖的写入（如删除 gateway.mode、丢失 meta 块、文件缩小超过一半）

7.1 常见配置任务

① 选择和配置模型

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["openai/gpt-5.4"],   // 主模型不可用时自动回退
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "openai/gpt-5.4": { alias: "GPT" },
      },
    },
  },
}

• 模型引用采用 provider/model 格式（如 anthropic/claude-opus-4-6）
• agents.defaults.modelPolicy.allow 是覆盖和模型选择器的显式允许列表，支持 provider/* 通配符；省略或 [] 允许任何模型
• 自定义 / 自托管提供商：见官方"自定义提供商"参考（兼容 OpenAI / Anthropic 端点均可）

② 控制谁可以发消息

见上文 dmPolicy；群组用 groupPolicy（allowlist | open | disabled）与 groupAllowFrom。

③ 群聊提及门控

群组消息默认要求提及，需为每个智能体配置触发模式：

{
  agents: {
    list: [{
      id: "main",
      groupChat: { mentionPatterns: ["@openclaw", "openclaw"] },
    }],
  },
  channels: {
    whatsapp: { groups: { "*": { requireMention: true } } },
  },
}

• 元数据提及：原生 @ 提及（WhatsApp 点按提及、Telegram @bot 等）
• 文本模式：mentionPatterns 中的安全正则表达式
• 可见回复：messages.visibleReplies 可要求通过消息工具发送

④ 限制每个智能体的 Skills

{
  agents: {
    defaults: { skills: ["github", "weather"] },
    list: [
      { id: "writer" },                 // 继承 github、weather
      { id: "docs", skills: ["docs-search"] },  // 替换默认值
      { id: "locked-down", skills: [] },        // 无 Skills
    ],
  },
}

⑤ 会话与重置

{
  session: {
    dmScope: "per-channel-peer",   // main | per-peer | per-channel-peer | per-account-channel-peer
    threadBindings: { enabled: true, idleHours: 24, maxAgeHours: 0 },
    reset: { mode: "daily", atHour: 4, idleMinutes: 120 },
  },
}

⑥ Heartbeat（定期检查）

{
  agents: { defaults: { heartbeat: { every: "30m", target: "last" } } },
}

every：持续时间字符串（30m、2h；0m 禁用，默认 30m）；target：last | none | <channel-id>。

⑦ 定时任务（cron）

{
  cron: { enabled: true, sessionRetention: "24h" },
}

⑧ Webhooks（Hooks）

{
  hooks: {
    enabled: true,
    token: "shared-secret",        // 专用令牌，勿复用 gateway.auth.token
    path: "/hooks",                // 不能是 "/"
    defaultSessionKey: "hook:ingress",
    mappings: [
      { match: { path: "gmail" }, action: "agent", agentId: "main", deliver: true },
    ],
  },
}

⑨ 多智能体路由

{
  agents: {
    list: [
      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },
      { id: "work", workspace: "~/.openclaw/workspace-work" },
    ],
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
}

⑩ 配置拆分为多个文件（$include）

// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: { $include: ["./clients/a.json5", "./clients/b.json5"] },
}

• 单个文件：替换包含它的对象；文件数组：按顺序深度合并（后者优先）
• 相对路径：相对于执行包含操作的文件解析；最多嵌套 10 层
• 限制范围：$include 路径必须解析到存放 openclaw.json 的目录之下

7.2 热重载与验证

Gateway 网关会监视 ~/.openclaw/openclaw.json 并自动应用更改——大多数设置无需手动重启。看到 config reload skipped (invalid config) 时：运行 openclaw config validate，再 openclaw doctor --fix 修复。

需要重启的更改：gateway.*（端口、绑定、认证、Tailscale、TLS、HTTP、推送）、discovery、browser、plugins.load 等基础设施字段。渠道、智能体、模型、自动化、会话等大多可热应用。

{
  gateway: { reload: { mode: "hybrid", debounceMs: 300 } },
}

环境变量

OpenClaw 从父进程、当前目录 .env、~/.openclaw/.env 读取环境变量；也可在配置中设置内联环境变量，并用 ${VAR_NAME} 引用：

{
  env: { OPENROUTER_API_KEY: "sk-or-...", vars: { GROQ_API_KEY: "gsk-..." } },
  gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } },
}

8. CLI 命令参考

openclaw 是主要 CLI 入口点。输入关键词快速过滤：

按用途划分的核心命令

常用命令速查

全局标志

输出模式：ANSI 颜色与进度指示器仅在 TTY 呈现；--json / --plain 禁用样式。CLI 使用龙虾主题调色板（accent #FF5A2D、success #2FBF71、warn #FFB020、error #E23D2D 等）。

9. 聊天斜杠命令（/）

聊天消息支持 /... 命令，重点功能：

10. 平台、节点与 Web 界面

A. 诊断与故障排查

官方诊断工具

openclaw config validate   # 校验配置
openclaw doctor            # 查看具体问题
openclaw doctor --fix      # 应用修复（恢复最后已知良好副本）

B. 重要环境变量

环境变量来源优先级：父进程 → 当前目录 .env → ~/.openclaw/.env（后两者不覆盖已有变量）。

C. 官方资源