用 OpenClaw 搭建个人助理（Clawd 风格）

OpenClaw 是一个为 Pi Agent 提供的 WhatsApp + Telegram + Discord + iMessage Gateway。Plugin 可以添加 Mattermost 支持。本指南介绍”个人助理”配置方式：用一个专属 WhatsApp 号码作为你的全天候 Agent。

⚠️ 安全第一

你要让 Agent 处于这样的位置：

  • 在你的电脑上运行命令（取决于你的 Pi 工具配置）
  • 在你的 Workspace 中读写文件
  • 通过 WhatsApp/Telegram/Discord/Mattermost（Plugin）发送消息

从保守的配置开始：

  • 务必设置 channels.whatsapp.allowFrom（千万别在你的个人 Mac 上开放给全世界）。
  • 为助理使用专属的 WhatsApp 号码。
  • Heartbeat 现在默认每 30 分钟触发一次。在你信任这套配置之前，先通过设置 agents.defaults.heartbeat.every: "0m" 禁用它。

前置要求

  • 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

双手机配置（推荐）

你需要这样的配置：

你的手机（个人）              备用手机（助理）
┌─────────────────┐           ┌─────────────────┐
│  你的 WhatsApp  │  ──────▶  │  助理 WA        │
│  +1-555-YOU     │  消息     │  +1-555-CLAWD   │
└─────────────────┘           └────────┬────────┘
                                       │ 通过二维码关联
                                       ▼
                              ┌─────────────────┐
                              │  你的 Mac       │
                              │  (openclaw)      │
                              │    Pi Agent     │
                              └─────────────────┘

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

5 分钟快速开始

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

现在从你的白名单手机给助理号码发消息。

引导完成后，我们会自动打开控制面板并显示你的 Gateway Token 和带 Token 的链接。之后要重新打开：openclaw dashboard。

给 Agent 一个 Workspace（AGENTS）

Clawd 从它的 Workspace 目录读取操作指令和”记忆”。

默认情况下，OpenClaw 使用 ~/clawd 作为 Agent Workspace，并会在设置/首次运行 Agent 时自动创建它（包括初始的 AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md）。BOOTSTRAP.md 只在 Workspace 全新时创建（删除后不会再次出现）。

提示：把这个文件夹当作 Clawd 的”记忆”，建议用 git 管理（最好是私有仓库），这样你的 AGENTS.md 和记忆文件就有备份了。如果安装了 git，全新的 Workspace 会自动初始化。

openclaw setup

完整的 Workspace 布局和备份指南：Agent Workspace 记忆工作流程：Memory

可选：通过 agents.defaults.workspace 选择不同的 Workspace（支持 ~）。

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

如果你已经从仓库提供自己的 Workspace 文件，可以完全禁用 Bootstrap 文件创建：

{
  agent: {
    skipBootstrap: true
  }
}

把它变成”助理”的配置

OpenClaw 默认就是很好的助理配置，但你通常会想调整：

  • SOUL.md 中的人格/指令
  • 思考默认设置（如果需要）
  • Heartbeat（在你信任它之后）

示例：

{
  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
    }
  }
}

Session 和记忆

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

Heartbeat（主动模式）

默认情况下，OpenClaw 每 30 分钟运行一次 Heartbeat，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 会跳过 Heartbeat 运行以节省 API 调用。
  • 如果文件不存在，Heartbeat 仍会运行，由模型决定做什么。
  • 如果 Agent 回复 HEARTBEAT_OK（可选带简短填充；见 agents.defaults.heartbeat.ackMaxChars），OpenClaw 会抑制该 Heartbeat 的出站消息。
  • Heartbeat 运行完整的 Agent 回合——间隔越短消耗的 Token 越多。
{
  agent: {
    heartbeat: { every: "30m" }
  }
}

媒体输入和输出

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

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

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

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

OpenClaw 会提取这些内容并将它们作为媒体与文本一起发送。

运维检查清单

openclaw status          # 本地状态（凭证、Session、排队事件）
openclaw status --all    # 完整诊断（只读，可粘贴）
openclaw status --deep   # 添加 Gateway 健康探测（Telegram + Discord）
openclaw health --json   # Gateway 健康快照（WS）

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

下一步