EXFOLIATE! EXFOLIATE!

Website · Docs · Vision · DeepWiki · Getting Started · Updating · Showcase · FAQ · Wizard · Nix · Docker · Discord

---

OpenAI	Vercel	Blacksmith	Convex

使用 DMXAPI 的 npm 镜像源安装：

npm config set registry https://npm.cnb.cool/dmxapi/openclaw-cn/-/packages/
npm install -g openclaw-cn@latest

# 运行引导向导
openclaw-cn onboard --install-daemon

# 启动 Gateway
openclaw-cn gateway --port 18789 --verbose

# 发送消息
openclaw-cn message send --to +1234567890 --message "Hello from OpenClaw"

# 与助手对话
openclaw-cn agent --message "Ship checklist" --thinking high

npm update -g openclaw-cn
# 升级后运行 doctor 检查
openclaw-cn doctor

---

OpenClaw 是一个运行在你自己设备上的个人 AI 助手。

它可以在你常用的通讯渠道上回复你（WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、iMessage、Microsoft Teams、WebChat），还支持扩展渠道如 BlueBubbles、Matrix、Zalo 和 Zalo Personal。它可以在 macOS/iOS/Android 上进行语音交互，并可以渲染你控制的实时 Canvas。Gateway 只是控制平面——产品本身是助手。

如果你想要一个本地、快速、常驻的个人单用户助手，这就是它。

• Node.js: >=22.12.0
• 包管理器: npm / pnpm / bun

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

推荐设置：运行引导向导 (openclaw-cn onboard)。它会引导你完成 Gateway、工作区、渠道和技能的设置。CLI 向导是推荐路径，支持 macOS、Linux 和 Windows (通过 WSL2；强烈推荐)。

---

订阅（OAuth）：

• OpenAI (ChatGPT/Codex)

模型说明：虽然支持任何模型，但强烈推荐 Anthropic Pro/Max (100/200) + Opus 4.5，因为其长上下文能力强，且对提示注入攻击有更好的抵抗力。参见 引导向导。

• 模型配置 + CLI: 模型
• 认证配置轮换（OAuth vs API 密钥）+ 回退: 模型故障转移

---

• 本地优先 Gateway — 会话、渠道、工具和事件的单一控制平面
• 多渠道收件箱 — WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、BlueBubbles (iMessage)、iMessage (传统)、Microsoft Teams、Matrix、Zalo、Zalo Personal、WebChat、macOS、iOS/Android
• 多代理路由 — 将入站渠道/账户/对等方路由到隔离的代理（工作区 + 每代理会话）
• 语音唤醒 + 对话模式 — macOS/iOS/Android 上使用 ElevenLabs 的常驻语音
• 实时 Canvas — 代理驱动的可视化工作区，支持 A2UI
• 一流的工具 — 浏览器、canvas、节点、定时任务、会话以及 Discord/Slack 操作
• 配套应用 — macOS 菜单栏应用 + iOS/Android 节点
• 引导向导 + 技能 — 向导驱动的设置，包含内置/托管/工作区技能

---

• stable: 标签发布 (vYYYY.M.D 或 vYYYY.M.D-<patch>)，npm dist-tag latest
• beta: 预发布标签 (vYYYY.M.D-beta.N)，npm dist-tag beta（macOS 应用可能缺失）
• dev: main 分支的移动头，npm dist-tag dev（如已发布）

切换渠道 (git + npm): openclaw-cn update --channel stable|beta|dev 详情: 开发渠道

---

推荐使用 pnpm 从源码构建。Bun 是可选的，用于直接运行 TypeScript。

openclaw onboard --install-daemon

openclaw gateway --port 18789 --verbose

# Send a message
openclaw message send --to +1234567890 --message "Hello from OpenClaw"

# Talk to the assistant (optionally deliver back to any connected channel: 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/WebChat)
openclaw agent --message "Ship checklist" --thinking high

Upgrading? Updating guide (and run openclaw doctor).

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 ... 直接运行 TypeScript（通过 tsx）。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-cn pairing approve <channel> <code>（然后发送者会被添加到本地白名单存储）
• 公开入站私信需要明确选择加入: 设置 dmPolicy="open" 并在渠道白名单中包含 "*"

运行 openclaw-cn doctor 以发现有风险/配置错误的私信策略。

---

• Gateway WS control plane with sessions, presence, config, cron, webhooks, Control UI, and Canvas host.
• CLI surface: gateway, agent, send, wizard, and doctor.
• Pi agent runtime in RPC mode with tool streaming and block streaming.
• Session model: main for direct chats, group isolation, activation modes, queue modes, reply-back. Group rules: Groups.
• Media pipeline: images/audio/video, transcription hooks, size caps, temp file lifecycle. Audio details: Audio.

• Channels: WhatsApp (Baileys), Telegram (grammY), Slack (Bolt), Discord (discord.js), Google Chat (Chat API), Signal (signal-cli), BlueBubbles (iMessage, recommended), iMessage (legacy imsg), IRC, Microsoft Teams, Matrix, Feishu, LINE, Mattermost, Nextcloud Talk, Nostr, Synology Chat, Tlon, Twitch, Zalo, Zalo Personal, WebChat.
• Group routing: mention gating, reply tags, per-channel chunking and routing. Channel rules: Channels.

• macOS app: menu bar control plane, Voice Wake/PTT, Talk Mode overlay, WebChat, debug tools, remote gateway control.
• iOS node: Canvas, Voice Wake, Talk Mode, camera, screen recording, Bonjour + device pairing.
• Android node: Connect tab (setup code/manual), chat sessions, voice tab, Canvas, camera/screen recording, and Android device commands (notifications/location/SMS/photos/contacts/calendar/motion/app update).
• macOS node mode: system.run/notify + canvas/camera exposure.

• Browser control: dedicated openclaw Chrome/Chromium, snapshots, actions, uploads, profiles.
• Canvas: A2UI push/reset, eval, snapshot.
• Nodes: camera snap/clip, screen record, location.get, notifications.
• Cron + wakeups; webhooks; Gmail Pub/Sub.
• Skills platform: bundled, managed, and workspace skills with install gating + UI.

• Channel routing, retry policy, and streaming/chunking.
• Presence, typing indicators, and usage tracking.
• Models, model failover, and session pruning.
• Security and troubleshooting.

• Control UI + WebChat served directly from the Gateway.
• Tailscale Serve/Funnel or SSH tunnels with token/password auth.
• Nix mode for declarative config; Docker-based installs.
• Doctor migrations, logging.

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 / WebChat
               │
               ▼
┌───────────────────────────────┐
│            Gateway            │
│       (control plane)         │
│     ws://127.0.0.1:18789      │
└──────────────┬────────────────┘
               │
               ├─ Pi agent (RPC)
               ├─ CLI (openclaw …)
               ├─ WebChat UI
               ├─ macOS app
               └─ iOS / Android nodes

• Gateway WebSocket network — single WS control plane for clients, tools, and events (plus ops: Gateway runbook).
• Tailscale exposure — Serve/Funnel for the Gateway dashboard + WS (remote access: Remote).
• Browser control — openclaw‑managed Chrome/Chromium with CDP control.
• Canvas + A2UI — agent‑driven visual workspace (A2UI host: Canvas/A2UI).
• Voice Wake + Talk Mode — wake words on macOS/iOS plus continuous voice on Android.
• Nodes — Canvas, camera snap/clip, screen record, location.get, notifications, plus macOS‑only system.run/system.notify.

OpenClaw can auto-configure Tailscale Serve (tailnet-only) or Funnel (public) while the Gateway stays bound to loopback. Configure gateway.tailscale.mode:

• off: no Tailscale automation (default).
• serve: tailnet-only HTTPS via tailscale serve (uses Tailscale identity headers by default).
• funnel: public HTTPS via tailscale funnel (requires shared password auth).

Notes:

• gateway.bind must stay loopback when Serve/Funnel is enabled (OpenClaw enforces this).
• Serve can be forced to require a password by setting gateway.auth.mode: "password" or gateway.auth.allowTailscale: false.
• Funnel refuses to start unless gateway.auth.mode: "password" is set.
• Optional: gateway.tailscale.resetOnExit to undo Serve/Funnel on shutdown.

Details: Tailscale guide · Web surfaces

It’s perfectly fine to run the Gateway on a small Linux instance. Clients (macOS app, CLI, WebChat) can connect over Tailscale Serve/Funnel or SSH tunnels, and you can still pair device nodes (macOS/iOS/Android) to execute device‑local actions when needed.

• Gateway host runs the exec tool and channel connections by default.
• Device nodes run device‑local actions (system.run, camera, screen recording, notifications) via node.invoke. In short: exec runs where the Gateway lives; device actions run where the device lives.

Details: Remote access · Nodes · Security

The macOS app can run in node mode and advertises its capabilities + permission map over the Gateway WebSocket (node.list / node.describe). Clients can then execute local actions via node.invoke:

• system.run runs a local command and returns stdout/stderr/exit code; set needsScreenRecording: true to require screen-recording permission (otherwise you’ll get PERMISSION_MISSING).
• system.notify posts a user notification and fails if notifications are denied.
• canvas.*, camera.*, screen.record, and location.get are also routed via node.invoke and follow TCC permission status.

Elevated bash (host permissions) is separate from macOS TCC:

• Use /elevated on|off to toggle per‑session elevated access when enabled + allowlisted.
• Gateway persists the per‑session toggle via sessions.patch (WS method) alongside thinkingLevel, verboseLevel, model, sendPolicy, and groupActivation.

Details: Nodes · macOS app · Gateway protocol

• Use these to coordinate work across sessions without jumping between chat surfaces.
• sessions_list — discover active sessions (agents) and their metadata.
• sessions_history — fetch transcript logs for a session.
• sessions_send — message another session; optional reply‑back ping‑pong + announce step (REPLY_SKIP, ANNOUNCE_SKIP).

Details: Session tools

ClawHub is a minimal skill registry. With ClawHub enabled, the agent can search for skills automatically and pull in new ones as needed.

ClawHub

Send these in WhatsApp/Telegram/Slack/Google Chat/Microsoft Teams/WebChat (group commands are owner-only):

• /status — compact session status (model + tokens, cost when available)
• /new or /reset — reset the session
• /compact — compact session context (summary)
• /think <level> — off|minimal|low|medium|high|xhigh (GPT-5.2 + Codex models only)
• /verbose on|off
• /usage off|tokens|full — per-response usage footer
• /restart — restart the gateway (owner-only in groups)
• /activation mention|always — group activation toggle (groups only)

The Gateway alone delivers a great experience. All apps are optional and add extra features.

If you plan to build/run companion apps, follow the platform runbooks below.

• Menu bar control for the Gateway and health.
• Voice Wake + push-to-talk overlay.
• WebChat + debug tools.
• Remote gateway control over SSH.

Note: signed builds required for macOS permissions to stick across rebuilds (see docs/mac/permissions.md).

• Pairs as a node over the Gateway WebSocket (device pairing).
• Voice trigger forwarding + Canvas surface.
• Controlled via openclaw nodes ….

Runbook: iOS connect.

• Pairs as a WS node via device pairing (openclaw devices ...).
• Exposes Connect/Chat/Voice tabs plus Canvas, Camera, Screen capture, and Android device command families.
• Runbook: Android connect.

• Workspace root: ~/.openclaw/workspace (configurable via agents.defaults.workspace).
• Injected prompt files: AGENTS.md, SOUL.md, TOOLS.md.
• Skills: ~/.openclaw/workspace/skills/<skill>/SKILL.md.

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

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

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

---

• 默认: 工具在主机上为 main 会话运行，因此当只有你使用时，代理具有完全访问权限
• 群组/渠道安全: 设置 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: {
      botToken: "123456:ABCDEF",
    },
  },
}

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

• 设置 DISCORD_BOT_TOKEN 或 channels.discord.token（环境变量优先）

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

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

• 推荐 的 iMessage 集成
• 配置 channels.bluebubbles.serverUrl + channels.bluebubbles.password 和 webhook (channels.bluebubbles.webhookPath)
• BlueBubbles 服务器在 macOS 上运行；Gateway 可以在 macOS 或其他地方运行

• 传统的仅限 macOS 集成，通过 imsg（Messages 必须已登录）
• 如果设置了 channels.imessage.groups，它将成为群组白名单

• 配置 Teams 应用 + Bot Framework，然后添加 msteams 配置部分

• 使用 Gateway WebSocket；无需单独的 WebChat 端口/配置

---

在 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 — 重启 Gateway（群组中仅限所有者）
• /activation mention|always — 群组激活切换（仅限群组）

---

Gateway 本身就能提供出色的体验。所有应用都是可选的，用于添加额外功能。

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

注意: 需要签名构建才能使 macOS 权限在重新构建后保持

• 通过 Bridge 配对为节点
• 语音触发转发 + Canvas 界面
• 通过 openclaw-cn nodes … 控制

运行手册: iOS 连接

• 通过与 iOS 相同的 Bridge + 配对流程配对
• 暴露 Canvas、相机和屏幕捕获命令

运行手册: Android 连接

---

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-cn …)
               ├─ WebChat UI
               ├─ macOS 应用
               └─ iOS / Android 节点

---

• Gateway WebSocket 网络 — 客户端、工具和事件的单一 WS 控制平面
• Tailscale 暴露 — Gateway 仪表板 + WS 的 Serve/Funnel
• 浏览器控制 — openclaw 管理的 Chrome/Chromium，支持 CDP 控制
• Canvas + A2UI — 代理驱动的可视化工作区
• 语音唤醒 + 对话模式 — 常驻语音和连续对话
• 节点 — Canvas、相机拍照/录制、屏幕录制、location.get、通知

---

OpenClaw 可以自动配置 Tailscale Serve（仅限 tailnet）或 Funnel（公开），同时 Gateway 保持绑定到回环。配置 gateway.tailscale.mode：

• off: 无 Tailscale 自动化（默认）
• serve: 通过 tailscale serve 的仅限 tailnet HTTPS（默认使用 Tailscale 身份头）
• funnel: 通过 tailscale funnel 的公开 HTTPS（需要共享密码认证）

详情: Tailscale 指南 · Web 界面

---

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

• Gateway 主机 默认运行 exec 工具和渠道连接
• 设备节点 通过 node.invoke 运行设备本地操作（system.run、相机、屏幕录制、通知）

简而言之：exec 在 Gateway 所在位置运行；设备操作在设备所在位置运行。

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

---

• 使用这些工具来协调跨会话的工作，无需在聊天界面之间切换
• sessions_list — 发现活动会话（代理）及其元数据
• sessions_history — 获取会话的对话日志
• sessions_send — 向另一个会话发送消息；可选的回复回环 + 宣告步骤

详情: 会话工具

---

ClawHub 是一个最小的技能注册表。启用 ClawHub 后，代理可以自动搜索技能并根据需要引入新技能。

ClawHub

---

• 从文档索引开始导航和了解"什么在哪里"
• 阅读架构概述了解 Gateway + 协议模型
• 需要每个键和示例时使用完整配置参考
• 按照运维手册运行 Gateway
• 了解控制 UI/Web 界面如何工作以及如何安全暴露它们
• 了解通过 SSH 隧道或 tailnet 的远程访问
• 按照引导向导流程进行引导设置
• 通过 webhook 界面连接外部触发器
• 设置 Gmail Pub/Sub 触发器
• 了解 macOS 菜单栏配套应用详情
• 平台指南: Windows (WSL2)、Linux、macOS、iOS、Android
• 使用故障排除指南调试常见故障
• 在暴露任何内容之前查看安全指南

• 发现 + 传输
• Bonjour/mDNS
• Gateway 配对
• 控制 UI
• 仪表板

• 健康检查
• Gateway 锁
• 后台进程
• 浏览器故障排除 (Linux)
• 日志

• 代理循环
• 在线状态
• TypeBox 模式
• RPC 适配器
• 队列

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

---

OpenClaw 是为 Molty 构建的，一个太空龙虾 AI 助手。 由 Peter Steinberger 和社区开发。

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

---

参见 CONTRIBUTING.md 了解指南、维护者和如何提交 PR。 欢迎 AI/vibe-coded PR!

特别感谢 Mario Zechner 的支持以及 pi-mono。 特别感谢 Adam Doppelt 的 lobster.bot。

---