用 OpenClaw 打造个人助手

OpenClaw 是一个面向 Pi Agent 的 WhatsApp + Telegram + Discord + iMessage 网关。Mattermost 通过插件支持。本指南面向「个人助手」场景：一个专属的 WhatsApp 号码，充当你的全天候 Agent。

⚠️ 安全第一

你正在把一个 Agent 放在这样的位置上：

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

先从保守配置开始：

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

前置要求

  • 已安装并完成 onboarding 的 OpenClaw — 如果还没做，请先看 快速上手
  • 一个专用于助手的手机号（SIM/eSIM/预付费卡）

双手机方案（推荐）

推荐的架构如下：

flowchart TB
    A["<b>Your Phone (personal)<br></b><br>Your WhatsApp<br>+1-555-YOU"] -- message --> B["<b>Second Phone (assistant)<br></b><br>Assistant WA<br>+1-555-ASSIST"]
    B -- linked via QR --> C["<b>Your Mac (openclaw)<br></b><br>Pi agent"]

如果把你的个人 WhatsApp 关联到 OpenClaw，你收到的每条消息都会变成”Agent 输入”。这通常不是你想要的。

5 分钟快速上手

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

现在用白名单中的手机号给助手号码发消息就行了。

onboarding 完成后，会自动打开 dashboard 并打印一个干净的（未带 token 的）链接。如果提示需要认证，把 gateway.auth.token 中的 token 粘贴到 Control UI 设置里。之后要再次打开：openclaw dashboard。

给 Agent 一个工作区（AGENTS）

OpenClaw 从工作区目录中读取运行指令和”记忆”。

默认情况下，OpenClaw 使用 ~/.openclaw/workspace 作为 Agent 工作区，在配置或首次运行时会自动创建（包括 AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md、HEARTBEAT.md 等初始文件）。BOOTSTRAP.md 只在全新工作区时创建（删除后不会再生成）。MEMORY.md 是可选的（不会自动创建）；存在时，会在普通会话中加载。子 Agent 会话只注入 AGENTS.md 和 TOOLS.md。

建议：把这个文件夹当作 OpenClaw 的”记忆”，做成一个 git 仓库（最好是私有的），这样 AGENTS.md 和记忆文件都有备份。如果安装了 git，全新工作区会自动初始化为 git 仓库。

openclaw setup

完整的工作区布局与备份指南：Agent 工作区 记忆工作流：记忆

可选：通过 agents.defaults.workspace 指定其他工作区路径（支持 ~）。

{
  agent: {
    workspace: "~/.openclaw/workspace",
  },
}

如果你已经从自己的仓库中提供了工作区文件，可以完全禁用引导文件的创建：

{
  agent: {
    skipBootstrap: true,
  },
}

把它变成”助手”的配置

OpenClaw 默认配置已经适合助手场景，但你通常需要调整：

  • SOUL.md 中的人设和指令
  • 思维链默认设置（按需）
  • 心跳（在你信任它之后再启用）

示例：

{
  logging: { level: "info" },
  agent: {
    model: "anthropic/claude-opus-4-6",
    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,
    },
  },
}

会话与记忆

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

心跳（主动模式）

默认情况下，OpenClaw 每 30 分钟运行一次心跳，使用的 prompt 是： 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 调用。
  • 如果文件不存在，心跳仍会运行，由模型自行决定做什么。
  • 如果 Agent 回复 HEARTBEAT_OK（可附带少量填充文字，参见 agents.defaults.heartbeat.ackMaxChars），OpenClaw 会压制该次心跳的对外发送。
  • 默认允许心跳向 DM 类型的 user:<id> 目标发送消息。设置 agents.defaults.heartbeat.directPolicy: "block" 可以在保持心跳运行的同时禁止向直接目标投递。
  • 心跳会运行完整的 Agent 回合——越频繁的间隔消耗越多 token。
{
  agent: {
    heartbeat: { every: "30m" },
  },
}

媒体收发

入站附件（图片/音频/文档）可以通过模板传递给你的命令：

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

Agent 的出站附件：在独立一行写 MEDIA:<path-or-url>（不要有空格）。示例：

Here's the screenshot.
MEDIA:https://example.com/screenshot.png

OpenClaw 会提取这些内容，随文本一起作为媒体发送。

运维清单

openclaw status          # 本地状态（凭据、会话、排队事件）
openclaw status --all    # 完整诊断（只读，可直接粘贴）
openclaw status --deep   # 额外进行 Gateway 健康探测（Telegram + Discord）
openclaw health --json   # Gateway 健康快照（WS）

日志存放在 /tmp/openclaw/（默认文件名：openclaw-YYYY-MM-DD.log）。

接下来

arrow_back
上一页
Onboarding
下一页
Wizard CLI Reference
arrow_forward