OpenClaw 助手

OpenClaw 是一个用于 Pi 代理的 WhatsApp + Telegram + Discord + iMessage 网关。插件添加了 Mattermost。本指南是“个人助手”设置：一个专门的 WhatsApp 号码，表现得像你永远在线的代理。

⚠️ 安全第一

你正在让代理处于以下位置：

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

保持保守：

始终设置 channels.whatsapp.allowFrom（永远不要在你的个人 Mac 上向全世界开放运行）。
为助手使用一个专用的 WhatsApp 号码。
心跳现在默认为每 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-ASSIST  │
│                 │           └────────┬────────┘
└─────────────────┘                    │ 通过二维码关联
                                      ▼
                             ┌─────────────────┐
                             │  你的 Mac       │
                             │  (openclaw)      │
                             │    Pi 代理       │
                             └─────────────────┘

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

5 分钟快速开始

配对 WhatsApp Web（显示二维码；用助手手机扫描）：

openclaw channels login

启动网关（让它保持运行）：

openclaw gateway --port 18789

在 ~/.openclaw/openclaw.json 中放置一个最小配置：

{
  channels: { whatsapp: { allowFrom: ["+15555550123"] } }
}

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

当引导完成时，我们会自动打开带有网关令牌的仪表板并打印令牌化链接。以后重新打开：openclaw dashboard。

给代理一个工作区 (AGENTS)

OpenClaw 从其工作区目录读取操作说明和“记忆”。

默认情况下，OpenClaw 使用 ~/.openclaw/workspace 作为代理工作区，并在设置/首次代理运行时自动创建它（加上初始的 AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md）。BOOTSTRAP.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-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
    }
  }
}

会话和记忆

会话文件：~/.openclaw/agents/<agentId>/sessions/{{SessionId}}.jsonl
会话元数据（令牌使用情况，上次路由等）：~/.openclaw/agents/<agentId>/sessions/sessions.json（旧版：~/.openclaw/sessions/sessions.json）
/new 或 /reset 为该聊天启动一个新的会话（可通过 resetTriggers 配置）。如果单独发送，代理会回复一个简短的问好以确认重置。
/compact [instructions] 压缩会话上下文并报告剩余的上下文预算。

心跳（主动模式）

默认情况下，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 存在但实际上是空的（只有空行和像 # Heading 这样的 markdown 标题），OpenClaw 会跳过心跳运行以节省 API 调用。
如果文件丢失，心跳仍然运行，模型决定做什么。
如果代理回复 HEARTBEAT_OK（可选带有短填充；参见 agents.defaults.heartbeat.ackMaxChars），OpenClaw 会抑制该心跳的出站传递。
心跳运行完整的代理回合 —— 较短的间隔会消耗更多 token。

{
  agent: {
    heartbeat: { every: "30m" }
  }
}

媒体输入与输出

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