这一篇帮助你先建立全局认知：OpenClaw 不是单纯聊天工具，而是把消息渠道、Gateway 网关和 Agent 能力接在一起的执行型助手框架。它的重点不是“回答得像不像人”，而是“能不能在持续在线的消息环境中稳定接收、理解、执行和回传”。

什么是 OpenClaw

OpenClaw 是一个开源消息网关，它把 WhatsApp、Telegram、Discord、iMessage 等聊天平台连接到 AI Agent，让你能构建一个不下线的个人助手。

• 它可以在多个消息平台上同时运行。
• 它可以执行本地命令和操作、管理文件和工作区。
• 它支持主动发送消息、处理图片音频等多媒体内容。

支持的平台

支持的平台包括WhatsApp、Telegram、Discord、iMessage、Slack、Mattermost、Signal、Microsoft Teams、LINE、Matrix 等都在范围内。你不需要先全部学会，但要知道它的定位从一开始就不是单平台机器人。

核心架构

这一篇还给出三层架构：客户端层承接各类聊天入口，Gateway 层负责消息路由、会话管理、认证授权和工具调用，Agent 层负责真正的模型与执行能力。

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

# 或使用 npm
npm install -g openclaw@latest

# 或使用 pnpm
pnpm add -g openclaw@latest

这一篇的目标非常明确：从零开始，尽快完成第一次可用对话。命令行已保留，方便你直接照着走。

0) 前置条件

这一步主要确认你的运行环境有没有准备好。重点不是配置多复杂，而是避免你后面所有步骤都卡在依赖不满足上。

• Node.js 版本至少要满足 `22`。
• `pnpm` 不是必须，但如果你要走源码构建，会更方便。
• 如果你想启用网页搜索，建议配置 Brave Search 的 API Key。
• macOS 如果只是 CLI + Gateway，不一定要装完整开发环境；Windows 强烈建议用 WSL2，而不是直接在原生 Windows 里跑。

openclaw dashboard
openclaw configure --section web

1) 安装 CLI（推荐）

安装方式优先推荐官方安装脚本，其次才是全局安装。你可以按自己环境选择其中一条。

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

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

# 备选方案
npm install -g openclaw@latest
pnpm add -g openclaw@latest

• 如果你是第一次安装，优先走官方脚本，少踩环境差异的坑。
• 如果你公司环境已经有 `npm` / `pnpm` 规范，也可以走全局安装。

2) 运行引导向导（并安装服务）

这是最核心的一步。`openclaw onboard --install-daemon` 不只是安装，而是会把认证、模型、Gateway、频道和后台服务一起串起来。

openclaw onboard --install-daemon

• 你会选择本地 Gateway 还是远程 Gateway。
• 你会选择认证方式，例如 OAuth 或 API Key。
• 你会设置消息渠道，例如 WhatsApp、Telegram、Discord 等。
• 你会决定是否把 Gateway 装成后台守护进程。
• 注意：WhatsApp / Telegram 更推荐 Node 运行时，不推荐 Bun。

3) 启动 Gateway

如果你在上一步已经安装了后台服务，Gateway 很可能已经在跑；否则就需要你自己检查或前台启动。这一步放在前面是因为后面所有渠道接入都依赖它。

openclaw gateway status
openclaw gateway --port 18789 --verbose

• 本地 Dashboard 默认会跑在 `http://127.0.0.1:18789/`。
• 如果你配置了 token，还要把它填进 Control UI 的连接设置里。
• 注意：如果你用 WhatsApp 或 Telegram，请优先用 Node 运行 Gateway。

3.5) 快速验证（2 分钟）

这一小节的目的很简单：不要等到接入消息渠道后才发现前面基础环境根本没通。先做只读检查，能大幅减少后面排查成本。

openclaw status
openclaw health
openclaw security audit --deep

• `openclaw status`：看当前整体状态。
• `openclaw health`：看健康状况，尤其适合判断 Gateway 和认证是不是就绪。
• `openclaw security audit --deep`：看安全审计结果，帮助你发现高风险配置。

4) 配对并连接你的首个聊天平台

这一步分为 WhatsApp 和其他渠道两类。核心思想是一样的：先把消息入口接上，再进入真实对话。

WhatsApp（QR 登录）

openclaw channels login

执行后要去 WhatsApp 的“已链接设备”里扫码。

Telegram / Discord / 其他

• 向导通常可以帮你把 token 和基础配置写进去。
• 如果你选择手动方式，就要分别去对应渠道文档里填 token、bot 信息和相关参数。
• 注意：Telegram 的第一条私聊可能会先返回一个配对码，没审批前 bot 不一定会直接回复。

5) DM 安全（配对审批）

这是很多人第一次接入后会卡住的地方。默认情况下，未知 DM 不会被直接处理，所以你需要先批准配对。

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <code>

• 如果你第一条消息没有收到正常回复，不一定是坏了，可能只是还没批准。
• 这个设计是安全默认值，避免陌生入口直接调用高权限 Agent。

6) 从源码安装（开发）

这一节是给开发者看的。如果你不是在开发 OpenClaw 本身，可以先跳过；但如果你后面要做更深定制，这一节很有参考价值。

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build
pnpm build
openclaw onboard --install-daemon

# 从仓库直接运行 Gateway
node openclaw.mjs gateway --port 18789 --verbose

• 这条路线适合要改源码、做二次开发或排查更底层问题的人。
• 也可以用 `pnpm openclaw ...` 从仓库里直接执行部分步骤。

7) 端到端验证

前面都做完之后，最后一定要用一条真实测试消息把整条链路打通。只有从消息发出到 Agent 回应都正常，才算真正完成。

openclaw message send --target +15555550123 --message "Hello from OpenClaw"
openclaw status --all
openclaw health

• 如果 `openclaw health` 显示没有认证配置，说明要回到向导重新补认证。
• `openclaw status --all` 是非常好用的只读调试报告。

下一步（可选，但推荐）

如果你已经能跑通一条链路，下一步就该进入更具体的能力场景。

• 如果你想要桌面端体验，可以继续看 macOS 应用、QoderWork 这类路线。
• 如果你想让它能调摄像头、语音或移动设备，可以继续看节点相关文档。
• 如果你要做长期在线或跨设备访问，可以继续看远程访问和 Tailscale。
• 如果你要做企业入口，就继续看飞书、钉钉、企业微信等渠道章节。

这篇会把 Onboarding 向导展开讲清楚，帮助你理解每一步为什么要选，而不是只是机械照着点。对于第一次部署的人来说，它几乎决定了你后面会不会卡住。

1) 本地 vs 远程

首先你需要决定是把 Gateway 放在本机，还是放到远程机器。这个决定会直接影响你的认证方式、token 保存位置、访问方式，以及后面怎么排查问题。

• 本地模式更适合个人实验和快速体验。
• 远程模式更适合长期在线、跨设备访问和消息渠道常驻。
• 如果你准备把它接进企业沟通工具，通常远程模式更稳。

2) 仅本地认证（Anthropic OAuth）

本地认证单独讲，是因为 OAuth 这类认证路径在本地交互环境里更顺手。这里的重点不是“能不能登录”，而是“登录完成后配置会写到哪里”。

3) 设置向导（Gateway 驱动）

Onboarding 向导会以 Gateway 为中心，带你走完模型、认证、频道和守护进程设置，所以它比普通“下一步、下一步”的安装器重要得多。

openclaw onboard
openclaw onboard --install-daemon

• 如果你只是想试一试，先用 `openclaw onboard`。
• 如果你希望它后台常驻，直接用 `--install-daemon`。
• 核心要点：配置会围绕 Gateway 组织，而不是围绕某个单一聊天渠道组织。

4) 权限

很多能力不是“装好了就自然能用”，而是还要看系统权限、应用权限、文件权限和消息渠道权限是否已经打通。

• 桌面控制、文件读写、消息发送、浏览器调用，这些都可能依赖权限。
• 如果权限层没配对，Agent 看起来像“安装好了但什么都做不了”。

5) CLI（可选）

CLI 被列为可选，因为有些用户更适合 GUI，有些用户更适合 CLI。CLI 不是必须，但它在排查和进阶阶段会非常重要。

6) 引导聊天（专用会话）

向导最后不是为了让你“看到安装完成”，而是为了把你带进第一条能正常工作的会话里。也就是“引导聊天”，也就是让你真正完成第一次闭环。

• 如果这一层没有走通，说明前面某一层配置还没闭环。
• 真正的完成标准不是出现一个页面，而是能发消息、能得到回复、能确认当前模型和当前通道。

补充：代理引导仪式、Gmail Hook、远程模式注意事项

此外还有代理引导仪式、可选 Gmail Hook、远程模式注意事项。这些更偏进阶，但能帮助你理解 OpenClaw 不只是“装一个机器人”，而是逐渐形成自己的能力编排。

这篇更偏“跑通之后的稳定化设置”，帮助你把默认配置调整成真正可持续使用的状态。很多人能装起来，但用不顺，通常就卡在这一步。

初始设置在解决什么问题

这一篇的核心目标不是再重复安装，而是帮助你把“第一次能跑通”升级为“之后每次都更稳定”。它会让你去看默认模型、默认工作区、Gateway 参数、消息入口和常用修改入口。

• 基础配置、默认运行方式、后续修改入口，会决定你排查时是不是能快速找到正确位置。
• 有些设置必须在第一次安装后尽快确认，有些可以等到后面再微调。
• 这一步的意义是把“能启动”升级为“能稳定使用”。

TL;DR

• 定制内容尽量放在仓库外，例如 `~/.openclaw/workspace` 和 `~/.openclaw/openclaw.json`。
• 稳定工作流更偏应用内置 Gateway；前沿工作流则会自己跑 Gateway 并保持热更新。

一次性引导与稳定工作流

openclaw setup
openclaw channels login
openclaw health

macOS 应用优先的稳定工作流单独写出来，意思很明确：如果你只想稳定地长期使用，优先让应用自己管理本地 Gateway；只有当你要开发或改源码时，才切到手动运行模式。

前沿工作流（开发 Gateway）

pnpm install
pnpm gateway:watch
openclaw health

要注意：源码开发和日常使用是两种不同工作流，不要混着理解。

这一篇解决的是“为什么我发了消息，它没理我”这类最常见问题。核心是安全 DM 和配对审批机制，也就是 OpenClaw 为什么默认不会轻易相信一个新入口。

为什么要配对

核心安全原则：未知来源的 DM 或新设备不会自动被 OpenClaw 信任。这样做的目的，是防止高权限助手被随便接管。配对分成两类：DM 配对和节点设备配对。

• 新设备或新对话默认不会被直接信任，所以第一次私聊没反应不一定是坏了，而是还没批准。
• 短码、审批和配对白名单是默认安全姿态。
• 不同渠道的第一条消息行为可能不同，尤其 Telegram 类机器人入口更容易在这里卡住。

1) DM 配对

当通道配置成 `pairing` 策略时，未知发送者会收到短码，消息在你批准前不会被处理。配对码规则：8 位大写字符、避开易混淆字符、1 小时过期、每个通道默认最多 3 个待处理请求。

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <code>

常见支持频道包括 `telegram`、`whatsapp`、`signal`、`imessage`、`discord`、`slack`。

2) 节点设备配对

第二类是设备或节点加入 Gateway 网络时的配对，这适用于 iOS、Android、macOS 或无头节点。

openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>

你要怎么判断是不是配对问题

• 如果 Gateway 正常、模型也正常，但消息没响应，优先怀疑配对。
• 如果渠道回了一个短码或提示审批，那基本就是配对环节未完成。
• 只有批准完成后，会话才会真正进入可处理状态。

这一篇的目标是把 OpenClaw 从"跑起来了"变成"像你的私人助手"。它涵盖安全隔离、工作区搭建、人格配置、会话管理和心跳机制，是从部署走向长期使用的关键一步。

安全第一：双手机方案

OpenClaw 建议使用专用的第二个 WhatsApp 号码作为助手入口，而不是把你的个人号码直接接上去。这样可以避免所有发给你的消息都变成"代理输入"。

• 始终设置 channels.whatsapp.allowFrom 白名单，避免开放式接入。
• 心跳默认每 30 分钟一次，在信任设置前建议先禁用：agents.defaults.heartbeat.every: "0m"。
• 前置条件：Node 22+，OpenClaw 已在 PATH 中，以及第二个电话号码。

5 分钟快速开始

# 1. 配对 WhatsApp Web（用助手手机扫码）
openclaw channels login

# 2. 启动 Gateway
openclaw gateway --port 18789

# 3. 在 ~/.openclaw/openclaw.json 中设置白名单
# { channels: { whatsapp: { allowFrom: ["+15555550123"] } } }

给代理一个工作区

OpenClaw 默认使用 ~/.openclaw/workspace 作为代理工作区，首次启动时会自动创建 AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md 等核心文件。你可以通过修改这些文件来定义助手的身份、偏好和行为规则。

openclaw setup

会话与记忆

• 会话文件保存在 ~/.openclaw/agents/<agentId>/sessions/。
• 发送 /new 或 /reset 可以为当前聊天启动新会话。
• 发送 /compact [instructions] 可以压缩会话上下文并报告剩余预算。

心跳（主动模式）

OpenClaw 默认每 30 分钟运行一次心跳，检查 HEARTBEAT.md 并按指令执行。如果没有需要关注的内容，代理会回复 HEARTBEAT_OK 并抑制该心跳的出站投递。心跳运行完整的代理轮次，因此较短间隔会消耗更多 token。

媒体输入和输出

• 入站：图片、音频、文档等附件可通过 {{MediaPath}}、{{MediaUrl}}、{{Transcript}} 传递给命令。
• 出站：在回复中使用 MEDIA:<path-or-url> 即可附带发送媒体文件。

这一篇汇集了社区里用 OpenClaw 构建的真实项目。它不是命令教程，而是帮助你建立"Agent 真正能做什么"的直觉，看到 OpenClaw 在各种场景中的实际价值。

开发与代码协作

• PR 审查 → Telegram 反馈：OpenCode 完成更改并打开 PR，OpenClaw 自动审查 diff 并在 Telegram 中回复审查意见和合并结论。
• 沙发开发模式：有人边看 Netflix 边通过 Telegram 重建了整个个人网站（Notion → Astro），迁移了 18 篇文章和 DNS，全程没打开笔记本。

生活与自动化

• Tesco 购物自动化：每周膳食计划 → 常规商品 → 预订配送 → 确认订单，无 API，纯浏览器控制。
• 帕德尔球场预订：自动检查 Playtomic 空闲球场并预订。
• 求职代理：搜索职位列表，对比简历关键词，返回匹配的机会和链接。

智能家居与 IoT

• Home Assistant 插件：在 Home Assistant OS 上运行 OpenClaw gateway，支持 SSH 隧道和持久状态。
• Winix 空气净化器控制：Agent 自动管理房间空气质量。
• Roborock 扫地机器人：通过自然对话控制扫地机器人。

工具与技能

• SNAG 截图转 Markdown：快捷键选区 → Gemini 视觉 → 即时 Markdown 到剪贴板。
• 酒窖技能：基于 CSV 导出快速构建本地酒窖管理技能（示例含 962 瓶）。
• TradingView 分析：通过浏览器自动化截图图表，按需执行技术分析。
• WhatsApp 记忆库：导入完整 WhatsApp 导出，转录 1000+ 语音备忘录，输出链接的 markdown 报告。

这一部分带你深入了解 OpenClaw 的前世今生，并为你提供后续深入探索的权威入口。

Lore：从 Moltbot 到 OpenClaw

OpenClaw 起源于一个名为 Moltbot 的项目。它的诞生并非为了创造一个通用的聊天机器人，而是开发者 Peter 为自己的龙虾吉祥物 Molty 赋予“灵魂”和“执行力”的尝试。随着 20 多次的迭代，它从一个简单的脚本演变成了支持多渠道、高扩展性的 Agent 网关。"爪子即法律"（Claw is Law）也成为了其开发哲学的核心：稳定执行优于华丽辞藻。

资料中心：你的进阶宝库

如果你在教程之外有更具体的需求（如特定的模型支持、特定的 UI 定制），可以访问中文社区的文档中心。那里涵盖了从 Bun 工作流到 Docker/Nix 安装的全部技术细节。

• 快速查阅：配置示例、故障排除、安全加固。
• 深度解析：Agent 运行时架构、会话裁剪机制、命令队列原理。

对于国内用户，将 Agent 接入主流办公软件和通讯工具是提升效率的关键。OpenClaw 对国内生态提供了深度适配。

1.10 飞书 (Feishu/Lark)

能力：不仅是聊天，更能直接读写飞书云文档、管理知识库节点和操作云盘。它是目前与企业流程整合度最高的渠道。

• 关键点：需要在飞书开放平台创建应用，并配置事件订阅 URL 以接收消息回调。
• 提示：记得在 OpenClaw 中配置 AppID 和 AppSecret。

1.11 QQ 机器人

能力：基于 QQ 开放平台，支持单聊与群聊。适合社群管理和个人快速互动。

• 流程：注册开放平台 → 创建机器人 → 沙箱成员配置 → 在 OpenClaw 后台应用凭据。

1.12 钉钉 (DingTalk)

能力：支持通过 Outgoing Webhook 或企业自建 Bot 接入。适合在钉钉工作流程中触发自动化指令。

微信作为最核心的通讯工具，OpenClaw 通过两种不同的引擎提供了支持，满足不同场景下的稳定性与功能需求。

1.13 WeChaty - 强大且专业

WeChaty 是一个多平台的微信 SDK。它支持多种 Puppet（Puppeteer, PadLocal, Service 等），功能非常全面，支持群发、关键词过滤和复杂的朋友圈/群组交互。

1.14 MyWecat - 轻量且便捷

相比之下，MyWecat 更加轻量，主打快速配置。如果你只需要实现简单的消息自动回复或个人助手功能，MyWecat 的上手门槛更低。

\n

这一部分涵盖了 OpenClaw 出生即自带的国际主流通讯渠道，以及当你遇到疑难杂症时的终极解决指南。

主流国际渠道 (1.15 - 1.19)

• Telegram: 开发者最爱的频道，API 极度友好，支持丰富的多媒体交互。
• Discord: 适合团队协作和大规模社群，支持斜杠命令集成。
• WhatsApp: 最通用的国际即时通讯工具，推荐配合双手机方案使用。
• iMessage / Signal / Slack / Mattermost: 提供从系统原生集成到企业级插件的全面支持。

系统诊断与运维 (1.20 - 1.21)

# 环境健康检查：自动排查依赖和权限问题
openclaw doctor

# 深度状态监测：检查通道连接、模型可用性和会话积压
openclaw status --deep

# 后台清理与重连：当某个通道卡死时使用
openclaw channels reset [name]

这是最容易上手理解的案例之一。你可以直观看到 Agent 如何根据明确规则把文件整理好，也能顺便理解为什么规则清晰的任务最适合自动化。

这个案例会帮助你看到，Agent 不只是写几句话，而是可以把搜集、整理、生成、投递串起来，形成一个完整流程。

这个案例能帮助你理解，Agent 不一定只待在网页里，也可以进入飞书这类你本来就在用的工作环境。

这个案例更偏进阶。你会看到 Agent 如何把笔记、对话和记忆整理成一个统一入口，但也要知道这类系统需要长期维护和约束。