Files

Josh Palmer 5676a6b38d Docs: normalize zh-CN terminology + tone

What: switch to 你/你的 tone; standardize Skills/Gateway网关/local loopback/私信 wording
Why: align zh-CN docs with issue 6995 feedback + idiomatic tech style
Tests: pnpm docs:build

2026-02-02 16:38:25 +01:00

8.1 KiB

Raw Blame History

read_when, summary, title, x-i18n

read_when

summary

title

x-i18n

新手引导新的助手实例

审查安全/权限影响

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

个人助手设置

generated_at	model	provider	source_hash	source_path	workflow
2026-02-01T21:39:04Z	claude-opus-4-5	pi	2763668c053abe34ea72c40d1306d3d1143099c58b1e3ef91c2e5a20cb2769e0	start/openclaw.md	15

使用 OpenClaw 构建个人助手

OpenClaw 是一个面向 Pi 智能体的 WhatsApp + Telegram + Discord + iMessage Gateway网关。插件可添加 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
# or: pnpm add -g openclaw@latest

从源码安装（开发模式）：

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

双手机设置（推荐）

你需要的配置如下：

你的手机（个人）                第二部手机（助手）
┌─────────────────┐           ┌─────────────────┐
│  你的 WhatsApp  │  ──────▶  │  助手 WA        │
│  +1-555-YOU     │  消息     │  +1-555-ASSIST  │
└─────────────────┘           └────────┬────────┘
                                       │ 通过二维码关联
                                       ▼
                              ┌─────────────────┐
                              │  你的 Mac       │
                              │  (openclaw)      │
                              │    Pi 智能体    │
                              └─────────────────┘

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

5 分钟快速上手

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

openclaw channels login

启动 Gateway网关（保持运行）：

openclaw gateway --port 18789

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

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

现在从你的允许列表手机给助手号码发消息。

新手引导完成后，我们会自动打开带有 Gateway网关令牌的仪表盘并打印令牌化链接。以后重新打开：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,
    // 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 会抑制该次心跳的出站消息投递。
心跳运行完整的智能体回合——较短的间隔会消耗更多令牌。

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

媒体输入和输出

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

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

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

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

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

运维清单

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

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

后续步骤

网页聊天：网页聊天
Gateway网关运维：Gateway网关运维手册
定时任务 + 唤醒：定时任务
macOS 菜单栏伴侣应用：OpenClaw macOS 应用
iOS 节点应用：iOS 应用
Android 节点应用：Android 应用
Windows 状态：Windows (WSL2)
Linux 状态：Linux 应用
安全：安全

8.1 KiB Raw Blame History Unescape Escape