入门指南

目标：从零开始，用最少的设置运行第一次工作聊天。 :::info 最快聊天：打开控制 UI（无需频道设置）。运行 openclaw-cn dashboard 并在浏览器中聊天，或在网关主机上打开 http://127.0.0.1:18789/。文档：仪表板 和 控制 UI。 :::

前提条件

Node 22 或更新版本 :::tip 如果不确定，请使用 node --version 检查您的 Node 版本。 :::

快速设置（CLI）

1. 安装 OpenClaw（推荐）

macOS/Linux：

curl -fsSL https://clawd.org.cn/install.sh | bash

Windows (PowerShell)：

iwr -useb https://clawd.org.cn/install.ps1 | iex

注意： 其他安装方法和要求：安装。

2. 运行引导向导

openclaw-cn onboard --install-daemon

向导配置认证、网关设置和可选频道。详情请参见 引导向导。

3. 检查网关

如果您安装了服务，它应该已经在运行：

openclaw-cn gateway status

4. 打开控制 UI

openclaw-cn dashboard

✓ 如果控制 UI 加载成功，您的网关已准备就绪。

可选检查和附加功能

在前台运行网关

适用于快速测试或故障排除。

openclaw-cn gateway --port 18789

发送测试消息

需要配置的频道。

openclaw-cn message send --target +15555550123 --message "来自 OpenClaw 的问候"

有用的环境变量

如果您将 OpenClaw 作为服务账户运行或想要自定义配置/状态位置：

OPENCLAW_HOME 设置用于内部路径解析的主目录。
OPENCLAW_STATE_DIR 覆盖状态目录。
OPENCLAW_CONFIG_PATH 覆盖配置文件路径。

完整的环境变量参考：环境变量。

深入了解

引导向导（详细信息） 完整的 CLI 向导参考和高级选项。

macOS 应用引导 macOS 应用的首次运行流程。

您将拥有

正在运行的网关
已配置的认证
控制 UI 访问权限或已连接的频道

下一步

私信安全和审批：配对
连接更多频道：频道
高级工作流和源码安装：设置

引导向导 (CLI)

引导向导是在 macOS、Linux 或 Windows（通过 WSL2；强烈推荐）上设置 OpenClaw 的推荐方式。它在一个引导流程中配置本地网关或远程网关连接，以及频道、技能和工作区默认设置。

主要入口点：

openclaw-cn onboard

最快首次聊天：打开控制 UI（无需频道设置）。运行 openclaw-cn dashboard 并在浏览器中聊天。文档：仪表板。

后续重新配置：

openclaw-cn configure

推荐：设置 Brave Search API 密钥，这样代理就可以使用 web_search （web_fetch 无需密钥即可工作）。最简单的方法：openclaw-cn configure --section web 这会存储 tools.web.search.apiKey。文档：网络工具。

快速开始 vs 高级模式

向导以快速开始（默认设置）vs高级（完全控制）开始。

快速开始保持默认设置：

本地网关（回环）
工作区默认设置（或现有工作区）
网关端口 18789
网关认证令牌（自动生成，即使是回环）
Tailscale 暴露关闭
Telegram + WhatsApp 私信默认为白名单（会提示您输入手机号码）

高级模式展示每个步骤（模式、工作区、网关、频道、守护进程、技能）。

向导的作用

本地模式（默认）引导您完成：

模型/认证（OpenAI Code (Codex) 订阅 OAuth、Anthropic API 密钥（推荐）或设置令牌（粘贴），以及 MiniMax/GLM/Moonshot/AI 网关选项）
工作区位置 + 启动文件
网关设置（端口/绑定/认证/tailscale）
提供商（Telegram、WhatsApp、Discord、Google Chat、Mattermost（插件）、Signal）
守护进程安装（LaunchAgent / systemd 用户单元）
健康检查
技能（推荐）

远程模式仅配置本地客户端连接到其他地方的网关。它不会在远程主机上安装或更改任何内容。

要添加更多独立代理（独立工作区 + 会话 + 认证），请使用：

openclaw-cn agents add <name>

提示：--json 不意味着非交互模式。脚本请使用 --non-interactive（和 --workspace）。

流程详情（本地）

现有配置检测
- 如果 ~/.openclaw/openclaw.json 存在，选择保留 / 修改 / 重置。
- 重新运行向导不会清除任何内容，除非您明确选择重置（或传递 --reset）。
- 如果配置无效或包含旧版密钥，向导会停止并要求您在继续之前运行 openclaw-cn doctor。
- 重置使用 trash（从不使用 rm）并提供范围：
  - 仅配置
  - 配置 + 凭据 + 会话
  - 完全重置（也移除工作区）
模型/认证
- Anthropic API 密钥（推荐）：如果存在则使用 ANTHROPIC_API_KEY 或提示输入密钥，然后保存供守护进程使用。
- Anthropic OAuth（Claude Code CLI）：在 macOS 上，向导检查钥匙串项目 "Claude Code-credentials"（选择 "始终允许" 以便 launchd 启动不被阻止）；在 Linux/Windows 上，如果存在则重用 ~/.claude/.credentials.json。
- Anthropic 令牌（粘贴设置令牌）：在任何机器上运行 claude setup-token，然后粘贴令牌（可以命名；空白 = 默认）。
- OpenAI Code (Codex) 订阅（Codex CLI）：如果 ~/.codex/auth.json 存在，向导可以重用它。
- OpenAI Code (Codex) 订阅（OAuth）：浏览器流程；粘贴 code#state。
  - 当模型未设置或为 openai/* 时，将 agents.defaults.model 设置为 openai-codex/gpt-5.2。
- OpenAI API 密钥：如果存在则使用 OPENAI_API_KEY 或提示输入密钥，然后保存到 ~/.openclaw/.env 以便 launchd 可以读取。
- OpenCode Zen（多模型代理）：提示输入 OPENCODE_API_KEY（或 OPENCODE_ZEN_API_KEY，在 https://opencode.ai/auth 获取）。
- API 密钥：为您存储密钥。
- Vercel AI 网关（多模型代理）：提示输入 AI_GATEWAY_API_KEY。
- 更多详情：Vercel AI 网关
- Cloudflare AI 网关：提示输入账户 ID、网关 ID 和 CLOUDFLARE_AI_GATEWAY_API_KEY。
- 更多详情：Cloudflare AI 网关
- MiniMax M2.1：配置自动写入。
- 更多详情：MiniMax
- Synthetic（Anthropic 兼容）：提示输入 SYNTHETIC_API_KEY。
- 更多详情：Synthetic
- Moonshot（Kimi K2）：配置自动写入。
- Kimi Coding：配置自动写入。
- 更多详情：Moonshot AI（Kimi + Kimi Coding）
- 跳过：尚未配置认证。
- 从检测到的选项中选择默认模型（或手动输入提供商/模型）。
- 向导运行模型检查，如果配置的模型未知或缺少认证则发出警告。

OAuth 凭据位于 ~/.openclaw/credentials/oauth.json；认证配置文件位于 ~/.openclaw/agents/\<agentId\>/agent/auth-profiles.json（API 密钥 + OAuth）。
更多详情：/concepts/oauth

工作区
- 默认 ~/.openclaw/workspace（可配置）。
- 为代理启动仪式生成所需的工作区文件。
- 完整工作区布局 + 备份指南：代理工作区
网关
- 端口、绑定、认证模式、tailscale 暴露。
- 认证建议：即使是回环也要保持令牌，这样本地 WS 客户端必须进行认证。
- 仅当您完全信任每个本地进程时才禁用认证。
- 非回环绑定仍需要认证。
频道
- WhatsApp：可选的二维码登录。
- Telegram：机器人令牌。
- Discord：机器人令牌。
- Google Chat：服务账户 JSON + webhook 受众。
- Mattermost（插件）：机器人令牌 + 基础 URL。
- Signal：可选的 signal-cli 安装 + 账户配置。
- BlueBubbles：推荐用于 iMessage；服务器 URL + 密码 + webhook。
- iMessage：旧版 imsg CLI 路径 + 数据库访问。
- 私信安全：默认为配对。第一条私信发送代码；通过 openclaw-cn pairing approve \<channel\> <code> 批准或使用白名单。
守护进程安装
- macOS：LaunchAgent
  - 需要已登录的用户会话；对于无头模式，使用自定义 LaunchDaemon（未提供）。
- Linux（和通过 WSL2 的 Windows）：systemd 用户单元
  - 向导尝试通过 loginctl enable-linger \<user\> 启用 linger，这样网关在注销后仍保持运行。
  - 可能提示输入 sudo（写入 /var/lib/systemd/linger）；首先尝试不使用 sudo。
- 运行时选择： Node（推荐；WhatsApp/Telegram 必需）。不推荐使用 Bun。
健康检查
- 启动网关（如果需要）并运行 openclaw-cn health。
- 提示：openclaw-cn status --deep 将网关健康探针添加到状态输出中（需要可访问的网关）。
技能（推荐）
- 读取可用技能并检查要求。
- 让您选择节点管理器：npm / pnpm（不推荐 bun）。
- 安装可选依赖项（某些在 macOS 上使用 Homebrew）。
完成
- 总结 + 下一步，包括用于额外功能的 iOS/Android/macOS 应用。

如果未检测到 GUI，向导会打印 SSH 端口转发指令用于控制 UI，而不是打开浏览器。
如果缺少控制 UI 资产，向导会尝试构建它们；备用方案是 pnpm ui:build（自动安装 UI 依赖项）。

远程模式

远程模式配置本地客户端连接到其他地方的网关。

您将设置：

远程网关 URL (ws://...)
如果远程网关需要认证则设置令牌（推荐）

注意事项：

不执行远程安装或守护进程更改。
如果网关仅为回环，则使用 SSH 隧道或 tailnet。
发现提示：
- macOS：Bonjour (dns-sd)
- Linux：Avahi (avahi-browse)

添加另一个代理

使用 openclaw-cn agents add \<name\> 创建具有自己工作区、会话和认证配置文件的独立代理。不带 --workspace 运行会启动向导。

它设置的内容：

agents.list[].name
agents.list[].workspace
agents.list[].agentDir

注意事项：

默认工作区遵循 ~/.openclaw/workspace-\<agentId\>。
添加 bindings 来路由入站消息（向导可以做到这一点）。
非交互标志：--model、--agent-dir、--bind、--non-interactive。

非交互模式

使用 --non-interactive 来自动化或脚本化引导过程：

openclaw-cn onboard --non-interactive \
  --mode local \
  --auth-choice apiKey \
  --anthropic-api-key "$ANTHROPIC_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback \
  --install-daemon \
  --daemon-runtime node \
  --skip-skills

添加 --json 以获得机器可读的摘要。

Gemini 示例：

openclaw-cn onboard --non-interactive \
  --mode local \
  --auth-choice gemini-api-key \
  --gemini-api-key "$GEMINI_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Z.AI 示例：

openclaw-cn onboard --non-interactive \
  --mode local \
  --auth-choice zai-api-key \
  --zai-api-key "$ZAI_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Vercel AI 网关示例：

openclaw-cn onboard --non-interactive \
  --mode local \
  --auth-choice ai-gateway-api-key \
  --ai-gateway-api-key "$AI_GATEWAY_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Cloudflare AI 网关示例：

openclaw-cn onboard --non-interactive \
  --mode local \
  --auth-choice cloudflare-ai-gateway-api-key \
  --cloudflare-ai-gateway-account-id "your-account-id" \
  --cloudflare-ai-gateway-gateway-id "your-gateway-id" \
  --cloudflare-ai-gateway-api-key "$CLOUDFLARE_AI_GATEWAY_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Moonshot 示例：

openclaw-cn onboard --non-interactive \
  --mode local \
  --auth-choice moonshot-api-key \
  --moonshot-api-key "$MOONSHOT_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Synthetic 示例：

openclaw-cn onboard --non-interactive \
  --mode local \
  --auth-choice synthetic-api-key \
  --synthetic-api-key "$SYNTHETIC_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

OpenCode Zen 示例：

openclaw-cn onboard --non-interactive \
  --mode local \
  --auth-choice opencode-zen \
  --opencode-zen-api-key "$OPENCODE_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

添加代理（非交互）示例：

openclaw-cn agents add work \
  --workspace ~/.openclaw/workspace-work \
  --model openai/gpt-5.2 \
  --bind whatsapp:biz \
  --non-interactive \
  --json

网关向导 RPC

网关通过 RPC 暴露向导流程（wizard.start、wizard.next、wizard.cancel、wizard.status）。客户端（macOS 应用、控制 UI）可以在不重新实现引导逻辑的情况下渲染步骤。

Signal 设置（signal-cli）

向导可以从 GitHub 发布版本安装 signal-cli：

下载适当的发布资产。
将其存储在 ~/.openclaw/tools/signal-cli/\<version\>/ 下。
将 channels.signal.cliPath 写入您的配置。

注意事项：

JVM 构建需要 Java 21。
可用时使用原生构建。
Windows 使用 WSL2；signal-cli 安装遵循 WSL 内的 Linux 流程。

向导写入的内容

~/.openclaw/openclaw.json 中的典型字段：

agents.defaults.workspace
agents.defaults.model / models.providers（如果选择了 Minimax）
gateway.*（模式、绑定、认证、tailscale）
channels.telegram.botToken、channels.discord.token、channels.signal.*、channels.imessage.*
频道白名单（Slack/Discord/Matrix/Microsoft Teams），当您在提示中选择加入时（名称尽可能解析为 ID）。
skills.install.nodeManager
wizard.lastRunAt
wizard.lastRunVersion
wizard.lastRunCommit
wizard.lastRunCommand
wizard.lastRunMode

openclaw-cn agents add 写入 agents.list[] 和可选的 bindings。

WhatsApp 凭据位于 ~/.openclaw/credentials/whatsapp/\<accountId\>/ 下。会话存储在 ~/.openclaw/agents/\<agentId\>/sessions/ 下。

某些频道以插件形式提供。当您在引导过程中选择其中一个时，向导会在配置之前提示安装它（npm 或本地路径）。

更新 Openclaw

本文档帮助你将 Openclaw 更新到最新版本，并在遇到问题时进行排查。

一分钟快速更新

大多数用户只需要这一个命令：

Linux / macOS：

npm i -g openclaw-cn@latest && openclaw-cn doctor && openclaw-cn gateway restart

Linux / macOS（淘宝镜像源，国内推荐）：

npm i -g openclaw-cn@latest --registry=https://registry.npmmirror.com && openclaw-cn doctor && openclaw-cn gateway restart

Windows（PowerShell）：

npm i -g openclaw-cn@latest; openclaw-cn doctor; openclaw-cn gateway restart

Windows（PowerShell，淘宝镜像源）：

npm i -g openclaw-cn@latest --registry=https://registry.npmmirror.com; openclaw-cn doctor; openclaw-cn gateway restart

WSL 用户注意：WSL 环境需要启用 systemd 才能使用 gateway restart。如果遇到 "Failed to connect to bus" 错误，请参考 WSL 启用 systemd 指南 或使用前台模式运行：

openclaw-cn gateway run

这会：更新到最新版本 → 运行诊断修复 → 重启 Gateway。

逐步更新指南

第一步：检查当前版本

openclaw-cn --version

第二步：更新 Openclaw

方法 A：使用安装脚本（推荐）

curl -fsSL https://clawd.org.cn/install.sh | bash -s -- --no-onboard

添加 --no-onboard 跳过引导向导（你已经配置过了）。

方法 B：使用 npm 直接更新

npm i -g openclaw-cn@latest

方法 C：使用淘宝镜像源更新（国内推荐）

如果 npm 官方源较慢，可以使用淘宝镜像：

npm i -g openclaw-cn@latest --registry=https://registry.npmmirror.com

或者永久设置淘宝源后再更新：

npm config set registry https://registry.npmmirror.com
npm i -g openclaw-cn@latest

方法 D：安装测试版本

如果你想测试预发布版本：

npm i -g openclaw-cn@test
# 或指定具体版本
npm i -g openclaw-cn@2026.2.2-test.0

第三步：运行诊断

更新后必须运行 doctor 命令：

openclaw-cn doctor

Doctor 会自动：

迁移旧配置到新格式
检查并修复常见问题
验证 Gateway 健康状态

第四步：重启 Gateway

openclaw-cn gateway restart

第五步：验证更新

openclaw-cn status

更新后问题排查

常用诊断命令

命令	用途
`openclaw-cn status`	查看整体状态概览
`openclaw-cn status --all`	完整诊断报告（可粘贴分享）
`openclaw-cn doctor`	自动检测并修复问题
`openclaw-cn logs --follow`	实时查看日志
`openclaw-cn channels status`	查看消息通道状态
`openclaw-cn models status`	查看 AI 模型认证状态

问题 1：Gateway 无法启动

症状：运行 openclaw-cn gateway restart 后无响应

排查步骤：

# 1. 查看 Gateway 状态
openclaw-cn gateway status
<h1 id="2. 查看详细日志">2. 查看详细日志</h1>
<p>openclaw-cn logs --follow</p>
<h1 id="3. 尝试重新安装服务">3. 尝试重新安装服务</h1>
<p>openclaw-cn gateway install
openclaw-cn gateway restart

问题 2：消息通道断开

症状：Telegram/微信/飞书等通道无法收发消息

排查步骤：

# 1. 查看通道状态
openclaw-cn channels status --probe</p>
<h1 id="2. 重启 Gateway">2. 重启 Gateway</h1>
<p>openclaw-cn gateway restart</p>
<h1 id="3. 如果问题持续，检查日志">3. 如果问题持续，检查日志</h1>
<p>openclaw-cn logs --follow

问题 3：API 认证失效

症状：提示"未找到提供者的 API 密钥"

排查步骤：

# 1. 查看当前认证状态
openclaw-cn models status</p>
<h1 id="2. 重新设置认证">2. 重新设置认证</h1>
<p>openclaw-cn models auth setup-token --provider anthropic</p>
<h1 id="或">或</h1>
<p>openclaw-cn models auth setup-token --provider openai

问题 4：配置迁移失败

症状：提示需要运行 doctor 但 doctor 报错

排查步骤：

# 1. 备份当前配置
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup</p>
<h1 id="2. 运行非交互式 doctor">2. 运行非交互式 doctor</h1>
<p>openclaw-cn doctor --non-interactive</p>
<h1 id="3. 如果仍有问题，尝试修复模式">3. 如果仍有问题，尝试修复模式</h1>
<p>openclaw-cn doctor --repair

问题 5：Web UI 显示 `disconnected (1006): no reason`

症状：更新后打开 Web 网关管理页面，显示错误 disconnected (1006): no reason

原因：浏览器缓存了旧版本的设备认证数据，与新版 Gateway 不兼容

快速解决：

清除浏览器本地存储（推荐）：
- Chrome：按 F12 → Application → Local Storage → 右键删除 clawdbot 相关条目
- 或者：Ctrl+Shift+Delete → 勾选「Cookie 和站点数据」→ 清除
使用无痕模式：在新的无痕/隐私窗口打开 Web UI
换一个浏览器：暂时使用另一个浏览器访问

详细说明见 故障排除指南

回滚到旧版本

如果新版本有问题，可以回滚到之前的版本：

# 查看可用版本
npm view openclaw-cn versions --json | tail -20</p>
<h1 id="安装指定版本（替换 2026.1.15 为你需要的版本）">安装指定版本（替换 2026.1.15 为你需要的版本）</h1>
<p>npm i -g openclaw-cn@2026.1.15</p>
<h1 id="运行 doctor 并重启">运行 doctor 并重启</h1>
<p>openclaw-cn doctor
openclaw-cn gateway restart

获取帮助

如果问题无法解决：

运行 openclaw-cn status --all 获取完整诊断报告
查看 故障排除指南
在 Discord 社区提问：https://discord.gg/KFTVvJUu

高级：更新渠道

Openclaw 有三个发布渠道：

渠道	说明	安装命令
stable	稳定版（默认）	`npm i -g openclaw-cn@latest`
beta	预发布测试版	`npm i -g openclaw-cn@beta`
test	开发测试版	`npm i -g openclaw-cn@test`

切换渠道：

openclaw-cn update --channel beta
openclaw-cn update --channel stable

高级：从源码更新

如果你是从 Git 仓库安装的：

# 方法 A：使用内置更新命令
openclaw-cn update</p>
<h1 id="方法 B：手动更新">方法 B：手动更新</h1>
<p>git pull
pnpm install
pnpm build
openclaw-cn doctor
openclaw-cn gateway restart

高级：Gateway 服务管理

查看服务状态：

openclaw-cn gateway status

启动/停止/重启：

openclaw-cn gateway start
openclaw-cn gateway stop
openclaw-cn gateway restart

安装/卸载系统服务：

openclaw-cn gateway install    # 安装为系统服务（开机自启）
openclaw-cn gateway uninstall  # 卸载系统服务

平台特定命令：

macOS：launchctl kickstart -k gui/$UID/com.openclaw.gateway
Linux：systemctl --user restart clawdbot-gateway.service

设置

最后更新：2026-01-01

概述

定制化存在于仓库之外： ~/clawd（工作区）+ ~/.openclaw/openclaw.json（配置）。
稳定工作流程： 安装 macOS 应用；让它运行捆绑的网关。
前沿工作流程： 通过 pnpm gateway:watch 自己运行网关，然后让 macOS 应用以本地模式附加。

先决条件（从源码）

Node >=22
pnpm
Docker（可选；仅用于容器化设置/e2e — 参见 Docker）

定制策略（因此更新不会造成损害）

如果您想要 "100% 适合我" 并且易于更新，请将您的自定义保存在：

配置： ~/.openclaw/openclaw.json（JSON/JSON5 类似）
工作区： ~/clawd（技能、提示、记忆；将其设为私有 git 仓库）

引导一次：

openclaw-cn setup

在此仓库内部，使用本地 CLI 入口：

openclaw-cn setup

如果您还没有全局安装，请通过 pnpm openclaw-cn setup 运行它。

稳定工作流程（先用 macOS 应用）

安装 + 启动 Clawdbot.app（菜单栏）。
完成入门/权限清单（TCC 提示）。
确保网关是本地且正在运行（应用管理它）。
链接界面（示例：WhatsApp）：

openclaw-cn channels login

健康检查：

openclaw-cn health

如果您的构建中不可用入门：

运行 openclaw-cn setup，然后 openclaw-cn channels login，然后手动启动网关（openclaw-cn gateway）。

前沿工作流程（网关在终端中）

目标：在 TypeScript 网关上工作，获得热重载，保持 macOS 应用 UI 附加。

0) （可选）也从源码运行 macOS 应用

如果您也希望 macOS 应用处于前沿：

./scripts/restart-mac.sh

1) 启动开发网关

pnpm install
pnpm gateway:watch

gateway:watch 在监视模式下运行网关并在 TypeScript 更改时重新加载。

2) 让 macOS 应用指向您正在运行的网关

在 Clawdbot.app 中：

连接模式：本地应用将附加到配置端口上正在运行的网关。

3) 验证

应用内网关状态应显示 "使用现有网关 …"
或通过 CLI：

openclaw-cn health

常见错误

错误端口： 网关 WS 默认为 ws://127.0.0.1:18789；保持应用 + CLI 在同一端口。
状态存储位置：
- 凭据：~/.openclaw/credentials/
- 会话：~/.openclaw/agents/<agentId>/sessions/
- 日志：/tmp/clawdbot/

更新（不破坏您的设置）

将 ~/clawd 和 ~/.openclaw/ 保留为 "您的内容"；不要将个人提示/配置放入 clawdbot 仓库。
更新源码：git pull + pnpm install（当锁文件更改时）+ 继续使用 pnpm gateway:watch。

Linux（systemd 用户服务）

Linux 安装使用 systemd 用户服务。默认情况下，systemd 在注销/空闲时停止用户服务，这会终止网关。入门尝试为您启用持久化（可能提示 sudo）。如果仍然关闭，请运行：

sudo loginctl enable-linger $USER

对于始终在线或多用户服务器，请考虑使用系统服务而不是用户服务（不需要持久化）。参见 网关运行手册 获取 systemd 注释。

配对

"配对" 是 Clawdbot 的显式所有者批准步骤。它在两个地方使用：

私信配对（谁被允许与机器人交谈）
节点配对（哪些设备/节点被允许加入网关网络）

安全上下文：安全

1) 私信配对（入站聊天访问）

当通道配置了私信策略 pairing 时，未知发送者会收到一个短代码，他们的消息在您批准之前不会被处理。

默认私信策略记录在：安全

配对代码：

8 个字符，大写，无歧义字符（0O1I）。
1小时后过期。机器人仅在创建新请求时发送配对消息（大约每小时每个发送者一次）。
默认情况下，待处理的私信配对请求限制为每个通道 3 个；附加请求将被忽略，直到其中一个过期或被批准。

批准发送者

openclaw-cn pairing list telegram
openclaw-cn pairing approve telegram <CODE>

支持的通道：telegram、whatsapp、signal、imessage、discord、slack。

状态存储位置

存储在 ~/.openclaw/credentials/ 下：

待处理请求：<channel>-pairing.json
已批准白名单存储：<channel>-allowFrom.json

将这些视为敏感文件（它们控制对您的助手的访问）。

2) 节点设备配对（iOS/Android/macOS/无头节点）

节点以 role: node 作为设备连接到网关。网关创建一个必须批准的设备配对请求。

批准节点设备

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

状态存储位置

存储在 ~/.openclaw/devices/ 下：

pending.json（短期存在；待处理请求会过期）
paired.json（已配对设备 + 令牌）

注意

旧版 node.pair.* API（CLI：openclaw-cn nodes pending/approve）是一个单独的网关拥有的配对存储。WS 节点仍需要设备配对。

使用 Clawdbot 构建个人助手（Clawd 风格）

Clawdbot 是一个用于 Pi 代理的 WhatsApp + Telegram + Discord + iMessage 网关。插件增加了 Mattermost 支持。本指南是 "个人助手" 设置：一个专用的 WhatsApp 号码，行为类似于您始终在线的代理。

⚠️ 安全第一

您将代理置于以下位置：

在您的机器上运行命令（取决于您的 Pi 工具设置）
读取/写入工作区中的文件
通过 WhatsApp/Telegram/Discord/Mattermost（插件）发送消息

保守开始：

始终设置 channels.whatsapp.allowFrom（永远不要在您的个人 Mac 上运行面向全世界开放的服务）。
为助手使用专用的 WhatsApp 号码。
心跳现在默认每 30 分钟一次。在信任设置之前禁用，方法是设置 agents.defaults.heartbeat.every: "0m"。

先决条件

Node 22+
Clawdbot 在 PATH 中可用（推荐：全局安装）
助手的第二个电话号码（SIM/eSIM/预付费）

npm install -g openclaw-cn@latest</p>
<h1 id="或：pnpm add -g openclaw-cn@latest</code></pre><p style="text-align: start; ; line-height: inherit"><span fontsize="" color="">从源码（开发）：</span></p><pre><code>git clone https://github.com/clawdbot/clawdbot.git">或：pnpm add -g openclaw-cn@latest

从源码（开发）：

git clone https://github.com/clawdbot/clawdbot.git</h1>
<p>cd clawdbot
pnpm install
pnpm ui:build # 首次运行时自动安装 UI 依赖
pnpm build
pnpm link --global

双手机设置（推荐）

您需要这样：

您的手机（个人）              第二部手机（助手）
┌─────────────────┐           ┌─────────────────┐
│  您的 WhatsApp  │  ──────▶  │  助手 WA        │
│  +1-555-YOU     │  消息     │  +1-555-CLAWD   │
└─────────────────┘           └────────┬────────┘
│ 通过二维码连接
▼
┌─────────────────┐
│  您的 Mac       │
│  (clawdbot)      │
│    Pi 代理      │
└─────────────────┘

如果您将个人 WhatsApp 与 Clawdbot 关联，每条发给您的消息都会变成 "代理输入"。这很少是您想要的结果。

5分钟快速开始

配对 WhatsApp Web（显示二维码；用助手手机扫描）：

openclaw-cn channels login

启动网关（保持运行）：

openclaw-cn gateway --port 18789

在 ~/.openclaw/openclaw.json 中放置最小配置：

{
channels: { whatsapp: { allowFrom: ["+15555550123"] } }
}

现在从您的白名单手机向助手号码发送消息。

入门完成后，我们会自动打开带有网关令牌的仪表板并打印令牌化链接。稍后重新打开：openclaw-cn dashboard。

给代理一个工作空间（AGENTS）

Clawd 从其工作空间目录读取操作指令和 "记忆"。

默认情况下，Clawdbot 使用 ~/clawd 作为代理工作空间，并将在设置/首次代理运行时自动创建它（以及初始的 AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md）。BOOTSTRAP.md 仅在工作空间全新时创建（删除后不应再出现）。

提示：将此文件夹视为 Clawd 的 "记忆" 并将其设为 git 仓库（理想情况下是私有的），以便备份您的 AGENTS.md + 记忆文件。如果安装了 git，全新的工作空间会自动初始化。

openclaw-cn setup

完整的工作空间布局 + 备份指南：代理工作空间 记忆工作流程：记忆

可选：使用 agents.defaults.workspace 选择不同的工作空间（支持 ~）。

{
agent: {
workspace: "~/clawd"
}
}

如果您已经从仓库部署自己的工作空间文件，您可以完全禁用引导文件创建：

{
agent: {
skipBootstrap: true
}
}

将其转变为 "助手" 的配置

Clawdbot 默认为良好的助手设置，但通常您需要调整：

SOUL.md 中的个性/指令
思考默认值（如需要）
心跳（一旦信任它）

示例：

{
logging: { level: "info" },
agent: {
model: "anthropic/claude-opus-4-5",
workspace: "~/clawd",
thinkingDefault: "high",
timeoutSeconds: 1800,
// 从 0 开始；稍后启用。
heartbeat: { every: "0m" }
},
channels: {
whatsapp: {
allowFrom: ["+15555550123"],
groups: {
"*": { requireMention: true }
}
}
},
routing: {
groupChat: {
mentionPatterns: ["@clawd", "clawd"]
}
},
session: {
scope: "per-sender",
resetTriggers: ["/new", "/reset"],
reset: {
mode: "daily",
atHour: 4,
idleMinutes: 10080
}
}
}

会话和记忆

会话文件：~/.openclaw/agents/<agentId>/sessions/{{SessionId}}.jsonl
会话元数据（令牌使用情况、最后路由等）：~/.openclaw/agents/<agentId>/sessions/sessions.json（旧版：~/.openclaw/sessions/sessions.json）
/new 或 /reset 为此聊天启动一个新会话（可通过 resetTriggers 配置）。如果单独发送，代理会回复简短问候以确认重置。
/compact [instructions] 压缩会话上下文并报告剩余的上下文预算。

心跳（主动模式）

默认情况下，Clawdbot 每 30 分钟运行一次心跳，提示为： 如果存在 HEARTBEAT.md，则阅读它（工作区上下文）。严格遵循它。不要从之前的聊天中推断或重复旧任务。如果没有需要注意的事情，回复 HEARTBEAT_OK。 设置 agents.defaults.heartbeat.every: "0m" 以禁用。

如果 HEARTBEAT.md 存在但实际上是空的（只有空白行和像 # 标题 这样的 markdown 标题），Clawdbot 会跳过心跳运行以节省 API 调用。
如果文件缺失，心跳仍会运行，模型决定做什么。
如果代理回复 HEARTBEAT_OK（可选择带短填充；参见 agents.defaults.heartbeat.ackMaxChars），Clawdbot 会抑制该心跳的出站传递。
心跳运行完整的代理回合 — 较短的间隔会消耗更多令牌。

{
agent: {
heartbeat: { every: "30m" }
}
}

媒体输入和输出

传入附件（图像/音频/文档）可以通过模板呈现给您的命令：

{{MediaPath}}（本地临时文件路径）
{{MediaUrl}}（伪 URL）
{{Transcript}}（如果启用了音频转录）

代理的传出附件：在单独一行包含 MEDIA:<path-or-url>（无空格）。例如：

这是截图。
MEDIA:/tmp/screenshot.png

Clawdbot 提取这些并随文本一起作为媒体发送。

操作清单

openclaw-cn status          # 本地状态（凭据、会话、排队事件）
openclaw-cn status --all    # 完整诊断（只读、可粘贴）
openclaw-cn status --deep   # 添加网关健康检查（Telegram + Discord）
openclaw-cn health --json   # 网关健康快照（WS）

日志位于 /tmp/clawdbot/ 下（默认：clawdbot-YYYY-MM-DD.log）。

下一步

WebChat：WebChat
网关操作：网关运行手册
Cron + 唤醒：Cron 作业
macOS 菜单栏伴侣：Clawdbot macOS 应用
iOS 节点应用：iOS 应用
Android 节点应用：Android 应用
Windows 状态：Windows (WSL2)
Linux 状态：Linux 应用
安全：安全

使用 Clawdbot 构建个人助手

入门指南

前提条件

快速设置（CLI）

1. 安装 OpenClaw（推荐）

2. 运行引导向导

3. 检查网关

4. 打开控制 UI

可选检查和附加功能

在前台运行网关

发送测试消息

有用的环境变量

深入了解

您将拥有

下一步

引导向导 (CLI)

快速开始 vs 高级模式

向导的作用

流程详情（本地）

远程模式

添加另一个代理

非交互模式

网关向导 RPC

Signal 设置（signal-cli）

向导写入的内容

相关文档

更新 Openclaw

一分钟快速更新

逐步更新指南

第一步：检查当前版本

第二步：更新 Openclaw

第三步：运行诊断

第四步：重启 Gateway

第五步：验证更新

更新后问题排查

常用诊断命令

问题 1：Gateway 无法启动

问题 2：消息通道断开

问题 3：API 认证失效

问题 4：配置迁移失败

问题 5：Web UI 显示 disconnected (1006): no reason

回滚到旧版本

获取帮助

高级：更新渠道

高级：从源码更新

高级：Gateway 服务管理

设置

概述

先决条件（从源码）

定制策略（因此更新不会造成损害）

稳定工作流程（先用 macOS 应用）

前沿工作流程（网关在终端中）

0) （可选）也从源码运行 macOS 应用

1) 启动开发网关

2) 让 macOS 应用指向您正在运行的网关

3) 验证

常见错误

更新（不破坏您的设置）

Linux（systemd 用户服务）

相关文档

配对

1) 私信配对（入站聊天访问）

批准发送者

状态存储位置

2) 节点设备配对（iOS/Android/macOS/无头节点）

批准节点设备

状态存储位置

注意

相关文档

使用 Clawdbot 构建个人助手（Clawd 风格）

⚠️ 安全第一

先决条件

双手机设置（推荐）

5分钟快速开始

给代理一个工作空间（AGENTS）

将其转变为 "助手" 的配置

会话和记忆

心跳（主动模式）

媒体输入和输出

操作清单

问题 5：Web UI 显示 `disconnected (1006): no reason`