使用 OpenClaw 构建个人助手

OpenClaw 是用于 Pi 代理的 WhatsApp + Telegram + Discord + iMessage gateway。插件添加 Mattermost。本指南是”个人助手”设置：一个专用 WhatsApp 号码，行为像你的常驻代理。

安全第一

你正在将代理置于可以执行以下操作的位置：

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

保守开始：

  • 始终设置 channels.whatsapp.allowFrom（永远不要在你的个人 Mac 上运行开放式的）。
  • 为助手使用专用 WhatsApp 号码。
  • 心跳现在默认为每 30 分钟一次。通过设置 agents.defaults.heartbeat.every: "0m" 禁用，直到你信任该设置。

前提条件

  • OpenClaw 已安装并完成入门 — 如果你还没有完成，请参见入门指南
  • 助手的第二个电话号码（SIM/eSIM/预付费）

双手机设置（推荐）

你想要的：

flowchart TB
    A["<b>你的手机（个人）<br></b><br>你的 WhatsApp<br>+1-555-YOU"] -- 消息 --> B["<b>第二部手机（助手）<br></b><br>助手 WA<br>+1-555-ASSIST"]
    B -- 通过 QR 链接 --> C["<b>你的 Mac（openclaw）<br></b><br>Pi 代理"]

如果你将个人 WhatsApp 链接到 OpenClaw，你的每条消息都成为”代理输入”。这很少是你想要的。

5 分钟快速开始

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

现在从你的允许列表中的手机向助手号码发送消息。

当 onboarding 完成时，我们自动打开仪表板并打印一个干净的（非 token 化）链接。如果提示认证，将 gateway.auth.token 中的 token 粘贴到 Control UI 设置中。稍后重新打开：openclaw dashboard。

给代理一个工作区（代理）

OpenClaw 从其工作区目录读取操作指令和”内存”。

默认情况下，OpenClaw 使用 ~/.openclaw/workspace 作为代理工作区，并会在设置/首次代理运行时自动创建它（加上启动文件 AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md、HEARTBEAT.md）。BOOTSTRAP.md 仅在工作区全新创建时生成（删除后不应再次出现）。MEMORY.md 是可选的（不是自动创建的）；当存在时，它会为正常会话加载。子代理会话仅注入 AGENTS.md 和 TOOLS.md。

提示：将此文件夹视为 OpenClaw 的”内存”并将其设为 git 仓库（最好是私有的），以便你的 AGENTS.md + 内存文件得到备份。如果已安装 git，全新工作区会自动初始化。

openclaw setup

完整工作区布局 + 备份指南：代理工作区 内存工作流程：内存

可选：使用 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 配置）。如果单独发送，代理会回复简短的 hello 以确认重置。
  • /compact [instructions] 压缩会话上下文并报告剩余的上下文预算。

心跳（主动模式）

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

  • 如果 HEARTBEAT.md 存在但实际上为空（仅空白行和 markdown 标题如 # Heading），OpenClaw 会跳过心跳运行以节省 API 调用。
  • 如果文件缺失，心跳仍会运行，模型决定做什么。
  • 如果代理回复 HEARTBEAT_OK（可选带简短填充；参见 agents.defaults.heartbeat.ackMaxChars），OpenClaw 会抑制该心跳的出站传递。
  • 默认情况下，允许向 DM 风格的 user:<id> 目标传递心跳。设置 agents.defaults.heartbeat.directPolicy: "block" 以抑制直接目标传递，同时保持心跳运行活跃。
  • 心跳运行完整代理轮次 — 更短的间隔消耗更多 token。
{
  agent: {
    heartbeat: { every: "30m" },
  },
}

媒体输入和输出

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

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

来自代理的出站附件：在自己的行上包含 MEDIA:<path-or-url>（无空格）。示例：

这是截图。
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）。

下一步