openclaw 文档

简体中文

English

简体中文

English

Appearance

使用 openclaw 构建个人助手（Clawd 风格） ​

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
# 或者：pnpm add -g openclaw@latest

从源代码安装（开发）：

bash
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build # 首次运行时自动安装 UI 依赖
pnpm build
pnpm link --global

双手机设置（推荐） ​

你想要这样的设置：

你的手机（个人）              第二部手机（助手）
┌─────────────────┐           ┌─────────────────┐
│  你的 WhatsApp  │  ──────▶  │  助手 WhatsApp  │
│  +1-555-YOU     │  消息     │  +1-555-CLAWD   │
└─────────────────────────┘           └────────┬────────┘
                                       │ 通过 QR 链接
                                       ▼
                              ┌─────────────────┐
                              │  你的 Mac       │
                              │  (openclaw)      │
                              │    Pi 代理      │
                              └─────────────────┘

如果你将你的个人 WhatsApp 链接到 openclaw，每条发给你的消息都会变成"代理输入"。这通常不是你想要的。

5 分钟快速开始 ​

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

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

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

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

Clawd 从其工作区目录读取操作指令和"记忆"。

默认情况下，openclaw 使用 ~/clawd 作为代理工作区，并会在设置/首次代理运行时自动创建它（以及初始的 AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md）。BOOTSTRAP.md 仅在工作区全新时创建（删除后不应重新出现）。

提示：将此文件夹视为 Clawd 的"记忆"并使其成为 git 仓库（最好是私有的），以便你的 AGENTS.md + 记忆文件得到备份。如果安装了 git，全新的工作区会自动初始化。

bash
openclaw setup

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

可选：使用 agents.defaults.workspace 选择不同的工作区（支持 ~）。

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

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

json5
{
  agent: {
    skipBootstrap: true
  }
}

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

openclaw 默认为良好的助手设置，但你通常需要调整：

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

示例：

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

会话和记忆 ​

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

心跳（主动模式） ​

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

  • 如果 HEARTBEAT.md 存在但实际上是空的（只有空行和像 # Heading 这样的 markdown 标题），openclaw 会跳过心跳运行以节省 API 调用。
  • 如果文件缺失，心跳仍然运行，模型决定做什么。
  • 如果代理回复 HEARTBEAT_OK（可选带有短填充；参见 agents.defaults.heartbeat.ackMaxChars），openclaw 会抑制该心跳的出站传递。
  • 心跳运行完整的代理轮次 — 更短的间隔会消耗更多令牌。
json5
{
  agent: {
    heartbeat: { every: "30m" }
  }
}

媒体输入和输出 ​

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

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

代理的出站附件：在单独的一行中包含 MEDIA:<path-or-url>（无空格）。示例：

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

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

运维检查清单 ​

bash
openclaw status          # 本地状态（凭据、会话、排队事件）
openclaw status --all    # 完整诊断（只读、可粘贴）
openclaw status --deep   # 添加网关健康检查（Telegram + Discord）
openclaw health --json   # 网关健康快照（WS）

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

后续步骤 ​