ClawCN - OpenClaw 中文版

主题

使用 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/预付费)
bash
npm install -g openclaw@latest
# or: pnpm add -g openclaw@latest

从源码安装(开发):

bash
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build # auto-installs UI deps on first run
pnpm build
pnpm link --global

双手机设置(推荐) ​

您需要这样:

Your Phone (personal)          Second Phone (assistant)
┌─────────────────┐           ┌─────────────────┐
│  Your WhatsApp  │  ──────▶  │  Assistant WA   │
│  +1-555-YOU     │  message  │  +1-555-ASSIST  │
└─────────────────┘           └────────┬────────┘
                                       │ linked via QR
                                       ▼
                              ┌─────────────────┐
                              │  Your Mac       │
                              │  (openclaw)      │
                              │    Pi agent     │
                              └─────────────────┘

如果您将个人 WhatsApp 链接到 OpenClaw,发给您的每条消息都会成为"代理输入"。这很少是您想要的。

5 分钟快速启动 ​

  1. 配对 WhatsApp Web(显示二维码;用助手手机扫描):
bash
openclaw channels login
  1. 启动网关(保持运行):
bash
openclaw gateway --port 18789
  1. 在 ~/.openclaw/openclaw.json 中放入最小配置:
json5
{
  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,全新工作区会自动初始化。

bash
openclaw setup

完整工作区布局 + 备份指南:代理工作区 记忆工作流:记忆

可选:使用 agents.defaults.workspace 选择不同的工作区(支持 ~)。

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

如果您已经从仓库提供自己的工作区文件,可以完全禁用引导文件创建:

json5
{
  agent: {
    skipBootstrap: true,
  },
}

将其变成"助手"的配置 ​

OpenClaw 默认为良好的助手设置,但您通常需要调整:

  • SOUL.md 中的角色/指令
  • 思考默认值(如果需要)
  • 心跳(一旦您信任它)

示例:

json5
{
  logging: { level: "info" },
  agent: {
    model: "anthropic/claude-opus-4-5",
    workspace: "~/.openclaw/workspace",
    thinkingDefault: "high",
    timeoutSeconds: 1800,
    // Start with 0; enable later.
    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 存在但实际上为空(仅有空行和 markdown 标题,如 # Heading),OpenClaw 会跳过心跳运行以节省 API 调用。
  • 如果文件缺失,心跳仍会运行,模型决定如何处理。
  • 如果代理回复 HEARTBEAT_OK(可选择带有简短填充;见 agents.defaults.heartbeat.ackMaxChars),OpenClaw 会抑制该心跳的出站传递。
  • 心跳运行完整的代理回合 — 较短的间隔会消耗更多令牌。
json5
{
  agent: {
    heartbeat: { every: "30m" },
  },
}

媒体输入和输出 ​

入站附件(图像/音频/文档)可以通过模板传递给您的命令:

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

来自代理的出站附件:单独一行包含 MEDIA:<path-or-url>(无空格)。示例:

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

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

操作检查清单 ​

bash
openclaw status          # local status (creds, sessions, queued events)
openclaw status --all    # full diagnosis (read-only, pasteable)
openclaw status --deep   # adds gateway health probes (Telegram + Discord)
openclaw health --json   # gateway health snapshot (WS)

日志位于 /tmp/openclaw/ 下(默认:openclaw-YYYY-MM-DD.log)。

后续步骤 ​