🦞 OpenClaw — 个人AI助手

去角质！去角质！

OpenClaw 是一款在您自己的设备上运行的_个人AI助手_。 它会通过您常用的渠道（WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、iMessage、BlueBubbles、IRC、Microsoft Teams、Matrix、飞书、LINE、Mattermost、Nextcloud Talk、Nostr、Synology Chat、Tlon、Twitch、Zalo、Zalo Personal、微信、WebChat）回复您的消息。它可以在macOS/iOS/Android上进行语音交互，并能渲染由您控制的实时Canvas画布。Gateway只是控制平面——真正的核心是助手本身。

如果您想要一个本地化、快速响应且始终在线的个人单用户助手，那么这就是它。

官网 · 文档 · 愿景 · DeepWiki · 入门指南 · 更新指南 · 案例展示 · 常见问题解答 · 引导设置 · Nix · Docker · Discord

推荐安装方式：在终端中运行 openclaw onboard。 OpenClaw Onboard会逐步引导您完成网关、工作空间、频道和技能的设置。这是推荐的CLI安装路径，适用于macOS、Linux以及Windows（通过WSL2；强烈推荐）。 支持npm、pnpm或bun。 新用户？请从这里开始：入门指南

赞助商

订阅服务（OAuth）：

• OpenAI（ChatGPT/Codex）

模型提示：虽然支持多种提供商和模型，但为了获得最佳体验并降低提示注入风险，请使用您可用的最强大、最新一代模型。详情请参阅引导设置。

模型（选择与认证）

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

安装（推荐）

运行环境：Node 24（推荐）或Node 22.16及以上版本。

npm install -g openclaw@latest
# 或：pnpm add -g openclaw@latest

openclaw onboard --install-daemon

OpenClaw Onboard会安装Gateway守护进程（launchd/systemd用户服务），以确保其持续运行。

快速入门（简版）

运行环境：Node 24（推荐）或Node 22.16及以上版本。

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

openclaw onboard --install-daemon

openclaw gateway --port 18789 --verbose

# 发送一条消息
openclaw message send --to +1234567890 --message "来自OpenClaw的问候"

# 与助手对话（可选择返回至任何已连接的渠道：WhatsApp/Telegram/Slack/Discord/Google Chat/Signal/iMessage/BlueBubbles/IRC/Microsoft Teams/Matrix/Feishu/LINE/Mattermost/Nextcloud Talk/Nostr/Synology Chat/Tlon/Twitch/Zalo/Zalo Personal/WeChat/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

pnpm install
pnpm ui:build # 首次运行时会自动安装 UI 依赖
pnpm build

pnpm openclaw onboard --install-daemon

# 开发循环（源码/配置变更时自动重载）
pnpm gateway:watch

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

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

OpenClaw 可以连接到真实的通讯平台。请将收到的私信视为 不受信任的输入。

完整安全指南：安全

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

• 私信配对（dmPolicy="pairing" / channels.discord.dmPolicy="pairing" / channels.slack.dmPolicy="pairing"；旧版：channels.discord.dm.policy、channels.slack.dm.policy）：未知发送者会收到一个简短的配对码，机器人不会处理他们的消息。
• 批准方式：openclaw pairing approve <channel> <code>（随后该发送者会被加入本地白名单）。
• 公开的入站私信需要明确的同意：将 dmPolicy="open" 设置，并在频道白名单中包含 "*"（allowFrom / channels.discord.allowFrom / channels.slack.allowFrom；旧版：channels.discord.dm.allowFrom、channels.slack.dm.allowFrom）。

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

亮点

• 本地优先网关 — 统一的控制平面，用于管理会话、频道、工具和事件。
• 多渠道收件箱 — WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、BlueBubbles（iMessage）、iMessage（旧版）、IRC、Microsoft Teams、Matrix、Feishu、LINE、Mattermost、Nextcloud Talk、Nostr、Synology Chat、Tlon、Twitch、Zalo、Zalo Personal、WeChat、WebChat、macOS、iOS/Android。
• 多代理路由 — 将入站频道/账号/对等方路由到隔离的代理（工作区 + 每个代理的会话）。
• 语音唤醒 + 对话模式 — macOS/iOS 上的唤醒词功能，以及 Android 上的连续语音功能（ElevenLabs + 系统 TTS 备用）。
• 实时画布 — 由代理驱动的可视化工作空间，配备 A2UI。
• 一流工具 — 浏览器、画布、节点、计划任务、会话，以及 Discord/Slack 操作。
• 配套应用 — macOS 菜单栏应用 + iOS/Android 的 节点。
• 引导流程 + 技能 — 基于引导流程的设置，包含捆绑式/托管式的工作区技能。

星标历史

我们迄今为止构建的一切

核心平台

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

频道

• 频道：WhatsApp（Baileys）、Telegram（grammY）、Slack（Bolt）、Discord（discord.js）、Google Chat（Chat API）、Signal（signal-cli）、BlueBubbles（iMessage，推荐）、iMessage（旧版 imsg）、IRC、Microsoft Teams、Matrix、Feishu、LINE、Mattermost、Nextcloud Talk、Nostr、Synology Chat、Tlon、Twitch、Zalo、Zalo Personal、WeChat（@tencent-weixin/openclaw-weixin）、WebChat。
• 群组消息路由：提及过滤、回复标签、按频道分块及路由。频道规则：频道。

应用程序 + 节点

• macOS 应用程序：菜单栏控制平面、语音唤醒/PTT、通话模式叠加层、WebChat、调试工具、远程网关控制。
• iOS 节点：画布、语音唤醒、通话模式、摄像头、屏幕录制、Bonjour + 设备配对。
• Android 节点：连接选项卡（设置代码/手动）、聊天会话、语音选项卡、画布、摄像头/屏幕录制，以及 Android 设备命令（通知/位置/SMS/照片/联系人/日历/运动/应用更新）。
• macOS 节点模式：system.run/notify + 画布/摄像头曝光。

工具 + 自动化

• 浏览器控制：专用 openclaw Chrome/Chromium 浏览器、截图、操作、上传、配置文件。
• 画布：A2UI 推送/重置、评估、截图。
• 节点：摄像头快照/剪辑、屏幕录制、location.get、通知。
• Cron + 唤醒；webhooks；Gmail Pub/Sub。
• 技能平台：捆绑式、托管式及工作区技能，带有安装权限控制 + UI。

运行时 + 安全性

• 通道路由、重试策略和流式传输/分块。
• 在线状态、打字指示器和使用情况跟踪。
• 模型、模型故障转移和会话修剪。
• 安全性和故障排除。

运维 + 打包

• 控制 UI + WebChat 直接由网关提供服务。
• Tailscale Serve/Funnel 或 SSH 隧道 结合令牌/密码认证。
• Nix 模式 用于声明式配置；基于 Docker 的安装。
• Doctor 迁移、日志记录。

工作原理（简要）

WhatsApp / Telegram / Slack / Discord / Google Chat / Signal / iMessage / BlueBubbles / IRC / Microsoft Teams / Matrix / Feishu / LINE / Mattermost / Nextcloud Talk / Nostr / Synology Chat / Tlon / Twitch / Zalo / Zalo Personal / WeChat / WebChat
               │
               ▼
┌───────────────────────────────┐
│            网关             │
│       (控制平面)          │
│     ws://127.0.0.1:18789      │
└──────────────┬────────────────┘
               │
               ├─ Pi 代理 (RPC)
               ├─ CLI (openclaw …)
               ├─ WebChat UI
               ├─ macOS 应用程序
               └─ iOS / Android 节点

关键子系统

• 网关 WebSocket 网络 — 单一 WS 控制平面，用于客户端、工具和事件（以及运维：网关运行手册）。
• Tailscale 暴露 — Serve/Funnel 用于网关仪表板 + WS（远程访问：Remote）。
• 浏览器控制 — openclaw 管理的 Chrome/Chromium 浏览器，支持 CDP 控制。
• 画布 + A2UI — 代理驱动的可视化工作空间（A2UI 主机：Canvas/A2UI）。
• 语音唤醒 + 通话模式 — macOS/iOS 上的唤醒词，以及 Android 上的持续语音功能。
• 节点 — 画布、摄像头快照/剪辑、屏幕录制、location.get、通知，以及仅限 macOS 的 system.run/system.notify。

Tailscale 访问（网关仪表板）

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

• off：无 Tailscale 自动化（默认）。
• serve：通过 tailscale serve 提供尾网专用 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），以便在需要时执行设备本地操作。

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

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

macOS 权限通过 Gateway 协议

macOS 应用可以以 节点模式 运行，并通过 Gateway WebSocket（node.list / node.describe）发布其功能和权限映射。客户端随后可以通过 node.invoke 执行本地操作：

• system.run 用于运行本地命令并返回标准输出、标准错误和退出码；设置 needsScreenRecording: true 可要求屏幕录制权限（否则会收到 PERMISSION_MISSING 错误）。
• system.notify 用于发送用户通知，如果通知权限被拒绝则会失败。
• canvas.*、camera.*、screen.record 和 location.get 也通过 node.invoke 路由，并遵循 TCC 权限状态。

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

• 使用 /elevated on|off 可在启用且被列入白名单时切换会话级别的提升权限。
• Gateway 会通过 sessions.patch（WS 方法）持久化会话级别的切换，同时还会更新 thinkingLevel、verboseLevel、model、sendPolicy 和 groupActivation。

详情：节点 · macOS 应用 · Gateway 协议

代理间通信（sessions_* 工具）

• 可用于在不同会话之间协调工作，而无需在不同的聊天界面间切换。
• sessions_list — 发现活跃的会话（代理）及其元数据。
• sessions_history — 获取某个会话的对话记录。
• sessions_send — 向另一个会话发送消息；可选地进行回复往返 + 宣告步骤（REPLY_SKIP、ANNOUNCE_SKIP）。

详情：会话工具

技能注册中心（ClawHub）

ClawHub 是一个极简的技能注册中心。启用 ClawHub 后，代理可以自动搜索技能，并在需要时引入新的技能。

ClawHub

聊天命令

可在 WhatsApp/Telegram/Slack/Google Chat/Microsoft Teams/WebChat 中发送这些命令（群组命令仅限管理员使用）：

• /status — 简要显示会话状态（模型 + token 数量，可用时显示费用）
• /new 或 /reset — 重置会话
• /compact — 简化会话上下文（摘要）
• /think <level> — 关闭|minimal|低|中|高|x高（仅适用于 GPT-5.2 和 Codex 模型）
• /verbose on|off
• /usage off|tokens|full — 显示每条响应的用量信息
• /restart — 重启网关（仅限群组管理员）
• /activation mention|always — 切换群组激活模式（仅限群组）

应用程序（可选）

仅凭 Gateway 本身就能提供出色的体验。所有应用程序均为可选，旨在增加额外功能。

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

macOS（OpenClaw.app）（可选）

• 用于控制 Gateway 和健康状态的菜单栏。
• 语音唤醒 + 按键对讲叠加层。
• WebChat + 调试工具。
• 通过 SSH 远程控制网关。

注意：为确保 macOS 权限在重新构建后仍能保持，必须使用签名版本（参见 macOS 权限）。

iOS 节点（可选）

• 通过 Gateway WebSocket 作为节点配对（设备配对）。
• 语音触发转发 + Canvas 表面。
• 通过 openclaw nodes … 进行控制。

运行手册：iOS 连接。

Android 节点（可选）

• 通过设备配对作为 WS 节点连接（openclaw devices ...）。
• 提供 Connect/Chat/Voice 标签页，以及 Canvas、Camera、屏幕截图和 Android 设备命令系列。
• 运行手册：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-6",
  },
}

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

安全模型（重要）

• 默认情况： 工具会在主会话的主机上运行，因此当只有您一人时，代理拥有完全访问权限。
• 群组/频道安全： 将 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 + 沙盒技术 · 沙盒配置

WhatsApp

• 链接设备：pnpm openclaw channels login（凭据存储在 ~/.openclaw/credentials 中）。
• 通过 channels.whatsapp.allowFrom 设置允许与助手对话的人员名单。
• 如果设置了 channels.whatsapp.groups，则会成为群组白名单；包含 "*" 可允许所有人加入。

Telegram

• 设置 TELEGRAM_BOT_TOKEN 或 channels.telegram.botToken（环境变量优先）。
• 可选：设置 channels.telegram.groups（配合 channels.telegram.groups."*".requireMention）；若设置，则为群组白名单（包含 "*" 可允许所有成员加入）。此外，根据需要还可设置 channels.telegram.allowFrom、channels.telegram.webhookUrl 和 channels.telegram.webhookSecret。

{
  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.allowFrom、channels.discord.guilds 或 channels.discord.mediaMaxMb 等参数。

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

Signal

• 需要 signal-cli 和一个 channels.signal 配置部分。

BlueBubbles (iMessage)

• 推荐的 iMessage 集成。
• 配置 channels.bluebubbles.serverUrl + channels.bluebubbles.password，以及一个 webhook（channels.bluebubbles.webhookPath）。
• BlueBubbles 服务器运行在 macOS 上；Gateway 可以在 macOS 或其他地方运行。

iMessage（旧版）

• 仅限 macOS 的旧版集成，通过 imsg 实现（需登录 Messages 应用）。
• 如果设置了 channels.imessage.groups，即为群组白名单；包含 "*" 可允许所有成员加入。

Microsoft Teams

• 配置一个 Teams 应用程序和 Bot Framework，然后添加 msteams 配置部分。
• 通过 msteams.allowFrom 允许特定用户发言；通过 msteams.groupAllowFrom 或 msteams.groupPolicy: "open" 来控制群组访问权限。

微信

• 官方腾讯插件通过 @tencent-weixin/openclaw-weixin（iLink Bot API）实现。仅支持私聊；v2.x 版本需要 OpenClaw >=2026.3.22。
• 安装命令：openclaw plugins install "@tencent-weixin/openclaw-weixin"，然后运行 openclaw channels login --channel openclaw-weixin 扫描二维码。
• 需要微信 ClawBot 插件（微信 > 我 > 设置 > 插件）；由腾讯逐步推广。

WebChat

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

浏览器控制（可选）：

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

文档

在完成入门流程后，若需更深入的参考信息，请使用以下文档。

• 从文档索引开始，了解导航和内容分布。
• 阅读架构概述，了解网关与协议模型。
• 查阅完整的配置参考，获取所有配置项及示例。
• 按照操作手册规范运行网关。
• 了解控制 UI/Web 的工作原理以及如何安全地对外暴露。
• 理解通过 SSH 隧道或尾网进行远程访问的机制。
• 遵循 OpenClaw 入门指南进行引导式设置。
• 通过 Webhook 接口接入外部触发源。
• 设置 Gmail Pub/Sub 触发器。
• 了解 macOS 菜单栏伴侣应用的详细信息。
• 平台指南：Windows (WSL2)，Linux，macOS，iOS，Android
• 通过故障排除指南诊断常见问题。
• 在对外暴露任何服务之前，请先查看安全指导。

高级文档（发现与控制）

• 发现与传输协议
• Bonjour/mDNS
• 网关配对
• 远程网关 README
• 控制 UI
• 仪表板

运维与故障排除

• 健康检查
• 网关锁
• 后台进程
• 浏览器故障排除（Linux）
• 日志记录

深度解析

• 智能体循环
• 存在感
• TypeBox 模式
• RPC 适配器
• 队列

工作空间与技能

• 技能配置
• 默认 AGENTS
• 模板：AGENTS
• 模板：BOOTSTRAP
• 模板：IDENTITY
• 模板：SOUL
• 模板：TOOLS
• 模板：USER

平台内部细节

• macOS 开发环境搭建
• macOS 菜单栏
• macOS 语音唤醒
• iOS 节点
• Android 节点
• Windows (WSL2)
• Linux 应用

邮件钩子（Gmail）

• docs.openclaw.ai/gmail-pubsub

Molty

OpenClaw 是为 Molty——一只太空龙虾 AI 助手——打造的。🦞 由 Peter Steinberger 和社区共同开发。

• openclaw.ai
• soul.md
• steipete.me
• @openclaw

社区

请参阅 CONTRIBUTING.md，了解贡献指南、维护人员信息以及如何提交 PR。欢迎任何形式的 AI 或充满创意的 PR！🤖

特别感谢 Mario Zechner 的支持，以及 pi-mono。 同时感谢 Adam Doppelt 对 lobster.bot 的贡献。

感谢所有 clawtributors：

OpenClaw 快速上手指南

OpenClaw 是一款可私有化部署的个人 AI 助手，支持在本地设备运行，并无缝集成微信、钉钉、飞书、Telegram、Discord 等主流通讯工具。它提供语音交互、实时画布（Canvas）及多智能体路由功能，打造“本地优先”的智能化体验。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：
  • macOS / Linux（推荐）
  • Windows：需通过 WSL2 (Windows Subsystem for Linux) 运行，强烈建议使用此方式以获得最佳兼容性。
• 运行时环境：
  • Node.js：推荐版本 Node 24，最低要求 Node 22.16+。
• 包管理器（任选其一）：
  • npm (默认)
  • pnpm (推荐用于源码构建)
  • bun

国内开发者提示：如果下载依赖较慢，建议配置国内镜像源（如淘宝镜像）：

npm config set registry https://registry.npmmirror.com
# 或 pnpm
pnpm config set registry https://registry.npmmirror.com

安装步骤

推荐使用官方提供的 onboard 向导进行一键式安装和配置，它将自动引导您完成网关、工作区、渠道和技能设置。

1. 全局安装

使用 npm 或 pnpm 安装最新版的 OpenClaw：

npm install -g openclaw@latest
# 或者使用 pnpm
pnpm add -g openclaw@latest

2. 初始化与守护进程安装

运行 onboard 命令并安装后台守护进程（使其作为系统服务持续运行）：

openclaw onboard --install-daemon

该命令会自动检测环境、引导登录认证模型（如 OpenAI）、配置通讯渠道，并在 macOS (launchd) 或 Linux (systemd) 上注册开机自启服务。

基本使用

安装完成后，您可以通过 CLI 直接与助手交互，或向其发送消息到已连接的渠道。

1. 启动网关（可选）

如果您未使用 --install-daemon 或需要查看实时日志，可手动启动网关：

openclaw gateway --port 18789 --verbose

2. 发送消息到通讯渠道

向指定的手机号或用户 ID 发送消息（需先配置好对应渠道，如 WhatsApp/Telegram 等）：

openclaw message send --to +1234567890 --message "Hello from OpenClaw"

3. 与 AI 助手对话

直接调用 Agent 进行处理，支持设定思考深度，并可配置将结果回传至任意已连接的渠道：

openclaw agent --message "Ship checklist" --thinking high

4. 安全配对（重要）

出于安全考虑，OpenClaw 默认对陌生用户的私信（DM）采取“配对验证”模式。当收到未知用户消息时，需使用以下命令批准访问：

openclaw pairing approve <channel> <code>

• <channel>: 渠道名称（如 discord, telegram）
• <code>: 用户收到的配对码

---

更多高级功能（如语音唤醒、Live Canvas 画布、多智能体路由）请参考官方文档：https://docs.openclaw.ai