openclaw/docs/zh-CN/start/openclaw.md

249 lines
8.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

---
read_when:
- 新手引导新的助手实例
- 审查安全/权限影响
summary: 将 OpenClaw 作为个人助手运行的端到端指南,包含安全注意事项
title: 个人助手设置
x-i18n:
generated_at: "2026-02-01T21:39:04Z"
model: claude-opus-4-5
provider: pi
source_hash: 2763668c053abe34ea72c40d1306d3d1143099c58b1e3ef91c2e5a20cb2769e0
source_path: start/openclaw.md
workflow: 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/预付费卡)
```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
```
## 双手机设置(推荐)
你需要的配置如下:
```
你的手机(个人) 第二部手机(助手)
┌─────────────────┐ ┌─────────────────┐
│ 你的 WhatsApp │ ──────▶ │ 助手 WA │
│ +1-555-YOU │ 消息 │ +1-555-ASSIST │
└─────────────────┘ └────────┬────────┘
│ 通过二维码关联
┌─────────────────┐
│ 你的 Mac │
│ (openclaw) │
│ Pi 智能体 │
└─────────────────┘
```
如果你将个人 WhatsApp 关联到 OpenClaw发给你的每条消息都会变成"智能体输入"。这通常不是你想要的。
## 5 分钟快速上手
1. 配对 WhatsApp Web显示二维码用助手手机扫描
```bash
openclaw channels login
```
2. 启动 Gateway网关保持运行
```bash
openclaw gateway --port 18789
```
3.`~/.openclaw/openclaw.json` 中放置一个最小配置:
```json5
{
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全新工作区会自动初始化。
```bash
openclaw setup
```
完整工作区布局 + 备份指南:[智能体工作区](/concepts/agent-workspace)
记忆工作流:[记忆](/concepts/memory)
可选:使用 `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 # 本地状态(凭证、会话、排队事件)
openclaw status --all # 完整诊断(只读,可粘贴)
openclaw status --deep # 添加 Gateway网关健康探测Telegram + Discord
openclaw health --json # Gateway网关健康快照WS
```
日志位于 `/tmp/openclaw/`(默认:`openclaw-YYYY-MM-DD.log`)。
## 后续步骤
- 网页聊天:[网页聊天](/web/webchat)
- Gateway网关运维[Gateway网关运维手册](/gateway)
- 定时任务 + 唤醒:[定时任务](/automation/cron-jobs)
- macOS 菜单栏伴侣应用:[OpenClaw macOS 应用](/platforms/macos)
- iOS 节点应用:[iOS 应用](/platforms/ios)
- Android 节点应用:[Android 应用](/platforms/android)
- Windows 状态:[Windows (WSL2)](/platforms/windows)
- Linux 状态:[Linux 应用](/platforms/linux)
- 安全:[安全](/gateway/security)