OpenClaw 使用指南

发表于 分类于 本文字数： 11k 阅读时长 ≈ 19 分钟

使用OpenClaw来生成的OpenClaw使用文档，文档写的挺专业，配置OpenClaw时查找命令非常不错。

OpenClaw 是一个开源、自托管的 AI 网关，将多种聊天应用（WhatsApp、Telegram、Discord、iMessage 等）与 AI 助手连接起来。运行在你自己选择的机器上，数据完全由你掌控。

1. 核心概念

Gateway（网关）

OpenClaw 的核心是一个长时间运行的 Gateway 进程，它：

  • 管理所有聊天渠道的连接（WhatsApp、Telegram、Discord 等）
  • 处理与 AI Agent 的通信
  • 提供 WebSocket API 给控制面板、CLI、移动端节点使用
  • 默认监听 http://127.0.0.1:18789
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
┌─────────────────────────────────────────────┐
│              Gateway (单一进程)              │
│                                             │
│  ┌──────────┐  ┌──────────┐  ┌───────────┐  │
│  │ WhatsApp │  │ Telegram │  │  Discord  │  │
│  └──────────┘  └──────────┘  └───────────┘  │
│                                             │
│  ┌──────────┐  ┌──────────┐  ┌───────────┐  │
│  │  Web UI  │  │    CLI   │  │   移动节点  │  │
│  └──────────┘  └──────────┘  └───────────┘  │
│                                             │
│              ┌──────────────┐               │
│              │  AI Agent    │               │
│              └──────────────┘               │
└─────────────────────────────────────────────┘

Agent

Agent 是 AI 对话的实际执行者。每个 Agent 有：

  • 独立的 workspace — 文件系统上的工作目录
  • 独立的会话 — 对话历史和上下文
  • 独立的工具策略 — 允许使用哪些工具
  • 独立的身份和绑定 — 绑定到特定的渠道或账号

Session（会话）

会话决定了同一对话中的消息如何被关联：

模式 行为
main 所有 DM 共享一个主会话
per-peer 每个发送者一个会话
per-channel-peer 每个渠道+发送者组合一个会话
per-account-channel-peer 每个账号+渠道+发送者一个会话

Channel（渠道）

渠道是 OpenClaw 连接的具体聊天平台。内置支持：

  • WhatsApp — 通过 Baileys 库，需要 QR 码配对
  • Telegram — 通过 Bot API，最快配置
  • Discord — 机器人账号
  • iMessage — 通过 BlueBubbles（macOS）

插件渠道：

  • Mattermost、Slack、Microsoft Teams、Signal、Matrix 等

DM 安全策略

每个渠道独立控制谁可以发送 DM：

  • pairing（默认）：未知发送者获得一次性配对码，需管理员审批
  • allowlist：仅 allowFrom 列表中的用户可以 DM
  • open：允许所有人 DM（需要 allowFrom: ["*"]）
  • disabled：禁用所有 DM

配置存储

OpenClaw 的配置文件位于 ~/.openclaw/openclaw.json（JSON5 格式，支持注释）。

2. 安装

环境要求

  • Node.js：Node 24（推荐）或 Node 22.14+
  • 操作系统：macOS、Linux、Windows (WSL2 推荐)
  • API Key：来自模型提供商（Anthropic、OpenAI、Google 等）

安装命令

macOS / Linux：

1
curl -fsSL https://openclaw.ai/install.sh | bash

Windows (PowerShell)：

1
iwr -useb https://openclaw.ai/install.ps1 | iex

其他方式（npm）：

1
npm install -g openclaw@latest

验证安装：

1
openclaw --version

3. 快速开始

步骤 1：引导式初始化

1
openclaw onboard --install-daemon

向导会依次询问：

  1. 模型/认证 — 选择提供商并输入 API Key
  2. 工作空间 — Agent 文件存储位置（默认 ~/.openclaw/workspace）
  3. 网关 — 端口、绑定地址、认证方式
  4. 渠道 — 配置 WhatsApp/Telegram/Discord 等
  5. 守护进程 — 安装系统服务使网关后台运行
  6. 健康检查 — 验证网关是否正常运行
  7. 技能 — 安装推荐的 Skills

步骤 2：验证网关运行

1
openclaw gateway status

步骤 3：打开控制面板

1
openclaw dashboard

浏览器访问 http://127.0.0.1:18789/ ，输入网关令牌登录。

步骤 4：发送第一条消息

在控制面板中直接发送消息，或配置 Telegram 以手机聊天：

1
openclaw channels add --channel telegram --token $TELEGRAM_BOT_TOKEN

4. 配置

配置文件位置

~/.openclaw/openclaw.json（JSON5 格式）

配置方式

方式一：交互式向导

1
2
openclaw onboard        # 完整引导
openclaw configure      # 配置向导

方式二：CLI 单行命令

1
2
3
4
5
6
7
8
# 获取值
openclaw config get agents.defaults.workspace

# 设置值
openclaw config set agents.defaults.heartbeat.every "2h"

# 删除值
openclaw config unset plugins.entries.brave.config.webSearch.apiKey

方式三：直接编辑

1
nano ~/.openclaw/openclaw.json

网关会自动监视文件并热重载大部分配置（无需重启）。

方式四：控制面板
打开 http://127.0.0.1:18789/ → Config tab，以表单或原始 JSON 编辑。

热重载规则

分类 字段 是否需要重启
渠道 channels.* ❌ 无需
Agent & 模型 agents.*, models.* ❌ 无需
自动化 hooks, cron, heartbeat ❌ 无需
会话 & 消息 session, messages ❌ 无需
网关服务 gateway.*（端口、绑定、TLS） ✅ 需要

常用配置示例

最小配置（仅 WhatsApp）：

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

多渠道配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
    },
    discord: {
      enabled: true,
      botToken: "xyz",
      dmPolicy: "allowlist",
      allowFrom: ["user:123", "user:456"],
    },
  },
}

多模型配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-7",
        fallbacks: ["openai/gpt-5.2"],
      },
      models: {
        "anthropic/claude-sonnet-4-7": { alias: "Sonnet" },
        "openai/gpt-5.2": { alias: "GPT" },
      },
    },
  },
}

5. 渠道（Channels）

支持的渠道

渠道 类型 配置难度 说明
Telegram 内置 ⭐ 最简单 只需 Bot Token
WhatsApp 内置 ⭐⭐ 需要 QR 码配对
Discord 内置 ⭐⭐ 需要机器人账号
iMessage 内置 ⭐⭐⭐ 通过 BlueBubbles（macOS）
Signal 内置 ⭐⭐⭐ 通过 signal-cli
Slack 插件 ⭐⭐ Bolt SDK
Microsoft Teams 插件 ⭐⭐⭐ Bot Framework
Mattermost 插件 ⭐⭐ WebSocket 支持
Matrix 插件 ⭐⭐ 协议支持
Google Chat 内置 ⭐⭐ HTTP Webhook

Telegram 快速配置

1
2
3
4
5
6
7
8
9
10
11
# 1. 创建机器人
# 找 @BotFather，发送 /newbot，获取 Bot Token

# 2. 添加渠道
openclaw channels add --channel telegram --token $TELEGRAM_BOT_TOKEN

# 3. 设置 DM 策略
openclaw config set channels.telegram.dmPolicy "pairing"

# 4. 测试
openclaw channels status

WhatsApp 配置

1
2
3
4
5
6
# 启动 QR 码登录
openclaw channels login --channel whatsapp

# 扫描后设置白名单
openclaw config set channels.whatsapp.allowFrom ["+15555550123"]
openclaw config set channels.whatsapp.dmPolicy "allowlist"

Discord 配置

1
2
3
4
5
6
7
# 1. 在 Discord Developer Portal 创建应用 → Bot
# 2. 启用 Message Content Intent
# 3. 添加 Bot 到服务器

# 4. 配置
openclaw channels add --channel discord --token $DISCORD_BOT_TOKEN
openclaw config set channels.discord.dmPolicy "pairing"

群组配置

群组消息默认需要 @提及才响应。配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: true },
      },
    },
  },
  agents: {
    list: [{
      id: "main",
      groupChat: {
        mentionPatterns: ["@openclaw", "openclaw"],
      },
    }],
  },
}

6. CLI 命令参考

核心命令

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# 初始化 & 向导
openclaw onboard              # 引导式初始化
openclaw configure           # 配置向导

# 网关管理
openclaw gateway status       # 查看网关状态
openclaw gateway start       # 启动网关
openclaw gateway stop        # 停止网关
openclaw gateway restart     # 重启网关
openclaw dashboard            # 打开控制面板

# 配置
openclaw config get <path>    # 获取配置值
openclaw config set <path> <value>  # 设置配置值
openclaw config file          # 显示配置文件路径
openclaw config validate     # 验证配置

# 健康 & 诊断
openclaw doctor               # 健康检查 + 修复
openclaw health               # 网关健康状态
openclaw status               # 系统状态
openclaw logs                 # 查看日志

渠道管理

1
2
3
4
5
6
7
openclaw channels list        # 列出所有渠道
openclaw channels status      # 渠道状态
openclaw channels add         # 添加渠道（交互式）
openclaw channels add --channel telegram --token xxx  # 非交互式
openclaw channels remove --channel discord
openclaw channels login --channel whatsapp  # QR 登录
openclaw channels logout --channel whatsapp  # 登出

Agent 管理

1
2
3
4
5
6
7
8
9
openclaw agents list          # 列出所有 Agent
openclaw agents add <name>    # 添加新 Agent
openclaw agents delete <id>   # 删除 Agent
openclaw agents bindings      # 查看路由绑定

# 切换/选择模型
openclaw models list          # 列出可用模型
openclaw models set <model>   # 设置默认模型
openclaw models status        # 模型状态

会话 & 消息

1
2
3
4
5
6
7
8
openclaw sessions             # 列出会话
openclaw message send --target <id> --message "Hello"

# Cron 定时任务
openclaw cron list            # 列出定时任务
openclaw cron add --name "daily" --every "1d" --system-event "..."
openclaw cron rm <id>
openclaw cron run <id>        # 手动触发

Skills（技能）

1
2
3
4
5
openclaw skills list          # 列出已安装技能
openclaw skills search <query>  # 搜索 ClawHub
openclaw skills install <slug>  # 安装技能
openclaw skills update <slug>    # 更新技能
openclaw skills info <name>   # 技能详情

配对 & 设备

1
2
3
4
openclaw pairing list          # 列出待处理配对请求
openclaw pairing approve <channel> <code>  # 批准配对
openclaw devices list         # 列出已配对设备
openclaw devices approve <requestId>  # 批准设备

浏览器控制

1
2
3
4
openclaw browser status       # 浏览器状态
openclaw browser start        # 启动浏览器
openclaw browser open <url>   # 打开 URL
openclaw browser screenshot   # 截图

其他

1
2
3
4
openclaw backup create         # 创建备份
openclaw update               # 更新 OpenClaw
openclaw uninstall             # 卸载
openclaw docs <query>          # 搜索文档

7. Web 控制面板

控制面板是浏览器中的管理界面，默认地址：

1
http://127.0.0.1:18789/

功能

  • Chat — 直接发送消息给 Agent
  • Sessions — 查看和管理对话会话
  • Config — 可视化配置编辑器
  • Nodes — 管理配对的移动节点
  • Logs — 实时日志查看

首次连接

  1. 打开 http://127.0.0.1:18789/

  2. 输入 Gateway Token（在初始化时生成，保存在 ~/.openclaw/openclaw.json 的 gateway.auth.token 字段）

  3. 首次在新设备连接时需要配对审批：

    1
    2
    openclaw devices list        # 查看待审批请求
    openclaw devices approve <requestId>

远程访问

方式一：Tailscale

1
openclaw gateway --tailscale serve

方式二：SSH 隧道

1
ssh -L 18789:127.0.0.1:18789 user@your-server

8. 多 Agent 与路由

为什么要多 Agent？

  • 为不同场景隔离工作空间（工作/个人）
  • 不同渠道绑定不同 Agent
  • 不同 Agent 使用不同模型或工具策略

添加新 Agent

1
openclaw agents add work --workspace ~/.openclaw/workspace-work

配置路由绑定

1
2
3
4
5
6
7
8
9
10
11
12
{
  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" } },
  ],
}

指令中切换 Agent

在支持 slash 命令的渠道（如 Discord）：

  • /focus — 进入专注会话
  • /unfocus — 退出专注会话
  • /agents — 列出可用 Agent
  • /session idle — 空闲会话超时设置

9. 自动化与定时任务

Cron 定时任务

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 创建一个每天早上 9 点执行的任务
openclaw cron add \
  --name "daily-briefing" \
  --cron "0 9 * * *" \
  --system-event "发送每日简报"

# 创建每隔 30 分钟检查一次的任务
openclaw cron add \
  --name "health-check" \
  --every "30m" \
  --message --target "#alerts" "健康检查"

# 列出所有任务
openclaw cron list

# 手动触发
openclaw cron run <jobId>

# 删除
openclaw cron rm <jobId>

Heartbeat（心跳）

定期让 Agent 执行检查任务：

1
2
3
4
5
6
7
8
9
10
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",      // 间隔
        target: "last",    // 回复到最后一个活跃会话
      },
    },
  },
}

Webhooks / Hooks

接入外部 HTTP 服务：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        agentId: "main",
        deliver: true,
      },
    ],
  },
}

10. 节点（Nodes）

OpenClaw 支持配对 iOS、Android、macOS 设备作为节点，提供：

  • Canvas — 屏幕截图、URL 导航
  • Camera — 拍照和录制视频
  • Screen Recording — 屏幕录制
  • Location — 获取位置
  • Voice — 语音交互
  • 通知 — 推送系统通知

macOS 节点

在 macOS 上安装节点：

1
openclaw nodes install

iOS / Android

  1. 从 App Store / Play Store 安装 OpenClaw 应用

  2. 扫描网关上的配对二维码

  3. 审批配对请求：

    1
    2
    openclaw nodes pending    # 查看待审批
    openclaw nodes approve <requestId>

节点命令示例

1
2
3
4
5
6
7
8
9
10
11
# 查看已连接节点
openclaw nodes status

# 节点截图
openclaw nodes camera snap --node my-iphone

# 获取节点屏幕内容
openclaw nodes canvas snapshot --node my-iphone

# 在节点上执行命令
openclaw nodes run --node my-mac --command "echo hello"

11. 安全设置

DM 访问控制

1
2
3
4
5
6
7
8
{
  channels: {
    telegram: {
      dmPolicy: "pairing",    // 默认：需要配对审批
      allowFrom: ["tg:123"],  // allowlist 模式下允许的用户
    },
  },
}

配对审批

1
2
3
4
5
# 查看待处理配对请求
openclaw pairing list

# 批准配对
openclaw pairing approve telegram ABC123

设备管理

1
2
3
4
5
6
7
8
# 列出已配对设备
openclaw devices list

# 撤销设备访问
openclaw devices revoke --device <deviceId> --role operator

# 清除所有设备
openclaw devices clear --yes --pending

安全审计

1
2
3
openclaw security audit       # 基础审计
openclaw security audit --deep # 深度审计（含实时探测）
openclaw security audit --fix # 自动修复安全建议

建议的安全实践

  1. 不要设置 dmPolicy: "open" — 使用 pairing 或 allowlist
  2. 为每个渠道配置 allowFrom 白名单
  3. 群组中启用 requireMention: true
  4. 定期运行 openclaw security audit
  5. 使用 Token 认证而非密码认证

12. 故障排除

常见问题

Gateway 无法启动

1
2
3
4
5
# 检查端口占用
openclaw doctor

# 查看详细日志
openclaw logs --lines 100

WhatsApp 连接断开

1
2
3
# 重新登录
openclaw channels logout --channel whatsapp
openclaw channels login --channel whatsapp

Telegram Bot 无响应

1
2
3
4
5
# 检查 Bot Token 是否正确
openclaw config get channels.telegram.botToken

# 检查频道状态
openclaw channels status --probe

配置验证失败

1
2
3
4
5
# 查看具体错误
openclaw config validate

# 自动修复
openclaw doctor --fix

日志查看

1
2
3
4
5
6
7
8
# 实时日志
openclaw logs --follow

# 最近 200 行
openclaw logs --lines 200

# JSON 格式输出
openclaw logs --json

健康检查

1
2
3
openclaw doctor              # 完整诊断
openclaw doctor --deep       # 深度扫描（检测重复安装）
openclaw doctor --fix        # 自动修复

重置

1
2
3
4
5
# 重置配置（保留 CLI）
openclaw reset --scope config --yes

# 完全重置
openclaw reset --scope full --yes

附录：配置文件完整参考

完整配置字段参考请查阅官方文档：

获取帮助

祝你使用愉快，🦞 OpenClaw 会是你最得力的 AI 助手！

AI 总结 (Qwen API)

生成时间: 2026-03-28 23:28:57

深度总结：

OpenClaw 是一个面向隐私优先、自托管场景的 AI 网关系统，其核心价值在于将异构即时通讯平台（WhatsApp/Telegram/Discord/iMessage 等）统一接入本地运行的 AI 助手生态，实现“消息即接口、聊天即工作流”的智能代理架构。它并非单一聊天机器人，而是一个可编程、可扩展、安全可控的AI 对话基础设施层。

系统采用清晰的分层设计：
🔹 Gateway（网关） 作为中央协调进程，承担连接管理、协议适配、API 路由与状态同步；
🔹 Agent 是语义与能力单元——每个 Agent 拥有独立工作空间、会话上下文、工具权限和模型策略，支持细粒度隔离与专业化分工；
🔹 Channel（渠道） 是双向通信端点，内置主流平台支持 + 插件化扩展机制，兼顾开箱即用性与企业集成能力；
🔹 Session 模型 提供多级会话粒度（per-peer 到 per-account-channel-peer），精准建模真实对话关系；
🔹 安全模型 以“默认最小权限”为原则，通过 pairing 配对审批、白名单 DM 控制、设备信任链、Token 认证等机制构筑纵深防御；
🔹 运维体系 高度成熟：支持热重载配置、CLI 全生命周期管理、Web 控制面板、跨平台节点（iOS/macOS/Android）、自动化 Cron/Heartbeat/Hooks，以及一键诊断（openclaw doctor）与审计（security audit）。

其技术哲学体现为：去中心化控制权 + 中心化协调能力 + 边缘化执行智能——数据永不离境，逻辑高度可定制，部署极度轻量（Node.js 单进程），同时通过 Skills（ClawHub 技能市场）和插件渠道实现生态可延展性。

核心关键词标签（3–5 个）：

#AI网关 #自托管AI #多渠道集成 #Agent架构 #隐私优先