第六章智能体管理

这章教你调教龙虾——让它知道自己是谁、记住你的偏好、按你的规矩干活。

AutoClaw 用户：AutoClaw 已预配置好，开箱即用。本章帮助你按需进阶调整。

0. 什么是 Agent？

Agent（智能体）就是你的龙虾本身——有自己的性格（人设文件）、记忆（工作区文件）和能力（工具）。

默认情况下 OpenClaw 运行一个 Agent（id 为 main）。工作区就是龙虾的"家"，存放它的一切：

~/.openclaw/workspace/

Windows 用户：~/.openclaw/workspace 即 C:\Users\你的用户名\.openclaw\workspace。

1. 网关架构（Gateway）

Gateway（网关）是 OpenClaw 的后台服务，所有消息都经它统一处理后转发给 Agent。

常用命令：

bash

openclaw gateway status   # 查看状态
openclaw gateway restart  # 重启（修改 gateway.* 配置后需要）
openclaw status           # 查看整体运行状态

通过 CLI 修改配置后，大部分设置自动热更新生效。只有端口、认证、TLS 等基础设施字段需要手动重启（详见第八章）。

Gateway 架构详解（连接协议、节点系统）

OpenClaw Gateway 架构

mermaid

flowchart LR

A["飞书"]
B["QQ"]
C["Telegram"]
D["Web 面板"]
E["CLI"]

G["Gateway（网关）
统一消息入口"]

R["Agent 运行时"]

M["AI 模型"]

WS["WebSocket API"]

A --> G
B --> G
C --> G
D --> G
E --> G

G --> R
R --> M

G <---> WS

核心职责：

维护与各聊天平台的长连接
将消息路由给对应 Agent
为客户端提供 WebSocket API
执行 Cron 定时任务

连接协议：Gateway 使用 WebSocket，默认监听 127.0.0.1:18789（仅本机）。

请求：{type:"req", id, method, params} → 响应：{type:"res", id, ok, payload}
事件（服务器推送）：{type:"event", event, payload}

安全认证：

设置了 OPENCLAW_GATEWAY_TOKEN 后，连接时必须提供匹配的 token
新设备需要配对审批；本地连接自动批准，远程连接需显式审批

远程访问：推荐 Tailscale 或 VPN；备选 SSH 隧道：

bash

ssh -N -L 18789:127.0.0.1:18789 user@host

节点（Node）系统：物理设备（手机、平板）以 role: node 身份接入，可提供拍照（camera.*）、录屏（screen.record）、位置（location.get）、画布（canvas.*）等能力。

2. Agent 工作区

工作区（Workspace）是龙虾的"家"——它的身份、性格、记忆、技能全都存放在这里。

2.1 默认位置

~/.openclaw/workspace/

如果设置了 OPENCLAW_PROFILE（非 default），则默认位置变为 ~/.openclaw/workspace-<profile>。

2.2 工作区文件一览

文件	用途	加载时机
`AGENTS.md`	操作指令：告诉龙虾"怎么做事"和如何使用记忆	每次会话开始
`SOUL.md`	人设：性格、语气、边界	每次会话开始
`USER.md`	用户资料：你是谁、怎么称呼你	每次会话开始
`IDENTITY.md`	龙虾身份：名字、风格、表情符号	每次会话开始
`TOOLS.md`	工具使用备注（不控制工具开关，只是使用建议）	每次会话开始
`HEARTBEAT.md`	心跳任务清单（可选，保持简短）	心跳运行时
`BOOT.md`	启动清单（可选，Gateway 重启时执行）	Gateway 启动时
`BOOTSTRAP.md`	首次引导仪式（完成后删除）	仅首次运行
`MEMORY.md`	长期记忆（可选）	仅主会话
`memory/YYYY-MM-DD.md`	每日记忆日志	今天+昨天：会话开始；其余按需读取
`skills/`	工作区级技能（可选）	按需加载

重要：这些文件在每次对话时都会注入到 AI 模型的上下文窗口中，会消耗 Token。保持文件简洁，尤其是 MEMORY.md——它会随时间增长，导致上下文使用量增大和更频繁的压缩。

memory/YYYY-MM-DD.md 中今天和昨天的文件会在会话开始时自动读取，其余日期的文件通过 memory_search 和 memory_get 工具按需访问，不占用上下文窗口。

工作区文件注入规则

空文件会被跳过
大文件会被截断并标注 [truncated]
- 单文件上限：agents.defaults.bootstrapMaxChars（默认 20,000 字符）
- 所有文件总上限：agents.defaults.bootstrapTotalMaxChars（默认 150,000 字符）
缺失的文件会注入一行 "missing file" 标记
子 Agent 会话只注入 AGENTS.md 和 TOOLS.md（其他文件被过滤以保持子 Agent 上下文精简）
截断时可注入警告，通过 agents.defaults.bootstrapPromptTruncationWarning 控制（off / once / always，默认 once）

运行 /context list 或 /context detail 可以查看每个文件的原始大小 vs 注入大小、是否被截断。

工作区的安全边界

工作区是默认的工作目录（cwd），但不是硬沙盒。工具解析相对路径时会基于工作区，但绝对路径仍然可以访问主机上的其他位置。

如果你需要严格隔离，使用沙盒模式：

json

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "all",
        "scope": "agent"
      }
    }
  }
}

启用沙盒后，工具会在 ~/.openclaw/sandboxes 下的隔离目录中操作，而非主机工作区。

工作区 Git 备份（推荐）

建议将工作区放入私有 Git 仓库备份：

bash

# 初始化
cd ~/.openclaw/workspace
git init
git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/
git commit -m "Add agent workspace"

# 添加远程仓库（GitHub CLI）
gh repo create openclaw-workspace --private --source . --remote origin --push

# 日常更新
git add .
git commit -m "Update memory"
git push

不要提交：API 密钥、OAuth 令牌、~/.openclaw/ 下的任何内容。

建议的 .gitignore：

.DS_Store
.env
**/*.key
**/*.pem
**/secrets*

2.3 工作区文件配置指南

每个文件都是纯 Markdown，直接用文本编辑器编辑即可。9 个文件看起来不少，但它们各司其职，可以分为四组来理解：

分组	文件	一句话说明
身份三件套	IDENTITY.md / SOUL.md / USER.md	龙虾是谁、什么性格、服务谁
行为指南	AGENTS.md / TOOLS.md	怎么做事、怎么用工具
记忆系统	MEMORY.md	跨会话记住什么
生命周期	BOOTSTRAP.md / BOOT.md / HEARTBEAT.md	首次启动 → 每次重启 → 定期巡检

建议阅读顺序：先配好身份三件套（让龙虾认识你），再写 AGENTS.md（教它做事），其余按需添加。

如何编辑这些文件？

所有工作区文件都存放在 ~/.openclaw/workspace/ 目录下。由于 .openclaw 是隐藏目录（以 . 开头），不会在文件管理器中默认显示。推荐以下方式打开编辑：

方式一：用命令行直接打开（推荐，所有系统通用）

bash

# 用 VS Code 打开整个工作区目录
code ~/.openclaw/workspace/

# 或者打开单个文件
code ~/.openclaw/workspace/IDENTITY.md

没有 VS Code？用 nano（macOS/Linux）或 notepad（Windows）替代 code。

方式二：在文件管理器中导航

系统	工作区路径	如何显示隐藏文件
Windows	`C:\Users\你的用户名\.openclaw\workspace\`	文件资源管理器 → 查看 → 显示隐藏的项目
macOS	`/Users/你的用户名/.openclaw/workspace/`	Finder 中按 `Cmd + Shift + .`
Linux	`/home/你的用户名/.openclaw/workspace/`	文件管理器中按 `Ctrl + H`

提示：修改工作区文件后，需要发送 /new 开始新会话才能生效——因为这些文件是在会话开始时注入的。

身份三件套：让龙虾认识你和自己

这三个文件定义了"谁是谁"——龙虾的身份、性格和用户资料。它们在每次会话开始时自动加载，是龙虾"记忆"的起点。

IDENTITY.md —— 龙虾的身份证

定义龙虾的名字、风格和表情偏好。龙虾会按照这里的设定来介绍自己。

markdown

# 身份

- 名字：阿虾
- 称呼用户：老板
- 语言：中文为主，技术术语保留英文
- 表情符号：适度使用 🦞🔥✅❌
- 签名风格：回复末尾不加落款

📋 IDENTITY.md 配置模板参考（点击展开）

上面的简化示例只展示了基本字段。实际使用中，你可以根据场景定制得更丰富：

markdown

# 身份

- 名字：阿虾
- 物种：一只住在电脑里的龙虾 🦞
- 称呼用户：老板
- 气质：温暖但不啰嗦，偶尔毒舌
- 语言：中文为主，技术术语保留英文
- 表情符号：🦞（签名）、✅❌（判断）、🔥（重要）、💡（建议）
- 头像：avatars/lobster.png
- 签名风格：回复末尾不加落款，不用"祝好"之类的客套
- 自我介绍：当被问到"你是谁"时，回答"我是阿虾，你的私人助理"

每个字段的作用：

字段	影响	不写会怎样
名字	龙虾怎么称呼自己	默认用"我"
物种	自我认知的基调（严肃 or 有趣）	默认"AI 助手"
称呼用户	对你的称呼方式	默认用"你"
气质	整体回复风格	取决于 SOUL.md
语言	回复语言	跟随用户语言
表情符号	回复中使用的表情	不主动使用
头像	在聊天平台显示的头像	使用默认头像

安装后的初始模板是一份空白问卷，引导龙虾在首次对话中通过问答来填写。你也可以跳过引导，直接按上面的格式手动编辑。

SOUL.md —— 龙虾的性格

定义性格、语气和行为边界。这是龙虾"怎么说话"的指南。

markdown

# 人设

## 性格
- 专业但不刻板，偶尔幽默
- 遇到不确定的问题，诚实说"我不确定"而非编造答案
- 主动提供建议，但不越权执行

## 语气
- 日常对话：轻松简洁
- 技术讨论：严谨准确
- 出错时：坦诚道歉，给出修复方案

## 边界
- 不讨论政治、宗教等敏感话题
- 不执行未经确认的破坏性操作（删除文件、清空数据等）
- 涉及金钱交易时，必须二次确认

📋 SOUL.md 配置模板参考（点击展开）

上面的简化示例覆盖了基本维度。实际使用中，你可以按场景细化到更具体的行为指导：

markdown

# 人设

## 核心信条
- 真正有用，不要表演式有用——别说"好问题！"，直接帮忙
- 有自己的观点，可以不同意、可以有偏好
- 先自己想办法，搞不定再问——带着答案回来，不是带着问题
- 对外部操作（发邮件、发消息）谨慎，对内部操作（阅读、整理）大胆

## 性格
- 专业但不刻板，偶尔幽默
- 遇到不确定的问题，诚实说"我不确定"而非编造答案
- 主动提供建议，但不越权执行
- 犯错时坦诚道歉，直接给修复方案，不找借口

## 语气（按场景调整）
- 日常对话：轻松简洁，像朋友聊天
- 正式文档：严谨准确，用书面语
- 出错时：坦诚 + 方案，不啰嗦
- 催促时：不急不躁，先确认优先级

## 边界
- 隐私的事情就是隐私，没有例外
- 不讨论政治、宗教等敏感话题
- 不执行未经确认的破坏性操作（删除文件、清空数据等）
- 涉及金钱交易时，必须二次确认
- 绝不往聊天平台发半成品回复
- 在群聊中谨慎发言——你不是用户的代言人

## 延续性
- 每次会话你都是全新醒来的，工作区文件就是你的记忆
- 重要的事情写进文件，不要"心里记着"
- 如果你修改了这个文件，告诉用户——这是你的灵魂，他们应该知道

SOUL.md vs AGENTS.md 的区别：

维度	SOUL.md	AGENTS.md
管什么	"怎么说话"——性格、语气、边界	"怎么做事"——流程、规则、记忆
类比	一个人的性格	一个人的工作手册
修改频率	很少改——定型后基本不动	经常改——随工作流程调整

官方初始模板的核心理念是：做一个有个性、有能力、有边界的助手，而不是唯唯诺诺的聊天机器人。上面的参考配置将这一理念具体化为可操作的规则。

USER.md —— 用户档案

告诉龙虾"你是谁"，让它更好地理解你的需求。

markdown

# 用户信息

- 称呼：鲸哥
- 角色：产品经理
- 日常工作：写需求文档、竞品分析、数据报表
- 偏好：喜欢简洁清晰的表达，讨厌冗长废话
- 时区：Asia/Shanghai
- 工作语言：中文

📋 USER.md 配置模板参考（点击展开）

上面的简化示例只列了基础信息。实际使用中，写得越详细，龙虾就越能"懂你"：

markdown

# 用户信息

## 基本资料
- 称呼：鲸哥
- 角色：产品经理
- 公司/团队：XX 科技 产品部
- 时区：Asia/Shanghai
- 工作语言：中文
- 工作时间：周一至周五 9:00-18:00

## 日常工作
- 写需求文档、竞品分析、数据报表
- 经常需要整理会议纪要
- 每周给领导汇报项目进展

## 沟通偏好
- 喜欢简洁清晰的表达，讨厌冗长废话
- 回复消息时先说结论，再说原因
- 不需要"您好""祝好"之类的客套
- 提建议时直接给方案，不要只说问题

## 技能水平
- 熟练使用飞书、Excel、PPT
- 了解基本的数据分析（SQL 能看懂，写不太行）
- 对技术概念有基本理解，但不需要看代码

## 个人喜好
- 喜欢简约设计风格
- 喜欢用清单和表格整理信息
- 不喜欢被追问"你确定吗？"——说了就是确定了

写多少合适？ USER.md 会在每次会话开始时注入上下文，所以不宜过长。建议控制在 30 行以内，把变化频繁的细节（当前项目、最近任务）放到 MEMORY.md 中。

安装后的初始模板是一份空白问卷，龙虾会在引导仪式中通过对话帮你填写，之后在日常使用中持续补充。你也可以跳过引导，直接按上面的格式手动编辑。

行为指南：教龙虾怎么做事

身份确定了，接下来告诉龙虾"该怎么工作"。AGENTS.md 是核心操作手册，TOOLS.md 是工具使用的补充备注。

AGENTS.md —— 操作手册

这是最重要的文件——告诉龙虾"怎么做事"。所有行为规则、工作流程、记忆使用方式都写在这里。

markdown

# 操作指令

## 通用规则
- 收到任务后，先确认理解再执行
- 每完成一个步骤，主动汇报进度
- 遇到错误先尝试自行解决，解决不了再告知用户

## 记忆使用
- 用户说"记住这个"时，立即写入 memory/YYYY-MM-DD.md
- 重要的长期信息（偏好、项目规范）写入 MEMORY.md
- 每次会话结束前，主动总结关键决策写入记忆

📋 AGENTS.md 配置模板参考（点击展开）

上面的简化示例只展示了通用规则和记忆使用。实际的 AGENTS.md 应该覆盖更多维度——以下是一个完整的参考配置：

markdown

# 操作指令

## 会话启动
每次会话开始前，依次执行（不需要请示）：
1. 读取 `SOUL.md` —— 了解自己是谁
2. 读取 `USER.md` —— 了解服务对象
3. 读取 `memory/YYYY-MM-DD.md`（今天 + 昨天）获取近期上下文
4. **仅在主会话中**：读取 `MEMORY.md`

## 通用规则
- 收到任务后，先确认理解再执行
- 每完成一个步骤，主动汇报进度
- 遇到错误先尝试自行解决，解决不了再告知用户
- 回复要简洁，不需要"好的，我来帮你"之类的开场白

## 记忆
龙虾每次会话都是全新的，记忆文件是唯一的"前世今生"：
- **每日日志：** `memory/YYYY-MM-DD.md` —— 当天发生了什么
- **长期记忆：** `MEMORY.md` —— 精炼后的持久知识（仅主会话加载）

### 记忆规则
- 用户说"记住这个"时，立即写入 memory/YYYY-MM-DD.md
- 重要的长期信息写入 MEMORY.md
- 每次会话结束前，主动总结关键决策写入记忆
- 一定要写进文件——"心里记着"熬不过会话重启

### 安全设计
- MEMORY.md **不在群聊中加载**——防止个人上下文泄露给陌生人
- 这是刻意的隐私保护，不要手动在群聊中读取 MEMORY.md

## 红线
- 绝不外泄用户隐私数据
- 执行破坏性命令前必须确认
- `trash` 优于 `rm`（可恢复胜过彻底删除）
- 拿不准的事，先问再做

## 群聊礼仪
**该回复时：**
- 被直接 @ 或被提问
- 能提供有价值的信息、见解或帮助

**该沉默时（回复 HEARTBEAT_OK）：**
- 只是人类之间的闲聊
- 已经有人回答了问题
- 对话流畅，不需要你插嘴

人类法则：人在群聊里也不会每条消息都回。龙虾也不应该。

## 心跳 —— 主动巡检
**定期检查（轮流进行，每天 2-4 次）：**
- 邮件 —— 有没有紧急未读？
- 日历 —— 未来 24-48 小时有什么安排？
- 天气 —— 用户可能出门吗？

**该主动汇报时：** 收到重要邮件、日历事件即将到来（< 2 小时）
**该保持安静时：** 深夜时段（23:00-08:00）、上次检查后没有新消息

## 场景处理 —— 遇到特定需求怎么办

龙虾不是只会聊天，很多用户会提出操作性需求。
提前定义好处理流程，龙虾就能自主完成，不需要你手把手教。

### 日程与提醒类需求
当用户提出涉及日程、提醒的任务时：
1. 确认时间、地点、参与人等关键信息
2. 检查是否与现有日程冲突
3. 创建/修改日程后，汇报确认结果
4. 临近时间主动提醒

### 信息查询类需求
当用户提出"帮我查一下""看看有没有"类需求时：
1. 优先使用已有工具（搜索、API 调用）获取信息
2. 结果要结构化呈现（表格、列表），不要大段文字
3. 标注信息来源和时效性

### 文件与内容类需求
当用户提出涉及文件整理、文案撰写的任务时：
1. 确认具体要求（格式、风格、长度）
2. 先给出大纲或草稿，确认方向无误再完善
3. 完成后列出要点摘要，方便用户快速检查

> **按需扩展**：以上只是常见场景的示例。你可以根据自己的使用习惯，添加更多场景处理规则，比如"翻译类需求""购物比价类需求""旅行规划类需求"等。场景越具体，龙虾的执行越精准。进阶用户还可以添加"代码与 PR 类需求"等开发场景（详见[Vibe Coding 实战](/cn/university/vibe-coding/)）。

AGENTS.md 的七大模块及其作用：

模块	作用	不写会怎样
会话启动	定义每次对话前的准备动作	龙虾不会主动读取记忆文件
通用规则	控制任务执行的基本行为	龙虾按默认习惯行事，可能不符合你的预期
记忆	规定什么时候写记忆、写到哪里	龙虾不会主动记录，重要信息可能丢失
红线	设定不可逾越的安全边界	龙虾可能执行你不想要的操作
群聊礼仪	控制在群聊中的发言策略	龙虾可能对每条消息都回复，造成刷屏
心跳	定义主动巡检的内容和频率	龙虾不会主动检查邮件、日历等
场景处理	预定义特定需求的处理流程	龙虾遇到操作性需求时凭直觉行事，可能遗漏关键步骤

Heartbeat vs Cron 选择指南：

场景	推荐方式	原因
批量检查邮件+日历+通知	Heartbeat	多个检查合并在一次心跳中，减少 API 调用
每周一早 9 点发周报	Cron	需要精确时间触发
20 分钟后提醒我开会	Cron（`--at`）	一次性定时任务
定期清理旧记忆文件	Heartbeat	时间不敏感，可顺带完成

AGENTS.md 是工作区中最重要也最长的文件。建议从上面的参考配置开始，用一段时间后根据实际体验逐步调整。记住：这只是起点，加入你自己的风格和规则。

TOOLS.md —— 工具使用备注

给龙虾补充工具使用的注意事项（不控制工具开关，只是建议）。

markdown

# 工具使用备注

## exec（命令执行）
- 执行破坏性命令前必须确认（删除文件、清空目录等）
- 长时间运行的命令加 timeout

## browser（浏览器）
- 优先使用搜索工具而非浏览器访问
- 访问需要登录的网站时，提前告知用户

## write / edit（文件操作）
- 修改重要文件前先备份
- 批量修改前先展示变更内容让用户确认

📋 TOOLS.md 配置模板参考（点击展开）

上面的简化示例按工具类型组织。实际使用中，你还可以加入环境专属信息——龙虾用工具时就会参考这些备忘：

markdown

# 工具使用备注

## exec（命令执行）
- 执行破坏性命令前必须确认（删除文件、清空目录等）
- 长时间运行的命令加 timeout
- `trash` 优于 `rm`（可恢复胜过彻底删除）

## browser（浏览器）
- 优先使用搜索工具而非浏览器访问
- 访问需要登录的网站时，提前告知用户
- 不要自动点击"同意 Cookie"之类的弹窗

## write / edit（文件操作）
- 修改重要文件前先备份
- 批量修改前先展示变更内容让用户确认
- 文件名用中文或拼音，不要用纯英文

## 我的环境信息
- 智能音箱：客厅小爱同学、卧室天猫精灵
- 打印机：书房 HP LaserJet（Wi-Fi 直连，IP 192.168.1.50）
- NAS：群晖 DS220+（IP 192.168.1.100，用户名 admin）
- 常用网站：飞书（feishu.cn）、语雀（yuque.com）

TOOLS.md vs CLI 配置的区别：

维度	TOOLS.md	CLI 配置（`openclaw config set`）
控制什么	使用建议和环境备忘	工具的开关和权限
谁读	龙虾（AI 模型）	Gateway（程序）
效果	软性引导，龙虾"尽量"遵守	硬性限制，不给就用不了
例子	"删除前先确认"	`openclaw config set tools.profile full`

TOOLS.md 是龙虾的"速查小抄"——技能定义了工具怎么用，这个文件记录你的环境怎么配。两者分开存放，更新技能不会丢失你的备忘，分享技能也不会泄露你的环境信息。

记忆系统：让龙虾记住重要的事

AGENTS.md 里提到了"记忆使用"规则，而 MEMORY.md 就是龙虾的长期记忆载体——跨会话保存的持久信息。

MEMORY.md —— 长期记忆（可选）

存放跨会话的持久信息。龙虾每次会话都会读取这个文件，所以保持精简。

markdown

# 长期记忆

## 日常事务
- 每周一上午有团队周会，需要提前准备议题
- 每月 25 号提交月度报表给领导

## 偏好
- 邮件回复尽量简短，不超过三段
- 文档用中文写，关键术语保留英文
- 不喜欢冗长的开场白，直奔主题

## 重要决策
- 2026-03-10：决定用飞书作为主要沟通渠道，微信仅用于非工作场景

⚠️ MEMORY.md 会随时间增长。定期清理过时内容，或将细节移入 memory/ 目录的日志文件中。

📋 MEMORY.md 配置模板参考（点击展开）

OpenClaw 安装后不会自动生成 MEMORY.md，需要你自己创建（或让龙虾在对话中帮你写入）。以下是一个完整的模板参考：

markdown

# 长期记忆

> 这个文件每次会话都会加载，请保持精简。细节放到 memory/ 目录的日志文件中。

## 关于我
- 称呼：鲸哥
- 习惯：早起型，通常 7 点前在线
- 沟通风格：喜欢直奔主题，不需要寒暄

## 日常事务
- 每周一上午 9:30 团队周会，需要提前准备议题
- 每月 25 号提交月度报表给领导
- 每周五下午整理下周计划

## 重要联系人
- 李总：直属领导，喜欢看数据说话
- 小王：设计同事，配合最多
- 张姐：财务，报销找她

## 偏好与习惯
- 邮件回复尽量简短，不超过三段
- 文档用中文写，关键术语保留英文
- 不喜欢冗长的开场白，直奔主题
- 讨厌被问"你确定吗？"——说了就是确定了

## 常用工具与账号
- 主要沟通：飞书（工作）、微信（私人）
- 文档协作：飞书文档
- 项目管理：飞书多维表格
- 日历：飞书日历（以飞书日历为准）

## 重要决策记录
- 2026-03-10：决定用飞书作为主要沟通渠道，微信仅用于非工作场景
- 2026-03-05：月度报表改用新模板，数据来源切换到新系统

## 注意事项
- 周三下午尽量不安排会议（留给专注工作）
- 给领导的文件必须检查错别字
- 涉及预算的事必须邮件确认，不接受口头承诺

这个模板比上面的简化示例更完整，涵盖了个人信息、日常事务、联系人、偏好、工具、决策记录等方面。你不需要一次性填满所有内容——可以先写最重要的几条，让龙虾在日常对话中逐步补充。记住：MEMORY.md 仅在主会话加载，群聊中不会泄露这些内容。

生命周期：从出生到日常巡检

最后三个文件控制龙虾在不同阶段的行为——首次启动时做什么、每次重启时做什么、日常定期做什么。按时间线排列：

BOOTSTRAP.md（首次启动，完成后删除）
    → BOOT.md（每次 Gateway 重启时执行）
        → HEARTBEAT.md（运行期间定期执行）

BOOTSTRAP.md —— 首次引导仪式（一次性）

首次运行时的引导脚本——龙虾通过一次轻松对话认识你和自己。完成后会自动删除。

markdown

# 引导仪式

1. 你叫什么名字？
2. 你是什么"物种"？
3. 你的风格是什么？
4. 用户怎么称呼？

📋 BOOTSTRAP.md 配置模板参考（点击展开）

上面的简化示例只列了四个问题。实际的引导仪式可以设计得更丰富，让龙虾的"出生体验"更完整：

markdown

# 引导仪式

## 第一步：认识自己
通过对话确认以下信息，写入 IDENTITY.md：
1. 你叫什么名字？（比如：阿虾、Lobster、小龙）
2. 你是什么"物种"？（AI 助手？电子龙虾？数字精灵？）
3. 你的气质是什么？（温暖？犀利？幽默？沉稳？）
4. 选一个专属表情符号（比如 🦞）

## 第二步：认识主人
通过对话确认以下信息，写入 USER.md：
1. 怎么称呼你？（名字或昵称）
2. 你的时区是？
3. 你平时做什么工作？
4. 你喜欢什么样的沟通方式？（简洁 or 详细？正式 or 随意？）

## 第三步：定性格
打开 SOUL.md，一起聊聊：
- 什么话题不该碰？（政治？宗教？其他？）
- 什么操作必须先问？（删除文件？发送消息？花钱？）
- 出错了怎么处理？（直接道歉还是解释原因？）

## 第四步：连接渠道（可选）
问问用户想怎么联系你：
- 仅网页聊天
- 飞书 / QQ / Telegram / WhatsApp
引导用户完成渠道配置（详见第四章）。

## 完成后
- 确认 IDENTITY.md、USER.md、SOUL.md 都已写入
- 删除这个文件——你不再需要引导脚本了

引导仪式的设计原则：

原则	说明
对话式，不是问卷式	像朋友聊天，不像填表格
龙虾主导	龙虾主动提问和建议，用户只需回答
允许跳过	用户不想回答的问题可以跳过，以后再补
写入文件	每个环节的结果立即写入对应的 .md 文件
一次性	完成后自动删除 BOOTSTRAP.md，确保只运行一次

如果你不想走引导仪式，运行 openclaw config set agent.skipBootstrap true，然后直接手动编辑 IDENTITY.md、USER.md 和 SOUL.md 即可。

BOOT.md —— 启动任务（可选）

Gateway 重启时自动执行的一次性任务。适合做环境检查。

markdown

# 启动任务

Gateway 重启时自动执行以下检查（每次启动只执行一次）。

## 环境检查
- 确认网络连接正常
- 检查工作区文件完整性（AGENTS.md、SOUL.md、USER.md 是否存在）

## 问候
- 如果在工作时间（08:00-22:00），给用户发一条简短的上线通知

📋 BOOT.md 配置模板参考（点击展开）

OpenClaw 安装后不会自动生成 BOOT.md，需要你自己创建。以下是一个实用的模板参考：

markdown

# 启动任务

Gateway 重启时自动执行以下检查（每次启动只执行一次）。

## 环境检查
- 确认网络连接正常
- 检查工作区文件完整性（AGENTS.md、SOUL.md、USER.md 是否存在）
- 检查 memory/ 目录是否可读写

## 状态恢复
- 读取昨天的记忆日志，了解最近上下文
- 如果有未完成的任务，列出待办清单

## 问候
- 如果在工作时间（08:00-22:00），给用户发一条简短的上线通知
- 如果不在工作时间，保持安静

BOOT.md 适合放"每次启动都要做一遍"的事情，比如环境自检和状态恢复。与 HEARTBEAT.md（定期重复执行）和 BOOTSTRAP.md（仅首次执行）不同，BOOT.md 在每次 Gateway 重启时执行一次。保持简短，避免启动时消耗过多 Token。

HEARTBEAT.md —— 心跳任务（可选）

心跳是龙虾的"定期自检"——每隔一段时间自动执行的轻量任务。保持简短，避免消耗过多 Token。

markdown

# 心跳任务

- 检查 memory/ 目录，清理超过 30 天的日志
- 如果今天还没写日记，提醒用户

心跳间隔通过 openclaw config set agents.defaults.heartbeat.every "30m" 配置，不在这里设置。

📋 HEARTBEAT.md 配置模板参考（点击展开）

上面的简化示例只列了两个任务。实际使用中，你可以根据龙虾接入的工具和服务来定制巡检清单：

markdown

# 心跳任务

## 信息检查（轮流进行，每天 2-4 次）
- 邮件 —— 有没有紧急未读？摘要汇报
- 日历 —— 未来 24-48 小时有什么安排？提前提醒
- 天气 —— 明天需要带伞吗？有极端天气吗？

## 主动汇报规则
- 收到重要邮件 → 立即通知
- 日历事件 < 2 小时 → 提醒
- 天气预警 → 当天第一次心跳时通知

## 静默规则
- 深夜时段（23:00-08:00）不打扰，除非紧急
- 上次检查后没有新消息 → 不汇报
- 周末减少频率，只检查邮件

## 维护任务
- 检查 memory/ 目录，清理超过 30 天的日志
- 如果今天还没写日记，提醒用户
- 检查 MEMORY.md 大小，超过 200 行时建议精简

心跳的成本意识： 每次心跳都会消耗 Token（调用 AI 模型执行任务清单）。任务越多，消耗越大。建议：

心跳频率	适用场景	每日大约消耗
每 6 小时	轻度使用，只检查邮件	较低
每 3 小时	日常使用，邮件 + 日历	中等
每 1 小时	重度使用，多项检查	较高

安装后的初始模板是空的——留空就不会触发心跳 API 调用，不消耗任何 Token。等你确定了需要定期检查的事项，再按上面的格式添加任务。心跳间隔通过 CLI 配置：openclaw config set agents.defaults.heartbeat.every "30m"。

2.4 哪些不在工作区

以下内容存储在 ~/.openclaw/ 下，不在工作区中：

路径	内容
`~/.openclaw/` 配置文件	全局配置（详见附录 G）
`~/.openclaw/credentials/`	OAuth 令牌、API 密钥
`~/.openclaw/agents/<id>/sessions/`	会话记录
`~/.openclaw/skills/`	共享级技能

如果你需要迁移到新机器，配置和会话需要单独复制。

3. 首次启动：引导仪式

首次运行 Agent 时，OpenClaw 会执行一个引导仪式（Bootstrapping）——一个简短的问答过程，帮助龙虾了解"它是谁"和"你是谁"。

引导过程

在工作区中创建 AGENTS.md、BOOTSTRAP.md、IDENTITY.md、USER.md
运行一轮简短的问答（每次一个问题）
将你的回答写入 IDENTITY.md、USER.md、SOUL.md
完成后自动删除 BOOTSTRAP.md（确保只运行一次）

引导仪式始终在 Gateway 所在的机器上执行。 如果你通过 macOS App 连接远程 Gateway，工作区和引导文件都在远程机器上。

如果你已经自行管理工作区文件（比如从另一台机器迁移过来），可以跳过引导：

bash

openclaw config set agent.skipBootstrap true

也可以随时运行 openclaw setup 重建缺失的默认文件（不会覆盖已有文件）。

4. Agent 循环与上下文

发送消息后，龙虾会依次：路由 → 排队 → 组装上下文 → 调用 AI 模型 → 执行工具 → 回复。

同一会话内的消息串行处理（不并行），不同会话之间完全并行。发送 /stop 可随时中止。

查看上下文使用情况：

命令	作用
`/status`	快速查看上下文使用率
`/context list`	查看注入的文件列表
`/context detail`	详细分解每个文件/工具的 Token 占用
`/usage tokens`	每次回复后追加 Token 用量

上下文 ≠ 记忆。上下文是模型当前窗口内容；记忆存在磁盘上，跨会话加载。

Agent 循环详解（运行步骤、系统提示词、钩子系统）

Agent 循环流程

你的消息
  → 路由（找到对应的 Agent 和会话）
  → 排队（如果正在处理另一条消息）
  → Agent 运行
      → 组装上下文（系统提示词 + 历史消息 + 工具列表）
      → 发送给 AI 模型
      → 模型思考并决定下一步
      → 执行工具调用（搜索、读写文件等）
      → 流式输出回复
  → 回复发送到聊天平台

不同会话（比如不同群聊）之间是并行的，通过 agents.defaults.maxConcurrent（默认 4）控制最大并行数。Agent 运行超时默认 48 小时，足以支持长时间运行的 ACP 会话。

系统提示词构成

每次 Agent 运行时，OpenClaw 构建一个系统提示词，包含：

部分	内容
工具列表	当前可用工具 + 简短描述
安全守则	避免越权行为的提醒（建议性，非硬限制）
技能列表	可用技能的名称、描述和路径
工作区	工作目录路径
日期时间	用户时区
引导文件	AGENTS.md、SOUL.md 等文件内容

真正的硬限制来自工具策略、exec 审批、沙盒和渠道白名单。

上下文的两大隐形成本：技能列表（每条技能占用提示词空间）和工具 Schema（JSON 格式，不可见但占用 Token，如 browser 工具约 2,500 Token）。

提示词模式由运行时自动设置：full（默认）/ minimal（子 Agent）/ none（最小化）。

钩子系统（Hooks）

内部钩子（Gateway Hooks）：

agent:bootstrap：引导文件构建前，可修改/替换引导上下文
命令钩子：/new、/reset、/stop 等命令事件

插件钩子：

before_model_resolve：在模型解析前覆盖 provider/model
before_prompt_build：在提交前注入额外上下文或系统提示
agent_end：运行完成后检查消息列表和元数据
before_tool_call / after_tool_call：拦截工具参数/结果
message_received / message_sending / message_sent：消息生命周期
session_start / session_end：会话边界
gateway_start / gateway_stop：网关生命周期

配置时区：agents.defaults.userTimezone，时间格式：agents.defaults.timeFormat（auto / 12 / 24）。

5. 会话管理

会话（Session）是龙虾与你（或一个群聊）之间的对话记录。每个群独立会话，私聊默认共享一个。

修改工作区文件后，发送 /new 开始新会话才能生效。/new Opus 还可以同时切换模型。

多人场景下的隐私隔离

安全警告：默认所有私聊共享同一会话。如果多个人都能私聊你的龙虾，Alice 的内容可能被 Bob 看到。

多人使用时，用 CLI 设置会话隔离：

bash

openclaw config set session.dmScope per-channel-peer

模式	适用场景
`main`（默认）	只有你一个人使用
`per-channel-peer`	推荐——多人使用

运行 openclaw security audit 可以检查你的 DM 安全设置。

会话管理进阶（生命周期、存储维护、跨会话通信、身份关联）

会话生命周期

默认每天凌晨 4:00 自动重置（Gateway 所在机器本地时间）：

json

{
  "session": {
    "reset": {
      "mode": "daily",
      "atHour": 4,
      "idleMinutes": 120
    }
  }
}

按类型/渠道自定义重置策略：

json

{
  "session": {
    "resetByType": {
      "direct": { "mode": "idle", "idleMinutes": 240 },
      "group": { "mode": "idle", "idleMinutes": 120 },
      "thread": { "mode": "daily", "atHour": 4 }
    },
    "resetByChannel": {
      "discord": { "mode": "idle", "idleMinutes": 10080 }
    }
  }
}

resetByChannel 优先级高于 reset / resetByType。

会话存储与维护

会话记录存储为 JSONL 文件：~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl

配置项	默认值	说明
`session.maintenance.mode`	`warn`	`warn` 仅报告，`enforce` 自动清理
`session.maintenance.pruneAfter`	`30d`	清理超过 30 天的旧会话
`session.maintenance.maxEntries`	`500`	最多保留 500 个会话条目
`session.maintenance.rotateBytes`	`10mb`	sessions.json 超过此大小时轮转

bash

openclaw sessions cleanup --dry-run   # 预览清理效果
openclaw sessions cleanup --enforce   # 执行清理

大规模部署示例：

json

{
  "session": {
    "maintenance": {
      "mode": "enforce",
      "pruneAfter": "14d",
      "maxEntries": 2000,
      "rotateBytes": "25mb",
      "maxDiskBytes": "2gb",
      "highWaterBytes": "1.6gb"
    }
  }
}

会话键格式

来源	会话键格式
私聊（默认）	`agent:main:main`
群聊	`agent:main:<channel>:group:<id>`
Cron 任务	`cron:<job.id>`
子 Agent	`agent:main:subagent:<uuid>`

身份关联（identityLinks）

同一个人在多个平台联系龙虾时，可以合并为同一会话：

json

{
  "session": {
    "dmScope": "per-channel-peer",
    "identityLinks": {
      "alice": ["telegram:123456789", "discord:987654321012345678"]
    }
  }
}

跨会话通信工具

工具	功能
`sessions_list`	列出所有会话
`sessions_history`	获取某个会话的对话记录
`sessions_send`	向另一个会话发送消息（支持等待回复）
`sessions_spawn`	派生子 Agent 执行隔离任务

sessions_send：timeoutSeconds = 0 异步发出；timeoutSeconds > 0 等待回复；超时返回 timeout。发送后触发乒乓循环，最多 maxPingPongTurns（默认 5）轮，回复 REPLY_SKIP 终止。

sessions_spawn 派生子 Agent 参数：task（必填）、label、model、thinking、runTimeoutSeconds、thread、cleanup（delete/keep）、sandbox（inherit/require）、attachments。子 Agent 不含会话工具，不允许嵌套派生，完成后默认 60 分钟后自动归档。

6. 记忆系统

OpenClaw 的记忆是纯 Markdown 文件——文件就是唯一真相来源，模型只"记住"被写到磁盘上的内容。

文件	用途
`MEMORY.md`	精选长期记忆（每次会话加载）
`memory/YYYY-MM-DD.md`	每日日志（按需读取，不占上下文）

写记忆的原则：说了"记住这个"，龙虾必须立即写入文件——"脑子里记着"熬不过会话重启。

搜索工具：memory_search（语义搜索）和 memory_get（读取指定文件）。

记忆系统进阶（向量搜索、混合搜索、时间衰减、QMD 后端）

自动记忆刷新

会话接近压缩上限时，OpenClaw 自动触发静默记忆刷新，提醒模型将重要信息写入磁盘：

json

{
  "agents": {
    "defaults": {
      "compaction": {
        "memoryFlush": {
          "enabled": true,
          "softThresholdTokens": 4000
        }
      }
    }
  }
}

向量记忆搜索

默认启用，自动监控记忆文件变化，通过语义相似度搜索（即使措辞不同也能匹配）。

嵌入提供商自动检测顺序：本地模型 → OpenAI → Gemini → Voyage/Mistral → Ollama。

配置示例（使用 Gemini 嵌入）：

json

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "provider": "gemini",
        "model": "gemini-embedding-001",
        "remote": {
          "apiKey": "你的 Gemini API Key"
        }
      }
    }
  }
}

混合搜索（BM25 + 向量）

结合语义匹配和关键词匹配（精确 ID、代码符号、错误信息）：

json

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "query": {
          "hybrid": {
            "enabled": true,
            "vectorWeight": 0.7,
            "textWeight": 0.3
          }
        }
      }
    }
  }
}

MMR 去重（减少重复结果，lambda：0=最大多样性，1=最大相关性，默认 0.7）：

json

{ "hybrid": { "mmr": { "enabled": true, "lambda": 0.7 } } }

时间衰减（优先近期记忆，半衰期 30 天：今天 100%、30 天前 50%、90 天前 12.5%）：

json

{ "hybrid": { "temporalDecay": { "enabled": true, "halfLifeDays": 30 } } }

MEMORY.md 和非日期命名文件不受衰减影响。

额外记忆路径：

json

{ "memorySearch": { "extraPaths": ["../team-docs", "/srv/shared-notes/overview.md"] } }

QMD 后端（实验性）

本地优先搜索引擎，结合 BM25 + 向量 + 重排序，失败时自动回退到内置 SQLite：

json

{ "memory": { "backend": "qmd" } }

前提：bun install -g https://github.com/tobi/qmd，macOS 需 brew install sqlite，Windows 建议 WSL2。

7. 上下文压缩与会话修剪

对话越来越长时，OpenClaw 会自动压缩旧对话（总结成摘要），保持上下文窗口可用。

手动压缩：/compact Focus on decisions and open questions（可附带指令引导重点）。

压缩与修剪详细配置

上下文压缩（Compaction）

自动压缩默认开启。/status 可查看压缩次数。

压缩后结构：压缩摘要 + 最近消息 + 当前提问

配置（可指定不同模型做压缩总结）：

json

{
  "agents": {
    "defaults": {
      "compaction": {
        "model": "openrouter/anthropic/claude-sonnet-4-5",
        "identifierPolicy": "strict"
      }
    }
  }
}

identifierPolicy：strict（默认，保留标识符）/ off / custom

压缩可靠性保障：

大型会话压缩时自动延长运行截止时间，避免压缩到一半被超时中断
压缩后自动修复孤立的 tool_result 块，防止残余数据导致后续请求报错
空会话不会触发无意义的压缩循环

会话修剪（Session Pruning）

修剪只临时裁剪发送给模型的内容，不修改磁盘记录。

对比	压缩	修剪
作用	总结旧对话	裁剪旧工具结果
持久化	写入 JSONL	仅内存中
触发	接近上下文上限	每次 LLM 调用前

修剪默认关闭。启用（cache-ttl 模式）：

json

{
  "agents": {
    "defaults": {
      "contextPruning": {
        "mode": "cache-ttl",
        "ttl": "5m"
      }
    }
  }
}

修剪规则：只修剪 toolResult 消息；保护最近 3 条助手消息后的工具结果；含图片的不修剪；软裁剪（保留头尾加 ...）或硬清除（替换为 [Old tool result content cleared]）。

默认参数：ttl 5 分钟，keepLastAssistants 3，softTrimRatio 0.3，hardClearRatio 0.5，minPrunableToolChars 50,000。

8. 多 Agent 路由

需要多 Agent 的场景：多人使用（各有独立记忆）、多场景（日常用快速模型/深度工作用 Opus）、多渠道分离、安全隔离（限制公开群组权限）。

bash

openclaw agents add work             # 创建新 Agent
openclaw agents list --bindings      # 查看所有 Agent 和路由绑定

每个 Agent 获得独立工作区（~/.openclaw/workspace-<id>）和会话存储。

路由绑定配置：

json

{
  "agents": {
    "list": [
      { "id": "chat", "name": "Everyday", "workspace": "~/.openclaw/workspace-chat" },
      { "id": "opus", "name": "Deep Work", "workspace": "~/.openclaw/workspace-opus" }
    ]
  },
  "bindings": [
    { "agentId": "chat", "match": { "channel": "whatsapp" } },
    { "agentId": "opus", "match": { "channel": "telegram" } }
  ]
}

路由进阶（优先级规则、按联系人分流、家庭群限权、多账号、独立沙盒）

路由优先级（最具体先匹配）

peer（精确私聊/群聊 ID）
parentPeer（线程继承）
guildId + roles（Discord 角色路由）
guildId / teamId
accountId（渠道账号）
channel（渠道级匹配）
回退到默认 Agent

同一优先级有多个匹配时，配置中靠前的先生效。

同一渠道按联系人分流

json

{
  "bindings": [
    {
      "agentId": "opus",
      "match": { "channel": "whatsapp", "peer": { "kind": "direct", "id": "+15551234567" } }
    },
    { "agentId": "chat", "match": { "channel": "whatsapp" } }
  ]
}

为家庭群创建专用 Agent（限制权限）

json

{
  "agents": {
    "list": [
      {
        "id": "family",
        "name": "Family Bot",
        "workspace": "~/.openclaw/workspace-family",
        "tools": {
          "allow": ["exec", "read", "sessions_list", "sessions_history"],
          "deny": ["write", "edit", "browser", "canvas", "cron"]
        }
      }
    ]
  },
  "bindings": [
    {
      "agentId": "family",
      "match": { "channel": "whatsapp", "peer": { "kind": "group", "id": "120363999999999999@g.us" } }
    }
  ]
}

多渠道账号

Discord 多机器人：

json

{
  "bindings": [
    { "agentId": "main", "match": { "channel": "discord", "accountId": "default" } },
    { "agentId": "coding", "match": { "channel": "discord", "accountId": "coding" } }
  ],
  "channels": {
    "discord": {
      "accounts": {
        "default": { "token": "DISCORD_BOT_TOKEN_MAIN" },
        "coding": { "token": "DISCORD_BOT_TOKEN_CODING" }
      }
    }
  }
}

WhatsApp 多号码：

bash

openclaw channels login --channel whatsapp --account personal
openclaw channels login --channel whatsapp --account biz

每个 Agent 独立沙盒和工具权限

json

{
  "agents": {
    "list": [
      { "id": "personal", "sandbox": { "mode": "off" } },
      {
        "id": "family",
        "sandbox": { "mode": "all", "scope": "agent", "docker": { "setupCommand": "apt-get update && apt-get install -y git curl" } },
        "tools": { "allow": ["read"], "deny": ["exec", "write", "edit"] }
      }
    ]
  }
}

注意：tools.elevated 是全局的（基于发送者），不能按 Agent 配置。

9. 消息投递与流式输出

快速连续发送多条消息时，OpenClaw 自动合并（防抖）为一次调用。龙虾正在处理时，新消息进入队列。

发送 /queue <mode> 可临时切换排队模式。块流默认关闭，开启后龙虾会逐段发送而非等全部完成。

消息投递进阶（防抖、排队模式、流式输出、重试策略）

入站防抖

json

{
  "messages": {
    "inbound": {
      "debounceMs": 2000,
      "byChannel": { "whatsapp": 5000, "slack": 1500 }
    }
  }
}

媒体/附件消息立即处理，不参与防抖。控制命令（如 /stop）绕过防抖。

消息排队模式

模式	行为
`collect`（默认）	收集所有排队消息，合并为一次后续处理
`steer`	注入当前运行（取消后续工具调用，插入新消息）
`followup`	当前运行结束后开始新一轮
`steer-backlog`	注入当前运行 + 保留消息供后续处理
`interrupt`	中止当前运行，处理最新消息

json

{
  "messages": {
    "queue": {
      "mode": "collect",
      "debounceMs": 1000,
      "cap": 20,
      "drop": "summarize",
      "byChannel": { "discord": "collect", "telegram": "steer" }
    }
  }
}

drop 溢出策略：old（丢最旧）/ new（丢最新）/ summarize（默认，保留摘要）。

组合命令：/queue collect debounce:2s cap:25 drop:summarize

块流（Block Streaming）

json

{
  "agents": {
    "defaults": {
      "blockStreamingDefault": "on",
      "blockStreamingBreak": "text_end"
    }
  }
}

非 Telegram 渠道还需在渠道配置中设置 *.blockStreaming: true。

分块算法：低水位（minChars）缓冲、高水位（maxChars）强制分割。分割优先级：段落 → 换行 → 句子 → 空格 → 硬分割。代码块不在围栏内分割。

合并（减少碎片感）：blockStreamingCoalesce: { idleMs: 500, minChars: 200, maxChars: 2000 }

仿人类节奏：humanDelay: { mode: "natural" }（块间随机延迟 800–2500ms）

预览流模式

配置 channels.<channel>.streaming：off / partial（单条持续更新）/ block（分块追加）/ progress（进度状态）。

重试策略

Telegram：429/超时/连接错误，最小 400ms，最大 30s，3 次。Discord：仅 429，最小 500ms，最大 30s，3 次。Markdown 解析错误不重试，回退为纯文本。

自定义：channels.telegram.retry: { attempts, minDelayMs, maxDelayMs, jitter }

10. 认证与 OAuth

认证信息按 Agent 隔离存储：~/.openclaw/agents/<agentId>/agent/auth-profiles.json

不要在不同 Agent 之间共享 agentDir——会导致认证和会话冲突。

认证进阶（多账号 Profile、OAuth 流程、Failover）

认证方式

方式	说明
API Key	最常见，推荐生产用法
OpenAI Codex OAuth	ChatGPT 账号登录（OpenAI 明确支持）
Anthropic setup-token	Claude 订阅登录（有政策风险，请自行确认）
插件自定义	特殊提供商的 OAuth/API Key 流程

多账号配置（Auth Profiles）

auth-profiles.json 支持同一提供商的多个配置。

全局选择：通过 auth.order 排序
会话级选择：/model Opus@anthropic:work
Failover：某 Profile 失败时自动切换到下一个（带冷却时间）

两种多账号模式：

独立 Agent（推荐）：openclaw agents add work && openclaw agents add personal
同一 Agent 多 Profile：/model Opus@anthropic:work

OpenAI Codex OAuth 流程

生成 PKCE 验证器/挑战 + 随机状态
打开 https://auth.openai.com/oauth/authorize?...
在 http://127.0.0.1:1455/auth/callback 捕获回调（远程/headless 时手动粘贴重定向 URL）
交换令牌并存储 { access, refresh, expires, accountId }

令牌到期后自动刷新，通常无需手动管理。

Anthropic setup-token

bash

claude setup-token                                        # 先在任意机器上运行
openclaw models auth setup-token --provider anthropic     # 粘贴到 OpenClaw
openclaw models status                                    # 验证

⚠️ Anthropic 曾限制部分用户在 Claude Code 之外使用订阅认证，请自行确认当前政策。

11. 在线状态与其他

在线状态（Presence）：轻量级"谁在线"视图，主要供 macOS App 实例标签页使用。Gateway 启动、WebSocket 客户端连接、节点接入时自动注册。5 分钟无更新自动清除，最多保留 200 条。

12. 常见问题

Q: 工作区文件改了但龙虾没反应？

A: 工作区文件在每次会话开始时注入。如果在会话进行中修改了 AGENTS.md 等文件，需要发送 /new 开始新会话才能生效。

Q: 上下文窗口快满了怎么办？

A: 发送 /compact 手动压缩旧对话。或者检查 /context detail 找到占用最多空间的文件/工具，精简不需要的内容。

Q: 多 Agent 怎么查看路由情况？

A: 运行 openclaw agents list --bindings 查看所有 Agent 和它们的路由绑定。

Q: 记忆搜索不工作？

A: 检查是否配置了嵌入提供商的 API Key。运行 openclaw status --deep 查看记忆搜索状态。如果没有 API Key，也没有本地模型，记忆搜索会保持关闭。

Q: 消息发送失败或延迟？

A: 检查 Gateway 状态（openclaw status）和日志（openclaw logs --limit 50）。可能是 API 限流——查看重试策略配置。

Q: 如何保护多人场景下的隐私？

A: 设置 session.dmScope 为 per-channel-peer 隔离每个人的会话。运行 openclaw security audit 检查安全配置。

Q: 对话中途想问个题外话，又不想打断当前上下文？

A: 使用 /btw 命令。在对话中随时发送 /btw 你的问题，Agent 会快速回答但不影响当前会话的上下文——就像开会时侧过身低声问一句题外话，问完继续开会。

第六章 智能体管理 ​

0. 什么是 Agent？ ​

1. 网关架构（Gateway） ​

2. Agent 工作区 ​

2.1 默认位置 ​

2.2 工作区文件一览 ​

2.3 工作区文件配置指南 ​

如何编辑这些文件？ ​

IDENTITY.md —— 龙虾的身份证 ​

SOUL.md —— 龙虾的性格 ​

USER.md —— 用户档案 ​

AGENTS.md —— 操作手册 ​

TOOLS.md —— 工具使用备注 ​

MEMORY.md —— 长期记忆（可选） ​

BOOTSTRAP.md —— 首次引导仪式（一次性） ​

BOOT.md —— 启动任务（可选） ​

HEARTBEAT.md —— 心跳任务（可选） ​

2.4 哪些不在工作区 ​

3. 首次启动：引导仪式 ​

引导过程 ​

4. Agent 循环与上下文 ​

Agent 循环流程 ​

系统提示词构成 ​

钩子系统（Hooks） ​

5. 会话管理 ​

多人场景下的隐私隔离 ​

会话生命周期 ​

会话存储与维护 ​

会话键格式 ​

身份关联（identityLinks） ​

跨会话通信工具 ​

6. 记忆系统 ​

自动记忆刷新 ​

向量记忆搜索 ​

混合搜索（BM25 + 向量） ​

QMD 后端（实验性） ​

7. 上下文压缩与会话修剪 ​

上下文压缩（Compaction） ​

会话修剪（Session Pruning） ​

8. 多 Agent 路由 ​

路由优先级（最具体先匹配） ​

同一渠道按联系人分流 ​

为家庭群创建专用 Agent（限制权限） ​

多渠道账号 ​

每个 Agent 独立沙盒和工具权限 ​

9. 消息投递与流式输出 ​

入站防抖 ​

消息排队模式 ​

块流（Block Streaming） ​

预览流模式 ​

重试策略 ​

10. 认证与 OAuth ​

认证方式 ​

多账号配置（Auth Profiles） ​

OpenAI Codex OAuth 流程 ​

Anthropic setup-token ​

11. 在线状态与其他 ​

12. 常见问题 ​

第六章智能体管理

0. 什么是 Agent？

1. 网关架构（Gateway）

2. Agent 工作区

2.1 默认位置

2.2 工作区文件一览

2.3 工作区文件配置指南

如何编辑这些文件？

IDENTITY.md —— 龙虾的身份证

SOUL.md —— 龙虾的性格

USER.md —— 用户档案

AGENTS.md —— 操作手册

TOOLS.md —— 工具使用备注

MEMORY.md —— 长期记忆（可选）

BOOTSTRAP.md —— 首次引导仪式（一次性）

BOOT.md —— 启动任务（可选）

HEARTBEAT.md —— 心跳任务（可选）

2.4 哪些不在工作区

3. 首次启动：引导仪式

引导过程

4. Agent 循环与上下文

Agent 循环流程

系统提示词构成

钩子系统（Hooks）

5. 会话管理

多人场景下的隐私隔离

会话生命周期

会话存储与维护

会话键格式

身份关联（identityLinks）

跨会话通信工具

6. 记忆系统

自动记忆刷新

向量记忆搜索

混合搜索（BM25 + 向量）

QMD 后端（实验性）

7. 上下文压缩与会话修剪

上下文压缩（Compaction）

会话修剪（Session Pruning）

8. 多 Agent 路由

路由优先级（最具体先匹配）

同一渠道按联系人分流

为家庭群创建专用 Agent（限制权限）

多渠道账号

每个 Agent 独立沙盒和工具权限

9. 消息投递与流式输出

入站防抖

消息排队模式

块流（Block Streaming）

预览流模式

重试策略

10. 认证与 OAuth

认证方式

多账号配置（Auth Profiles）

OpenAI Codex OAuth 流程

Anthropic setup-token

11. 在线状态与其他

12. 常见问题