OpenClaw (Clawdbot)— 个人 AI 助手，安装部署

优质文章学习记录

07 Apr 2026 — 14 min read

🦞 OpenClaw(原名Clawdbot) — 个人 AI 助手

OpenClaw 是一款运行在您自有设备上的个人 AI 助手。
它支持您已在使用的各种通信渠道（WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、iMessage、Microsoft Teams、WebChat），以及扩展渠道如 BlueBubbles、Matrix、Zalo 和 Zalo Personal。它可在 macOS/iOS/Android 上进行语音交互，并能渲染一个由您控制的实时画布（Canvas）。网关（Gateway）仅作为控制平面，产品本身是这个助手。

如果您希望拥有一款感觉本地化、快速且始终在线的个人单用户助手，那么就是它了。

官网 · 文档 · DeepWiki · 入门指南 · 更新指南 · 功能展示 · 常见问题 · 向导工具 · Nix · Docker · Discord

推荐设置：运行初始化向导（openclaw onboard）。该向导将引导您完成网关、工作区、渠道和技能的配置。CLI 向导是推荐方式，支持 macOS、Linux 和 Windows（通过 WSL2；强烈推荐）。
支持 npm、pnpm 或 bun。
全新安装？请从这里开始：入门指南

订阅服务（OAuth）：

Anthropic（Claude Pro/Max）
OpenAI（ChatGPT/Codex）

模型说明：虽然支持任意模型，但强烈推荐使用 Anthropic Pro/Max（100/200）+ Opus 4.5，因其在长上下文处理能力和更强的提示注入防护方面表现更佳。详见初始化配置。

模型（选择 + 认证）

模型配置与 CLI：模型
认证配置切换（OAuth 与 API 密钥）及备用方案：模型故障转移

安装（推荐方式）

运行环境：Node ≥22。

npminstall -g openclaw@latest # 或：pnpm add -g openclaw@latest openclaw onboard --install-daemon

该向导会安装 Gateway 守护进程（launchd/systemd 用户服务），使其持续运行。

快速入门（TL;DR）

运行环境：Node ≥22。

完整新手指南（认证、配对、渠道）：入门指南

openclaw onboard --install-daemon openclaw gateway --port 18789 --verbose # 发送消息 openclaw message send --to +1234567890 --message "Hello from OpenClaw"# 与助手对话（可选：将回复发送至任意已连接渠道：WhatsApp/Telegram/Slack/Discord/Google Chat/Signal/iMessage/BlueBubbles/Microsoft Teams/Matrix/Zalo/Zalo Personal/WebChat） openclaw agent --message "Ship checklist" --thinking high

需要升级？请参考更新指南（并运行 openclaw doctor）。

开发渠道

stable：带标签的正式发布版本（vYYYY.M.D 或 vYYYY.M.D-<patch>），npm 分发标签为 latest。
beta：预发布版本（vYYYY.M.D-beta.N），npm 分发标签为 beta（macOS 应用可能缺失）。
dev：main 分支的最新代码，npm 分发标签为 dev（若已发布）。

切换渠道（git + npm）：openclaw update --channel stable|beta|dev。
详情：开发渠道。

从源码构建（开发用途）

建议使用 pnpm 从源码构建。Bun 可选，用于直接运行 TypeScript。

git clone https://github.com/openclaw/openclaw.git cd openclaw pnpminstallpnpm ui:build # 首次运行时自动安装 UI 依赖pnpm build pnpm openclaw onboard --install-daemon # 开发循环（TS 文件变更时自动重载）pnpm gateway:watch

注意：pnpm openclaw ... 通过 tsx 直接运行 TypeScript。pnpm build 生成 dist/ 目录，可用于通过 Node 或打包后的 openclaw 二进制文件运行。

安全默认设置（私信访问）

OpenClaw 会连接真实的即时通讯平台。请将所有入站私信视为不可信输入。

完整安全指南：安全

Telegram/WhatsApp/Signal/iMessage/Microsoft Teams/Discord/Google Chat/Slack 的默认行为：

私信配对（dmPolicy="pairing" / channels.discord.dm.policy="pairing" / channels.slack.dm.policy="pairing"）：未知发件人将收到一个简短的配对码，机器人不会处理其消息。
通过以下命令批准：openclaw pairing approve <channel> <code>（随后该发件人将被加入本地允许列表）。
公开接收私信需显式启用：设置 dmPolicy="open" 并在渠道允许列表中包含 "*"（allowFrom / channels.discord.dm.allowFrom / channels.slack.dm.allowFrom）。

运行 openclaw doctor 可检测存在风险或配置不当的私信策略。

亮点功能

本地优先网关 —— 统一的控制平面，用于管理会话、渠道、工具和事件。
多渠道收件箱 —— 支持 WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、iMessage、BlueBubbles、Microsoft Teams、Matrix、Zalo、Zalo Personal、WebChat、macOS、iOS/Android。
多代理路由 —— 将入站渠道/账号/联系人路由至隔离的代理（工作区 + 每个代理的独立会话）。
语音唤醒 + 对话模式 —— 基于 ElevenLabs，在 macOS/iOS/Android 上实现始终在线的语音交互。
实时画布 —— 由代理驱动的可视化工作区，支持 A2UI。
一流工具支持 —— 浏览器、画布、节点、定时任务、会话，以及 Discord/Slack 操作。
配套应用 —— macOS 菜单栏应用 + iOS/Android 节点。
初始化向导 + 技能 —— 通过向导驱动的设置流程，内置/托管/工作区技能。

Star 历史

我们迄今构建的一切

核心平台

网关 WS 控制平面，包含会话、在线状态、配置、定时任务、Webhook、控制 UI 和画布主机。
CLI 接口：gateway、agent、send、向导和诊断工具。
Pi 代理运行时，支持 RPC 模式、工具流和区块流。
会话模型：main 用于直接聊天，支持群组隔离、激活模式、队列模式、回复功能。群组规则：群组。
媒体管道：图像/音频/视频、转录钩子、大小限制、临时文件生命周期。音频详情：音频。

渠道

渠道：WhatsApp（Baileys）、Telegram（grammY）、Slack（Bolt）、Discord（discord.js）、Google Chat（Chat API）、Signal（signal-cli）、iMessage（imsg）、BlueBubbles（扩展）、Microsoft Teams（扩展）、Matrix（扩展）、Zalo（扩展）、Zalo Personal（扩展）、WebChat。
群组路由：提及门控、回复标签、按渠道分块与路由。渠道规则：渠道。

应用 + 节点

macOS 应用：菜单栏控制平面、语音唤醒/PTT、对话模式覆盖层、WebChat、调试工具、远程网关控制。
iOS 节点：画布、语音唤醒、对话模式、摄像头、屏幕录制、Bonjour 配对。
Android 节点：画布、对话模式、摄像头、屏幕录制、可选短信功能。
macOS 节点模式：system.run/notify + 画布/摄像头暴露。

工具 + 自动化

浏览器控制：专用的 openclaw Chrome/Chromium，支持快照、操作、上传、配置文件。
画布：A2UI 推送/重置、执行、快照。
节点：摄像头拍照/录像、屏幕录制、location.get、通知。
定时任务 + 唤醒；Webhook；Gmail Pub/Sub。
技能平台：内置、托管和工作区技能，支持安装门控 + UI。

运行时 + 安全

运维 + 打包

控制 UI + WebChat 由网关直接提供服务。
通过 Tailscale Serve/Funnel 或 SSH 隧道提供远程访问，支持令牌/密码认证。
Nix 模式用于声明式配置；基于 Docker 的安装。
诊断工具迁移、日志记录。

工作原理（简述）

WhatsApp / Telegram / Slack / Discord / Google Chat / Signal / iMessage / BlueBubbles / Microsoft Teams / Matrix / Zalo / Zalo Personal / WebChat │ ▼ ┌───────────────────────────────┐ │ 网关 (Gateway) │ │ (控制平面) │ │ ws://127.0.0.1:18789 │ └──────────────┬────────────────┘ │ ├─ Pi 代理 (RPC) ├─ CLI (openclaw …) ├─ WebChat UI ├─ macOS 应用 └─ iOS / Android 节点

关键子系统

网关 WebSocket 网络 —— 单一 WS 控制平面，用于客户端、工具和事件（以及运维：网关操作手册）。
Tailscale 暴露 —— 通过 Serve/Funnel 提供网关仪表盘 + WS（远程访问：远程）。
浏览器控制 —— openclaw 管理的 Chrome/Chromium，支持 CDP 控制。
画布 + A2UI —— 代理驱动的可视化工作区（A2UI 主机：画布/A2UI）。
语音唤醒 + 对话模式 —— 始终在线的语音和持续对话。
节点 —— 画布、摄像头拍照/录像、屏幕录制、location.get、通知，以及 macOS 专属的 system.run/system.notify。

Tailscale 访问（网关仪表盘）

OpenClaw 可自动配置 Tailscale Serve（仅限 tailnet 内部）或 Funnel（公开），同时网关仍绑定到本地回环地址。配置 gateway.tailscale.mode：

off：不启用 Tailscale 自动化（默认）。
serve：通过 tailscale serve 提供仅限 tailnet 的 HTTPS（默认使用 Tailscale 身份头）。
funnel：通过 tailscale funnel 提供公开 HTTPS（需共享密码认证）。

注意事项：

启用 Serve/Funnel 时，gateway.bind 必须保持为 loopback（OpenClaw 会强制执行）。
通过设置 gateway.auth.mode: "password" 或 gateway.auth.allowTailscale: false，可强制 Serve 要求密码。
Funnel 除非设置了 gateway.auth.mode: "password"，否则拒绝启动。
可选：设置 gateway.tailscale.resetOnExit，在关闭时自动撤销 Serve/Funnel。

详情：Tailscale 指南 · Web 界面

远程网关（Linux 很棒）

在小型 Linux 实例上运行网关完全可行。客户端（macOS 应用、CLI、WebChat）可通过 Tailscale Serve/Funnel 或 SSH 隧道连接，并且仍可在需要时配对设备节点（macOS/iOS/Android）以执行设备本地操作。

网关主机 默认运行 exec 工具和渠道连接。
设备节点 通过 node.invoke 运行设备本地操作（system.run、摄像头、屏幕录制、通知）。
简而言之：exec 在网关所在位置运行；设备操作在设备所在位置运行。

详情：远程访问 · 节点 · 安全

通过网关协议实现 macOS 权限

macOS 应用可运行在节点模式下，并通过网关 WebSocket（node.list / node.describe）广播其能力与权限映射。客户端随后可通过 node.invoke 执行本地操作：

system.run 运行本地命令并返回 stdout/stderr/退出码；设置 needsScreenRecording: true 以要求屏幕录制权限（否则将返回 PERMISSION_MISSING）。
system.notify 发送用户通知，若通知权限被拒绝则失败。
canvas.*、camera.*、screen.record 和 location.get 也通过 node.invoke 路由，并遵循 TCC 权限状态。

提升权限的 bash（主机权限）与 macOS TCC 是分开的：

使用 /elevated on|off 在启用并加入允许列表后，按会话切换提升访问权限。
网关通过 sessions.patch（WS 方法）持久化每会话的切换状态，同时持久化 thinkingLevel、verboseLevel、model、sendPolicy 和 groupActivation。

详情：节点 · macOS 应用 · 网关协议

代理间通信（sessions_* 工具）

使用这些工具在会话间协调工作，无需在不同聊天界面间切换。
sessions_list —— 发现活跃会话（代理）及其元数据。
sessions_history —— 获取指定会话的对话记录。
sessions_send —— 向另一个会话发送消息；可选回复 ping-pong 和公告步骤（REPLY_SKIP、ANNOUNCE_SKIP）。

详情：会话工具

技能注册表（ClawHub）

ClawHub 是一个极简的技能注册表。启用 ClawHub 后，代理可自动搜索技能并在需要时拉取新技能。

ClawHub

聊天命令

在 WhatsApp/Telegram/Slack/Google Chat/Microsoft Teams/WebChat 中发送以下命令（群组命令仅限所有者）：

/status —— 简洁会话状态（模型 + 令牌数，如有则显示成本）
/new 或 /reset —— 重置会话
/compact —— 压缩会话上下文（摘要）
/think <level> —— off|minimal|low|medium|high|xhigh（仅限 GPT-5.2 + Codex 模型）
/verbose on|off
/usage off|tokens|full —— 每次回复的用量页脚
/restart —— 重启网关（群组中仅限所有者）
/activation mention|always —— 切换群组激活模式（仅限群组）

应用（可选）

仅网关即可提供出色的体验。所有应用均为可选，用于添加额外功能。

如果您计划构建/运行配套应用，请遵循以下平台操作手册。

macOS（OpenClaw.app）（可选）

网关和健康状态的菜单栏控制。
语音唤醒 + 按键通话覆盖层。
WebChat + 调试工具。
通过 SSH 控制远程网关。

注意：macOS 权限需签名构建才能在重建后保留（参见 docs/mac/permissions.md）。

iOS 节点（可选）

通过 Bridge 配对为节点。
语音触发转发 + 画布界面。
通过 openclaw nodes … 控制。

操作手册：iOS 连接。

Android 节点（可选）

通过与 iOS 相同的 Bridge 和配对流程配对。
提供画布、摄像头和屏幕捕获命令。
操作手册：Android 连接。

代理工作区 + 技能

工作区根目录：~/.openclaw/workspace（可通过 agents.defaults.workspace 配置）。
注入的提示文件：AGENTS.md、SOUL.md、TOOLS.md。
技能：~/.openclaw/workspace/skills/<skill>/SKILL.md。

配置

最小化的 ~/.openclaw/openclaw.json（模型 + 默认值）：

{ agent: { model: "anthropic/claude-opus-4-5" } }

完整配置参考（所有键 + 示例）。

安全模型（重要）

默认：工具在主会话的主机上运行，因此当只有您自己使用时，代理拥有完全访问权限。
群组/渠道安全：设置 agents.defaults.sandbox.mode: "non-main"，使非主会话（群组/渠道）在每会话 Docker 沙箱中运行；此时 bash 在这些会话的 Docker 中运行。
沙箱默认：允许 bash、process、read、write、edit、sessions_list、sessions_history、sessions_send、sessions_spawn；禁止 browser、canvas、nodes、cron、discord、gateway。

详情：安全指南 · Docker + 沙箱 · 沙箱配置

链接设备：pnpm openclaw channels login（凭据存储在 ~/.openclaw/credentials）。
通过 channels.whatsapp.allowFrom 设置允许与助手对话的用户。
若设置了 channels.whatsapp.groups，则成为群组允许列表；包含 "*" 以允许所有群组。

设置 TELEGRAM_BOT_TOKEN 或 channels.telegram.botToken（环境变量优先）。
可选：设置 channels.telegram.groups（配合 channels.telegram.groups."*".requireMention）；设置后即为群组允许列表（包含 "*" 以允许所有群组）。也可根据需要设置 channels.telegram.allowFrom 或 channels.telegram.webhookUrl。

{ channels: { telegram: { botToken: "123456:ABCDEF" } } }

Slack

设置 SLACK_BOT_TOKEN + SLACK_APP_TOKEN（或 channels.slack.botToken + channels.slack.appToken）。

Discord

设置 DISCORD_BOT_TOKEN 或 channels.discord.token（环境变量优先）。
可选：设置 commands.native、commands.text 或 commands.useAccessGroups，以及根据需要设置 channels.discord.dm.allowFrom、channels.discord.guilds 或 channels.discord.mediaMaxMb。

{ channels: { discord: { token: "1234abcd" } } }

Signal

需要 signal-cli 和 channels.signal 配置段。

iMessage

仅限 macOS；需登录 Messages。
若设置了 channels.imessage.groups，则成为群组允许列表；包含 "*" 以允许所有群组。

Microsoft Teams

配置 Teams 应用 + Bot Framework，然后添加 msteams 配置段。
通过 msteams.allowFrom 设置允许对话的用户；通过 msteams.groupAllowFrom 或 msteams.groupPolicy: "open" 设置群组访问。

WebChat

使用网关 WebSocket；无需单独的 WebChat 端口/配置。

浏览器控制（可选）：

{ browser: { enabled: true, color: "#FF4500" } }

文档

完成初始化流程后，如需深入参考，请使用以下文档。

高级文档（发现 + 控制）

运维与故障排除

深入解析

工作区与技能

平台内部机制

邮件钩子（Gmail）

docs.openclaw.ai/gmail-pubsub

Molty

OpenClaw 专为 Molty（一只太空龙虾 AI 助手）而构建。🦞
由 Peter Steinberger 与社区共同打造。

社区

有关贡献指南、维护者信息及如何提交 PR，请参阅 CONTRIBUTING.md。
欢迎 AI/氛围编码的 PR！🤖

特别感谢 Mario Zechner 的支持以及他开发的 pi-mono。
特别感谢 Adam Doppelt 对 lobster.bot 的贡献。

感谢所有 clawtributors（爪式贡献者）：