OpenClaw 个人助手搭建指南:从 WhatsApp 网关到常驻智能体的完整配置实战
OpenClaw 个人助手搭建指南:从 WhatsApp 网关到常驻智能体的完整配置实战
OpenClaw 是一款将 Pi 智能体桥接到 WhatsApp、Telegram、Discord 与 iMessage 等即时通讯渠道的 Gateway 网关(插件还可扩展 Mattermost)。本文以「个人助手设置」为场景,完整讲解如何用一部专用手机号码,把 OpenClaw 变成你的常驻智能体:从安全边界、双手机架构、5 分钟快速启动,到工作区(AGENTS)、会话记忆、心跳主动模式、媒体收发与日常运维诊断,并辅以仓库源码级证据说明每个配置项的底层行为。读完本文,你将能独立搭建并持续运营一个"只属于你"的私人助手。
一、先想清楚:什么是"个人助手"模式
「个人助手」与"把某个群聊接入 AI"是两种完全不同的用法。OpenClaw 的定位是一个 Gateway 网关:它把智能体的运行能力(读工作区、执行命令、调用工具)与聊天渠道(WhatsApp/Telegram/Discord/iMessage)连接起来。当你的目标是"一个专用的 WhatsApp 号码表现得像我的常驻智能体"时,你就进入了本指南所讲的个人助手场景。
在这一场景下,智能体获得的能力包括但不限于:
- 在你的机器上运行命令(取决于你的 Pi 工具设置);
- 在你的工作区读/写文件;
- 通过 WhatsApp/Telegram/Discord/Mattermost(插件)发送消息。
换句话说,你正在把一个"能操作你电脑的 AI"交给一个手机号码来指挥。安全设计必须前置。
二、安全第一:先画好权限边界
文档在开篇就给出三条硬性安全建议,其中第一条的实现细节可以从源码得到印证:
- 始终设置
channels.whatsapp.allowFrom——永远不要在你的个人 Mac 上对全世界开放。在 channels/allow-from.ts 中,isSenderIdAllowed()定义了允许列表的判定逻辑:当allowFrom列表为空时,是否放行取决于allowWhenEmpty(通常为 false);列表含通配符则全部放行;否则精确匹配发送者 ID。也就是说,不配置 allowFrom 时默认是"谁都能触发智能体",这在个人电脑上极其危险。 - 为助手使用专用的 WhatsApp 号码——理由见下文"双手机设置"。
- 心跳默认每 30 分钟一次——在你完全信任设置之前,通过
agents.defaults.heartbeat.every: "0m"禁用。心跳让智能体可以"主动想起你"(比如定时检查任务),但也意味着它会周期性消耗 token 并拥有执行能力,先关掉再逐步放开是稳妥做法。
三、先决条件与安装
- Node 22+;
- OpenClaw 在 PATH 中可用(推荐全局安装);
- 助手专用的第二个手机号码(SIM/eSIM/预付费均可)。
全局安装:
npm install -g openclaw@latest
# 或:pnpm add -g openclaw@latest
从源代码(开发)安装:
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build # 首次运行时自动安装 UI 依赖
pnpm build
pnpm link --global
安装完成后,可以通过 openclaw --version 或 openclaw status 验证命令是否就绪。
四、双手机设置:为什么推荐专用号码
官方推荐的双手机架构示意:
你的手机(个人) 第二部手机(助手)
┌─────────────────┐ ┌─────────────────┐
│ 你的 WhatsApp │ ──────▶ │ 助手 WA │
│ +1-555-YOU │ 消息 │ +1-555-ASSIST │
└─────────────────┘ └────────┬────────┘
│ 通过二维码关联
▼
┌─────────────────┐
│ 你的 Mac │
│ (openclaw) │
│ Pi 智能体 │
└─────────────────┘
关键原则:如果你把个人 WhatsApp 关联到 OpenClaw,发给你的每条消息都会变成"智能体输入"——包括验证码、垃圾短信、家人闲聊,它们都会被当作指令喂给模型。这通常不是你想要的。专用号码配合 allowFrom 白名单,才能保证"只有你(的主号码)能指挥这个助手"。
五、5 分钟快速开始
三步启动一个最小可用实例:
1. 配对 WhatsApp Web(显示二维码,用助手手机扫描):
openclaw channels login
2. 启动 Gateway 网关(保持运行):
openclaw gateway --port 18789
Gateway 是智能体的常驻宿主进程,负责渠道消息的收发出与状态维护,必须保持运行。
3. 在 ~/.openclaw/openclaw.json 中放置最小配置:
{
channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}
现在从你允许列表中的手机向助手号码发消息即可。新手引导完成后,OpenClaw 会自动打开带有 Gateway 网关令牌的仪表板并打印带令牌的链接;之后想重新打开,运行 openclaw dashboard。
说明:配置文件默认位于
~/.openclaw/openclaw.json(JSON5 格式,允许注释与尾逗号);~/.openclaw/目录还存放凭证与会话数据,不属于工作区,不应被纳入工作区 git 仓库。
六、给智能体一个工作区(AGENTS 布局与备份)
OpenClaw 从其工作区目录读取操作指令和"记忆"。默认工作区为 ~/.openclaw/workspace,会在设置/首次智能体运行时自动创建,并写入起始文件:AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md。BOOTSTRAP.md 仅在全新工作区创建(删除后不应再出现),用于一次性首次运行仪式。
各文件的语义可参见 docs/concepts/agent-workspace.md:
AGENTS.md:对智能体的操作指令与记忆使用方式,每个会话开始时加载,适合放置规则与优先级;SOUL.md:人设、语气与行为边界,每个会话加载;USER.md:"用户是谁、如何称呼",每个会话加载;IDENTITY.md:智能体的名字、风格与 emoji,由引导仪式写入;TOOLS.md:本地工具与约定的备注(仅指导,不控制工具可用性);HEARTBEAT.md:可选的心跳运行小清单,保持简短以节省 token;BOOT.md:可选的网关重启启动清单(内部 hooks 启用时执行);memory/YYYY-MM-DD.md:每日记忆日志(一天一个文件),会话开始时建议读取今天与昨天;MEMORY.md(可选):精选长期记忆,仅在主会话/私聊中加载,不会注入群聊上下文;skills/(可选):工作区专属技能,与内置技能同名时覆盖;canvas/(可选):节点展示用的 Canvas UI 文件。
初始化工作区:
openclaw setup
备份建议:把这个文件夹视为 OpenClaw 的"记忆",并将其设为 git 仓库(最好是私有的),这样 AGENTS.md 与记忆文件就有了版本化备份。如果安装了 git,全新的工作区会自动初始化。openclaw setup 可以在不覆盖已有文件的前提下重建缺失的默认文件。完整的 git 初始化、私有远端(GitHub/GitLab/gh CLI)与日常提交流程同样记录在 docs/concepts/agent-workspace.md,注意即使私有仓库也不要把 API 密钥、OAuth token、聊天原始转储等敏感内容提交进去,建议在仓库中放置 .gitignore 并借助密码管理器或环境变量保存真实密钥。
更换工作区路径:使用 agents.defaults.workspace 选择不同的位置(支持 ~ 展开):
{
agent: {
workspace: "~/.openclaw/workspace",
},
}
跳过引导文件创建:如果你已从仓库自行提供工作区文件,可完全禁用引导文件创建:
{
agent: {
skipBootstrap: true,
},
}
引导仪式(seeding 文件 + 一轮一问的 Q&A + 写入身份信息 + 删除 BOOTSTRAP.md)的完整描述见 docs/start/bootstrapping.md。从源码看,skipBootstrap 在 config/types.agent-defaults.ts 中被定义用于"跳过 BOOTSTRAP.md 创建等引导行为,适用于预配置部署",与文档描述一致。
七、把 OpenClaw 变成"助手"的完整配置
OpenClaw 默认为良好的助手设置,但通常你需要调整三处:SOUL.md 中的人设/指令、思考默认值(如果需要)、心跳(一旦信任它后)。下面是一份可直接落地的示例配置(存放于 ~/.openclaw/openclaw.json):
{
logging: { level: "info" },
agent: {
model: "anthropic/claude-opus-4-5",
workspace: "~/.openclaw/workspace",
thinkingDefault: "high",
timeoutSeconds: 1800,
// 从 0 开始;稍后启用。
heartbeat: { every: "0m" },
},
channels: {
whatsapp: {
allowFrom: ["+15555550123"],
groups: {
"*": { requireMention: true },
},
},
},
routing: {
groupChat: {
mentionPatterns: ["@openclaw", "openclaw"],
},
},
session: {
scope: "per-sender",
resetTriggers: ["/new", "/reset"],
reset: {
mode: "daily",
atHour: 4,
idleMinutes: 10080,
},
},
}
各配置项要点:
logging.level:日志级别,日常使用info即可;agent.model:主模型(provider/model 格式)。从 config/defaults.ts 可以看到内置模型别名机制,如opus、sonnet、gpt、gemini、gemini-flash等短别名会被解析为完整模型 ID;agent.thinkingDefault:默认思考级别(off/minimal/low/medium/high/xhigh/adaptive,定义于 config/types.agent-defaults.ts),可按模型能力取舍;agent.timeoutSeconds:单次智能体轮次的超时上限,长任务场景建议调大(示例为 1800 秒);channels.whatsapp.groups["*"].requireMention:群聊中必须 @ 才响应,避免群内误触发;routing.groupChat.mentionPatterns:群聊中视为"提到智能体"的关键词;session.scope:会话作用域。注意在 docs/concepts/session.md 中,直聊默认dmScope: "main"(所有私聊共享主会话,保证连续性),而scope: "per-sender"与dmScope: "per-channel-peer"等设置可把不同发送者的上下文隔离开,防止多人私聊时上下文串扰——如果你的助手可能被多个号码联系,强烈建议启用按发送者隔离的会话模式;session.resetTriggers:触发新会话的指令词(见下一节);session.reset:自动重置策略,mode: "daily"表示每天atHour: 4(本地时间 4 点)重置,idleMinutes: 10080(7 天)表示闲置超过该时长即重置;配置类型定义见 config/types.base.ts。
八、会话与记忆管理
会话状态由 Gateway 统一持有(Gateway 是"事实来源"),相关文件位置:
- 会话记录(transcript):
~/.openclaw/agents/<agentId>/sessions/{{SessionId}}.jsonl - 会话元数据(token 使用量、最后路由等):
~/.openclaw/agents/<agentId>/sessions/sessions.json(旧版:~/.openclaw/sessions/sessions.json)
日常操作:
/new或/reset:为该聊天启动新会话(可用resetTriggers自定义触发词)。如果单独发送,智能体会回复一个简短的问候来确认重置;/compact [instructions]:压缩会话上下文,并报告剩余的上下文预算,适合长对话后控制 token 消耗。
记忆采用"工作区 Markdown 即事实来源"的设计(详见 docs/concepts/memory.md):模型只"记得"被写入磁盘的内容。memory/YYYY-MM-DD.md 是追加式每日日志,MEMORY.md 是精选长期记忆且只在主会话加载。智能体通过两个工具访问记忆:memory_search(语义检索)与 memory_get(按文件/行读取,文件不存在时优雅降级而非报错)。会话存储还内置维护机制(默认 pruneAfter: 30d、maxEntries: 500、rotateBytes: 10mb,可运行 openclaw sessions cleanup 手动触发),避免 sessions.json 无限膨胀。
九、心跳(主动模式):让助手"主动想起你"
默认情况下,OpenClaw 每 30 分钟运行一次心跳,提示词为:
Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.
通过 agents.defaults.heartbeat.every: "0m" 可完全禁用。心跳的完整配置项定义在 config/types.agent-defaults.ts,关键行为包括:
- 如果
HEARTBEAT.md存在但实际为空(只有空行和 markdown 标题如# Heading),OpenClaw 会跳过心跳运行以节省 API 调用; - 如果文件不存在,心跳仍然运行,由模型自行决定做什么;
- 如果智能体回复
HEARTBEAT_OK(可选带短填充;agents.defaults.heartbeat.ackMaxChars控制允许的填充长度,默认 30 字符),OpenClaw 会为该心跳抑制出站投递——即不向聊天渠道推送任何消息; - 心跳运行完整的智能体轮次——更短的间隔会消耗更多 token,请按需设置;
- 从源码看还支持
activeHours(仅在本地时间窗口内运行)、model(心跳专用模型覆盖)、target(投递目标:last/none/指定渠道)、isolatedSession(隔离会话,大幅降低 token 成本)、lightContext(仅保留 HEARTBEAT.md 的轻量引导上下文)等进阶选项,可作为深入调优方向。
开启心跳示例:
{
agent: {
heartbeat: { every: "30m" },
},
}
十、媒体输入与输出
入站附件(图片/音频/文档)可以通过模板变量暴露给你的命令:
{{MediaPath}}:本地临时文件路径;{{MediaUrl}}:伪 URL;{{Transcript}}:如果启用了音频转录,则为转录文本。
出站附件:智能体在回复中单独一行包含 MEDIA:<path-or-url>(无空格),OpenClaw 会提取它们并将媒体与文本一起发送。示例:
这是截图。
MEDIA:https://example.com/screenshot.png
媒体处理在仓库中有完整实现与测试覆盖(例如 auto-reply/media-note.ts 及其测试 auto-reply/media-note.test.ts),入站媒体还会被暂存进 sandbox 工作区供命令使用(对应 reply.triggers 的入站媒体处理链路)。
十一、运维检查清单
日常健康检查命令:
openclaw status # 本地状态(凭证、会话、排队事件)
openclaw status --all # 完整诊断(只读,可粘贴)
openclaw status --deep # 添加 Gateway 网关健康探测(Telegram + Discord)
openclaw health --json # Gateway 网关健康快照(WS)
日志位于 /tmp/openclaw/(默认文件名:openclaw-YYYY-MM-DD.log)。此外 openclaw doctor 会在检测到多余工作区目录、配置异常等潜在问题时给出警告,是排障时的第一选择。
十二、下一步
搭建好个人助手之后,可以继续深入以下主题(均为本仓库文档,路径以仓库根目录为准):
- WebChat 网页聊天:WebChat
- Gateway 网关运维:Gateway 网关运行手册
- 定时任务 + 唤醒:定时任务
- 心跳与定时任务的取舍:cron vs heartbeat
- macOS 菜单栏配套应用:OpenClaw macOS 应用
- iOS 节点应用:iOS 应用
- Android 节点应用:Android 应用
- Windows 状态:Windows (WSL2)
- Linux 状态:Linux 应用
- 网关认证与安全:认证、密钥管理