OpenClaw 个人 AI 助手安装部署指南

OpenClaw — 个人 AI 助手

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

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

模型（选择 + 认证）

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

安装（推荐方式）

运行环境：Node ≥22。

npm install -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）。

从源码构建（开发用途）

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

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm 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 │ ▼ ┌───────────────────────────────┐ │ 网关 (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" } }

文档

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