古法编程

Appearance

用 OpenClaw 搭建个人 AI 助手，核心是双手机加白名单：一台手机（个人）通过另一台专用号码（助手）与 OpenClaw 通信。按本指南操作，5 分钟就能让 WhatsApp 通道跑起来，再配置工作区（AGENTS.md、SOUL.md 等）和可选的心跳任务。注意：安全第一，务必设置 channels.whatsapp.allowFrom 和禁用心跳（agents.defaults.heartbeat.every: "0m"）直到你信任配置。诊断用 openclaw status 或 openclaw status --deep。

OpenClaw 个人助手搭建指南 ​

OpenClaw 是一个自托管的网关，连接 Discord、Google Chat、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp、Zalo 等渠道到 AI 智能体。本指南介绍“个人助手”配置：一个专用 WhatsApp 号码，作为始终在线的 AI 助手。

⚠️ 安全优先 ​

你把智能体放到了可以执行以下操作的位置：

  • 在你的机器上运行命令（取决于工具策略）
  • 在工作区读写文件
  • 通过 WhatsApp/Telegram/Discord/Mattermost 等渠道向外发送消息

从保守配置开始：

  • 务必设置 channels.whatsapp.allowFrom（永远不要在个人 Mac 上对全世界开放）。
  • 为助手使用一个专用 WhatsApp 号码（不要用个人号码）。
  • 心跳默认每 30 分钟一次。在信任配置之前，通过设置 agents.defaults.heartbeat.every: "0m" 禁用它。

前置条件 ​

  • OpenClaw 已安装并运行过 openclaw onboard — 如果还没完成，先参考 快速入门
  • 一个第二手机号（SIM/eSIM/预付费）用于助手 WhatsApp 号码

双手机方案（推荐） ​

架构是这样的：

mermaid
flowchart TB
    A["你的手机（个人）<br>你的 WhatsApp<br>+1-555-YOU"] -- 发消息 --> B["第二台手机（助手）<br>助手 WhatsApp<br>+1-555-ASSIST"]
    B -- 扫码关联 --> C["你的 Mac（OpenClaw）<br>AI 智能体"]

如果你把个人 WhatsApp 直接关联到 OpenClaw，那么发给你自己的每条消息都会变成“智能体输入”，这通常不是你想要的。

5 分钟快速启动 ​

  1. 配对 WhatsApp Web（显示 QR 码；用助手手机扫描）：
bash
openclaw channels login
  1. 启动 Gateway（保持运行）：
bash
openclaw gateway --port 18789
  1. 在 ~/.openclaw/openclaw.json 中放入最简配置：
json5
{
  gateway: { mode: "local" },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

现在从白名单手机向助手号码发一条消息。当 onboarding 完成后，OpenClaw 自动打开仪表盘并打印一个无 token 的链接。如果仪表盘提示认证，把配置中的 gateway.auth.token 粘贴到 Control UI 设置中。如果改成 gateway.auth.mode 为 password，则用密码登录。之后重新打开：openclaw dashboard。

给智能体配置工作区（AGENTS） ​

OpenClaw 从工作区目录读取操作指令和“记忆”。

默认工作区：~/.openclaw/workspace。首次运行或执行 openclaw setup 时会自动创建该目录，并生成以下文件：AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md、HEARTBEAT.md。BOOTSTRAP.md 仅在工作区全新时创建（删除后不会重新生成）。MEMORY.md 是可选的（不会自动创建）；当存在时，会在普通会话中加载。子智能体会话只注入 AGENTS.md 和 TOOLS.md。

建议将工作区目录做成 git 仓库（最好是私有），以便备份 AGENTS.md 和记忆文件。如果已安装 git，全新工作区会自动初始化为 git。

bash
openclaw setup

完整工作区布局 + 备份指南：智能体工作区 记忆工作流：记忆（Memory）

可选：通过 agents.defaults.workspace 指定其他目录（支持 ~）：

json5
{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
    },
  },
}

如果你自带工作区文件（从仓库直接复制），可以禁用 bootstrap 文件创建：

json5
{
  agents: {
    defaults: {
      skipBootstrap: true,
    },
  },
}

把它变成“助手”的配置 ​

OpenClaw 默认已是一个不错的助手配置，但你通常需要调整：

  • SOUL.md 中的角色/指令
  • 思考模式默认值（如需要）
  • 心跳（信任后再开启）

完整示例配置：

json5
{
  logging: { level: "info" },
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-opus-4-6" },
      workspace: "~/.openclaw/workspace",
      thinkingDefault: "high",
      timeoutSeconds: 1800,
      // 先设为 0；之后再开启
      heartbeat: { every: "0m" },
    },
    list: [
      {
        id: "main",
        default: true,
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: {
        "*": { requireMention: true },
      },
    },
  },
  session: {
    scope: "per-sender",
    resetTriggers: ["/new", "/reset"],
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 10080,
    },
  },
}

会话与记忆 ​

  • 会话文件目录：~/.openclaw/agents/<agentId>/sessions/&#123;&#123;SessionId&#125;&#125;.jsonl
  • 会话元数据（token 用量、最后路由等）：~/.openclaw/agents/<agentId>/sessions/sessions.json（旧版路径：~/.openclaw/sessions/sessions.json）
  • /new 或 /reset 在对应聊天中开启新会话（可通过 resetTriggers 配置）。单独发送时，OpenClaw 会确认重置而不调用模型。
  • /compact [指令] 压缩会话上下文并报告剩余上下文预算。

心跳（主动模式） ​

默认情况下，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" 可禁用。

  • 如果 HEARTBEAT.md 存在但实际为空（只有空行和 Markdown 标题如 # Heading），OpenClaw 会跳过本次心跳以节省 API 调用。
  • 如果文件缺失，心跳仍会运行，模型自行决定做什么。
  • 如果智能体回复 HEARTBEAT_OK（可选附带简短内容；参见 agents.defaults.heartbeat.ackMaxChars），OpenClaw 会抑制该次心跳的向外投递。
  • 默认情况下，心跳向 DM 风格 user:&lt;id&gt; 目标的投递是允许的。设置 agents.defaults.heartbeat.directPolicy: "block" 可在保持心跳运行的同时阻止直接目标投递。
  • 心跳会运行完整的智能体轮次——间隔越短，消耗 token 越多。
json5
{
  agents: {
    defaults: {
      heartbeat: { every: "30m" },
    },
  },
}

媒体收发 ​

入站附件（图片/音频/文档）可通过模板变量暴露给智能体：

  • &#123;&#123;MediaPath&#125;&#125;（本地临时文件路径）
  • &#123;&#123;MediaUrl&#125;&#125;（伪 URL）
  • &#123;&#123;Transcript&#125;&#125;（如果启用了音频转录）

智能体发出附件：在回复中单独成行包含 MEDIA:<路径或URL>（不加空格）。示例：

这是截图。
MEDIA:https://example.com/screenshot.png

OpenClaw 会提取这些内容，将媒体与文本一起发送。

本地路径行为遵循与智能体相同的文件读取信任模型：

  • 如果 tools.fs.workspaceOnly 为 true，出站 MEDIA: 本地路径限制在 OpenClaw 临时根目录、媒体缓存、智能体工作区路径和沙箱生成的文件。
  • 如果 tools.fs.workspaceOnly 为 false，出站 MEDIA: 可以使用智能体已被允许读取的主机本地文件。
  • 本地路径可以是绝对路径、工作区相对路径或 ~/ 开头的 home 相对路径。
  • 主机本地发送仍只允许媒体和安全文档类型（图片、音频、视频、PDF 和 Office 文档）。纯文本和类似机密文件不会被当作可发送媒体。

这意味着当你的 fs 策略已允许读取时，工作区外生成的图片/文件现在也能通过 MEDIA: 发送，而无需重新开放任意主机文本附件泄露。

运维检查命令 ​

bash
openclaw status          # 本地状态（凭证、会话、排队事件）
openclaw status --all    # 完整诊断（只读，可粘贴分享）
openclaw status --deep   # 增加 Gateway 健康探测（当渠道支持时）
openclaw health --json   # Gateway 健康快照（WS；默认返回缓存快照）

日志默认存储在 /tmp/openclaw/ 下，文件名为 openclaw-YYYY-MM-DD.log。

下一步 ​

常见问题 ​

OpenClaw 配置了 WhatsApp 但助手不回复，怎么办？ ​

检查三个方面：1）确认 channels.whatsapp.allowFrom 中包含了你的手机号（格式为国际全号，例如 +15555550123）；2）用 openclaw channels login 重新配对 WhatsApp Web，确保扫码成功；3）查看日志 /tmp/openclaw/openclaw-YYYY-MM-DD.log 是否有错误。然后从白名单手机发一条简单消息，正常应收到回复。

心跳怎么测试是否正常？ ​

将心跳间隔临时设为短时间（如 every: "1m"），然后观察 openclaw status 或日志。默认提示词会要求智能体回复 HEARTBEAT_OK 表示无事。如果智能体回复了其他内容，会通过渠道发送给你。确认后记得改回合理间隔或禁用。

openclaw status --deep 和 openclaw health --json 有什么区别？ ​

openclaw status --deep 是 CLI 命令，会主动询问 Gateway 进行实时健康探测（包括渠道探针，如果支持），返回诊断文本。openclaw health --json 是获取 Gateway 健康快照（默认返回缓存的最新快照，可通过 WS 获取），适合用于脚本或监控集成。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策