OpenClawSkills
GitHub
快速入门 • 阅读需 10 分钟

个人助手配置

将 OpenClaw 作为个人助手运行的端到端指南（含安全注意事项）。

OpenClaw 是一个面向 **Pi** agents 的 WhatsApp + Telegram + Discord + iMessage 网关（Gateway）。插件还可以接入 Mattermost。本指南是“个人助手”配置：使用一个专用的 WhatsApp 号码，让它表现为随时在线的 Agent。

Tutorial.step

⚠️ 安全优先

你把一个 Agent 放在了可能做到这些事的位置： - 在你的机器上运行命令（取决于你的 Pi 工具配置） - 读/写你工作区里的文件 - 通过 WhatsApp/Telegram/Discord/Mattermost（插件）向外发送消息 建议从保守配置开始：

- 始终设置 `channels.whatsapp.allowFrom`（不要在个人电脑上运行一个“对全世界开放”的助手）。

- 为助手使用一个独立的 WhatsApp 号码。

- 心跳（Heartbeat）默认每 30 分钟一次。建议先禁用，直到你信任这个设置：将 `agents.defaults.heartbeat.every: "0m"`。

Tutorial.step

前置条件

- Node **22+** - 系统 PATH 中能找到 OpenClaw（推荐：全局安装） - 一个第二手机号（SIM/eSIM/预付费均可），用于助手号码

Bash
npm install -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
Tutorial.step

双手机方案（推荐）

你想要的是这种结构：

Terminal
你的手机（个人）                 第二部手机（助手）
┌─────────────────┐           ┌─────────────────┐
│   你的 WhatsApp  │  ──────▶  │  助手 WhatsApp  │
│  +1-555-YOU      │  message  │  +1-555-ASSIST  │
└─────────────────┘           └────────┬────────┘
                                       │ 通过 QR 码链接
                                       ▼
                              ┌─────────────────┐
                              │  你的 Mac        │
                              │  (openclaw)      │
                              │    Pi agent      │
                              └─────────────────┘

如果你把个人 WhatsApp 账号链接 to OpenClaw，那么每条发给你的消息都会变成 “agent 输入”。这通常不是你想要的。

Tutorial.step

5 分钟快速开始

1. 配对 WhatsApp Web（会显示 QR；用助手手机扫描）：

Bash
openclaw channels login

2. 启动 Gateway（保持它一直运行）：

Bash
openclaw gateway --port 18789

3. 在 `~/.openclaw/openclaw.json` 写一个最小配置：

Bash
'{'
  channels: '{' whatsapp: '{' allowFrom: ["+15555550123"] '}' '}',
'}'

现在，用你的 allowlist 手机号给助手号码发消息。 当 onboarding 完成后，我们会自动打开带 token 的 dashboard 链接，并把 token 化的 URL 打印出来。之后要再次打开：`openclaw dashboard`。

Tutorial.step

给 Agent 一个工作区（AGENTS）

OpenClaw 会从它的工作区目录读取操作指令和“记忆”。 默认情况下，OpenClaw 使用 `~/.openclaw/workspace` 作为 agent 工作区，并会在 setup/首次运行时自动创建（以及初始的 `AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`）。`BOOTSTRAP.md` 只会在工作区全新时创建（删除后不应反复出现）。

建议：把这个文件夹当作 OpenClaw 的“记忆”，并把它做成一个 git 仓库（最好是私有仓库）来备份 `AGENTS.md` 与记忆文件。如果系统安装了 git，全新的工作区会自动初始化为仓库。

Bash
openclaw setup

完整工作区结构与备份指南：Agent 工作区

记忆工作流：Memory

可选：通过 `agents.defaults.workspace` 设置不同的工作区路径（支持 `~`）：

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

如果你已经从仓库分发自己的工作区文件，可以完全禁用 bootstrap 文件创建：

Json5
{
  agent: {
    skipBootstrap: true,
  },
}
Tutorial.step

让它真正“像个助手”的配置

OpenClaw 默认已经是一个不错的助手设置，但你通常会想调整：

- `SOUL.md` 里的 persona / 指令

- 思考默认值（如有需要）

- 心跳（在你信任之后再启用）

示例：

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,
    },
  },
}
Tutorial.step

会话与记忆

- 会话文件：`<code1>~/.openclaw/agents/<agentId>/sessions/{'{SessionId}'}.jsonl</code1>`

- 会话元数据（token 用量、上一次路由等）：`<code1>~/.openclaw/agents/<agentId>/sessions/sessions.json</code1>`（旧路径：`<code2>~/.openclaw/sessions/sessions.json</code2>`）

- `/new` 或 `/reset` 会为该聊天开启一个新会话（可通过 `resetTriggers` 配置）。如果单独发送该命令，Agent 会回复一个简短的确认消息。

- `/compact [instructions]` 会压缩会话上下文并报告剩余的上下文预算。

Tutorial.step

心跳（主动模式）

默认情况下，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` 这样的标题），OpenClaw 会跳过本次心跳以节省 API 调用。

- 如果文件不存在，心跳仍会运行，由模型决定做什么。

- 如果 Agent 回复 `HEARTBEAT_OK`（可带少量填充；参见 `agents.defaults.heartbeat.ackMaxChars`），OpenClaw 会抑制本次心跳的对外发送。

- 心跳是完整的 agent turn；间隔越短，消耗 token 越多。

Json5
{
  agent: {
    heartbeat: { every: "30m" },
  },
}
Tutorial.step

输入与输出媒体

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

- `<code1>'{'{MediaPath}'}'</code1>`（本地临时文件路径）

- `<code2>'{'{MediaUrl}'}'</code2>`（伪 URL）

- `<code3>'{'{Transcript}'}'</code3>`（如果启用了音频转写）

Agent 的出站附件：在单独一行写 `<code1>MEDIA:<path-or-url>'</code1>`（无空格）。例如：

Terminal
这是截图。
MEDIA:https://example.com/screenshot.png

OpenClaw 会解析这些行，并把它们作为媒体与文本一起发送。

Tutorial.step

运维检查清单

Bash
openclaw status          # 本机状态（凭据、会话、队列事件）
openclaw status --all    # 完整诊断（只读，可直接粘贴分享）
openclaw status --deep   # 增加 gateway 健康探针（Telegram + Discord）
openclaw health --json   # gateway 健康快照（WS）

日志默认在 `/tmp/openclaw/`（文件名形如 `openclaw-YYYY-MM-DD.log`）。

Tutorial.step

下一步

- WebChat- Gateway 运行手册- Cron 任务- OpenClaw macOS 应用- iOS 应用- Android 应用- Windows（WSL2）- Linux 应用- 安全