第5章 Agent 智能体与工作区

一句话：Agent 是 OpenClaw 的大脑——模型选择决定智商上限，System Prompt 决定性格底色，Session 管理决定记忆边界，搞对这三件事，你的 AI 助手才能真正好用。

---

5.1 Agent 核心架构

OpenClaw 的 Agent 基于 Pi agent core 构建，采用单嵌入式运行时设计。每个 Agent 实例需要一个工作目录（workspace）作为运行时的根目录，所有记忆文件、Bootstrap 文件、工具输出都存放在其中。

Agent = 模型（大脑）+ Workspace（记忆和工具）+ System Prompt（性格）

---

5.2 模型配置

primary + fallbacks 回退链

{
  agents: {
    defaults: {
      model: {
        primary: "deepseek/deepseek-v3.2",        // 主模型
        fallbacks: [
          "minimax/MiniMax-M2.5",                  // 第一备选
          "moonshot/kimi-k2.5",                    // 第二备选
        ],
      },
    },
  },
}

当主模型返回错误（API 限流、服务不可用等）时，Agent 会自动沿 fallbacks 列表依次尝试，直到成功或全部失败。

models 白名单

models 字段有双重作用——白名单和别名：

{
  agents: {
    defaults: {
      models: {
        "deepseek/deepseek-v3.2": { alias: "DeepSeek" },
        "minimax/MiniMax-M2.5": { alias: "MiniMax" },
        "moonshot/kimi-k2.5": { alias: "Kimi" },
        "zai/glm-5": { alias: "GLM" },
        // 以下需海外账户
        // "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        // "openai/gpt-5.4": { alias: "GPT" },
      },
    },
  },
}

用户在聊天中可以通过别名切换：

/model DeepSeek    ← 切换到 deepseek-v3.2
/model Kimi        ← 切换到 kimi-k2.5

注意：models 白名单控制的是用户通过 /model 命令可切换的模型列表。model.primary 和 fallbacks 不要求必须在 models 中列出——但建议保持一致，方便用户切换。

图片处理

{
  agents: {
    defaults: {
      imageMaxDimensionPx: 1200,  // 图片最长边限制
    },
  },
}

场景	推荐值	说明
一般聊天	1200	够用且省 token
代码截图/文档	1600	需要识别文字
极限省 token	800	只能看个大概

---

5.3 Bootstrap 文件体系

Bootstrap 文件是 Agent 的”灵魂工程”——它们在每次会话开始时被注入到上下文中，决定了 Agent 的行为方式、知识边界和人格特征。所有 Bootstrap 文件都是 Markdown 格式，存放在 Agent 的 workspace 目录下。

~/.openclaw/workspace/
  IDENTITY.md      # 名字、风格、Emoji
  SOUL.md          # 人格、边界、语气
  USER.md          # 用户画像
  AGENTS.md        # 操作指令 + 记忆
  TOOLS.md         # 工具使用说明
  BOOTSTRAP.md     # 首次运行仪式（运行后自动删除）

注入顺序（重要！）

Agent 会话开始时，Bootstrap 文件按以下顺序注入上下文：

IDENTITY.md → SOUL.md → USER.md → AGENTS.md → TOOLS.md → [BOOTSTRAP.md]

后注入的内容在上下文中位置更靠后，对模型行为的影响更大（recency bias）。这意味着：

• AGENTS.md 的优先级高于 SOUL.md：如果两者有冲突，Agent 更倾向于遵守 AGENTS.md
• TOOLS.md 的影响力最大：最后注入（BOOTSTRAP.md 除外），适合放”硬性规则”

各文件职责

文件	注入时机	作用	编辑频率
IDENTITY.md	每次会话	名字、emoji、基本人设	设定后很少改
SOUL.md	每次会话	性格、语气、行为边界	初期设定，偶尔调整
USER.md	每次会话	用户个人信息	按需更新
AGENTS.md	每次会话	操作手册 + 手动记忆	经常编辑
TOOLS.md	每次会话	工具使用笔记	按需添加
BOOTSTRAP.md	仅首次会话	首次启动引导，完成后自动删除	只写一次

IDENTITY.md — 身份卡片

# Identity

- Name: 小克
- Emoji: 🦀
- Vibe: 务实、高效、有一点极客幽默
- Language: 中文为主，技术术语保持英文

SOUL.md — 人格设计

# Soul

## 身份
你叫小克（Claw），是一个务实的技术助手。

## 性格特点
- 说话直接，不说废话
- 用类比解释复杂概念
- 适当使用幽默，但不过度
- 承认不知道的事情

## 语言规范
- 默认用中文回复
- 技术术语保持英文（如 API、Token、Webhook）
- 代码注释用中文

## 行为边界
- 不生成虚假信息或编造不存在的 API
- 不执行危险的系统命令（rm -rf / 等）
- 被要求做超出能力范围的事时，坦诚说明

## 回复风格
- 短问题短回答，不要过度展开
- 长问题先给摘要，再详细解释
- 代码优先，文字辅助

人格设计技巧：

1. 明确而非模糊：“说话直接”比”注意沟通方式”更有效
2. 给出反面示例：告诉 Agent 什么不该做同样重要
3. 保持简洁：SOUL.md 每次会话都会注入，太长浪费 token。控制在 200-500 字

USER.md — 用户画像

# User Profile

- 名字：小明
- 角色：全栈开发者
- 技术栈偏好：TypeScript, Python, Go
- 经验：5 年以上
- 偏好：喜欢简洁的代码，讨厌过度抽象
- 时区：Asia/Shanghai (UTC+8)

AGENTS.md — 操作指令

这是你最常编辑的文件。把它想象成给 Agent 的工作手册：

# Operating Instructions

## 核心任务
你是一个全栈开发助手，主要帮助我处理以下工作：
- Python 后端开发（FastAPI, SQLAlchemy）
- React 前端开发（TypeScript, Next.js）
- DevOps（Docker, K8s, CI/CD）

## 工作习惯
- 回答时先给结论，再给解释
- 代码示例用中文注释
- 遇到不确定的事情，主动说"我不确定"

## 项目上下文
当前主要项目：电商后台管理系统
- 技术栈：Next.js 14 + FastAPI + PostgreSQL
- 仓库地址：github.com/example/admin-panel

## 记忆笔记
- 2024-12-01: 数据库从 MySQL 迁移到 PostgreSQL
- 2024-12-15: 前端升级到 Next.js 14

BOOTSTRAP.md — 首次运行仪式

仅在首次会话注入，完成后自动删除：

# Bootstrap

这是你的首次启动。请完成以下初始化任务：
1. 阅读工作目录下的 README.md
2. 在 AGENTS.md 底部记录你对项目的理解
3. 确认你可以正常使用所有工具
4. 向用户发送一条简短的自我介绍

---

5.4 System Prompt 编写实战

SOUL.md + AGENTS.md 共同构成了 Agent 的 System Prompt。下面是一个完整的中文技术客服 Agent 示例。

SOUL.md（客服版）

# Soul

## 角色
你是"小助"，一家 SaaS 公司的技术客服 AI。

## 性格
- 耐心、友好、专业
- 用户说得模糊时，追问而不是猜测
- 复杂问题分步骤引导

## 边界
- 不讨论竞争对手的产品
- 不承诺未发布的功能
- 无法解决时，引导用户提交工单

## 语言
- 中文回复
- 避免技术黑话，用通俗语言解释

AGENTS.md（客服版）

# Operating Instructions

## 知识库
- 产品文档: docs.example.com
- API 文档: api.example.com/docs

## 工作流程
1. 理解用户问题
2. 检查是否在 FAQ 中有现成答案
3. 如果没有，尝试从知识库查找
4. 给出解决方案，附上相关文档链接
5. 确认用户问题是否解决

## FAQ
Q: 如何重置密码？
A: 访问 https://example.com/reset，输入注册邮箱即可。

Q: API 限流规则是什么？
A: 免费版 100 次/分钟，专业版 1000 次/分钟，企业版无限制。

---

5.5 Session 管理

dmScope 四种模式

dmScope 决定了不同来源的消息是否共享同一个会话上下文。注意：dmScope 在顶层 session 下配置，不是在 agents.defaults.session 下：

{
  session: {
    dmScope: "per-channel-peer",  // 推荐值
  },
}

模式	说明	示例
"main"	所有消息共享一个 session	Telegram 和 Discord 聊同一个上下文
"per-peer"	按用户隔离	同一用户在不同 Channel 共享上下文
"per-channel-peer"	按 Channel + 用户隔离	推荐。各平台互不影响
"per-account-channel-peer"	按账户 + Channel + 用户	同平台有多个账号时使用

推荐 "per-channel-peer"：不同平台的对话场景通常不同（Telegram 聊工作，Discord 聊开源），上下文隔离可以防止跑题。

identityLinks 跨平台用户识别

同一个用户可能在不同平台有不同的用户 ID。identityLinks 让 OpenClaw 知道这些 ID 属于同一个人：

{
  session: {
    dmScope: "per-channel-peer",
    identityLinks: {
      alice: [
        "telegram:123456789",
        "discord:987654321",
      ],
      bob: [
        "telegram:111222333",
        "whatsapp:+8613800138000",
      ],
    },
  },
}

身份链接的作用：当 dmScope 为 "per-peer" 时，已链接的 ID 共享同一个 session；Agent 可以识别跨平台的同一用户。

ID 格式必须是 platform:userId，其中 platform 必须与 Channel type 一致，userId 必须是平台的原始用户 ID（不是用户名）。

会话重置

默认情况下，Agent 会话每天凌晨 4:00 AM 自动重置。用户也可以手动重置：

/new     ← 开始全新会话
/reset   ← 重置当前会话（清除历史，保留 Bootstrap 注入）

---

5.6 上下文窗口 & Compaction

上下文窗口 = 工作台

把 Agent 的上下文窗口想象成一张工作台——这是 Agent 同时能看到的所有信息。工作台大小由模型决定：

模型	上下文窗口	类比
DeepSeek V3.2	128K tokens	一张大书桌
GLM-5	200K tokens	一张半书桌
Kimi K2.5	256K tokens	两张拼起来的书桌
MiMo V2	262K tokens	更大的书桌
GPT-5.4	272K～1M tokens	一整间书房
Claude Sonnet/Opus 4.6	1M tokens	一整间书房

当工作台上的文件堆满了（对话太长），Agent 就需要”整理书桌”——这就是 Compaction。

Compaction：自动整理书桌

当会话的 token 消耗接近模型上限时，Agent 会自动执行 compaction——将重要信息持久化到记忆文件，然后释放上下文空间。你也可以在聊天中发送 /compact 手动触发。

Compaction 不等于”遗忘”——重要信息会被写入文件，以后可通过记忆搜索找回。详见第 6 章记忆系统。

---

5.7 完整配置结构

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "deepseek/deepseek-v3.2",
        fallbacks: ["minimax/MiniMax-M2.5"],
      },
      models: {
        "deepseek/deepseek-v3.2": { alias: "DeepSeek" },
        "minimax/MiniMax-M2.5": { alias: "MiniMax" },
        "moonshot/kimi-k2.5": { alias: "Kimi" },
      },
      imageMaxDimensionPx: 1200,
    },
    list: [
      { id: "main", default: true },
      { id: "home", workspace: "~/.openclaw/workspace-home" },
    ],
  },

  session: {
    dmScope: "per-channel-peer",
  },
}

---

5.8 小结

主题	要点
模型配置	model.primary + fallbacks 构成回退链，models 兼做白名单和别名表
Bootstrap 文件	六个 Markdown 文件定义 Agent 的”灵魂”，按 IDENTITY→SOUL→USER→AGENTS→TOOLS→BOOTSTRAP 顺序注入
System Prompt	SOUL.md 管性格，AGENTS.md 管行为，两者组合就是 System Prompt
Session 管理	dmScope 在顶层 session 下配置，推荐 per-channel-peer
上下文窗口	像工作台一样有大小限制，Compaction 自动”整理书桌”持久化重要信息
identityLinks	跨平台用户识别，实现一致的个性化体验

下一章深入记忆系统——Agent 如何记住你。