🤖 多代理 AI 系统的架构设计与实现

【导读】

你有没有想过，一个能同时运行在 Telegram、Discord、Slack 等多个平台，支持多种 AI 模型，还能自动调用工具执行复杂任务的 AI 助手，它的核心大脑是如何工作的？

今天，我们就来深度解析 OpenClaw 项目的 Agent 模块，揭开多代理 AI 系统的神秘面纱。

01 Agent 系统全景图

OpenClaw 的 Agent 模块位于 src/agents/ 目录，包含约 749 个 TypeScript 文件。这是一个高度模块化的多代理系统，核心架构可以用"一个运行时、三大系统、两个机制"来概括。

🧠一个运行时：

Pi Embedded Runner —— Agent 的核心大脑

🔧三大系统：

• 工具系统（Tools）—— 让 AI 能"做事"

• 技能系统（Skills）—— 让 AI 更"专业"

• 会话系统（Sessions）—— 让 AI 有"记忆"

🛡️两个机制：

• 沙箱隔离机制 —— 安全保障

• 认证故障转移 —— 高可用设计

02 核心组件详解

▍组件一：Agent 运行时

如果把 Agent 比作一个人，那么运行时就是它的大脑皮层，负责思考、决策和执行。

运行时的核心工作流程：

第一步模型解析与认证从配置中解析出要使用的 AI 模型（如 Claude、GPT-4 等），并从认证库中获取对应的 API Key 或 OAuth 凭证。

第二步上下文窗口保护实时监控对话上下文的 token 使用量，当接近模型限制时自动触发压缩机制，避免"失忆"。

第三步故障转移当某个 API Key 失效或遇到限流时，自动切换到备用凭证，保证服务不中断。

第四步使用量追踪精确统计每次调用的输入/输出 token 数、缓存命中情况，帮助你优化成本。

💡 技术亮点：

✓ 支持多个 Auth Profile 轮询

✓ 自动冷却机制（cooldown）

✓ 错误智能分类：auth、rate_limit、billing、timeout、context_overflow

▍组件二：流式响应处理

你在使用 ChatGPT 时看到文字逐字冒出的效果，就是流式响应。OpenClaw 的实现更加精细。

流式处理的秘密：

📦 消息分块将长文本按段落或标题分块，避免一次性处理过大内容。

🤔 推理模式支持可以剥离<think>标签，只显示最终答案；也可以开启流式推理，让 AI"边想边说"。

🔄 重复检测智能识别并过滤重复内容，避免 AI 反复发送相同消息。

📊 工具结果聚合当 AI 调用工具（如搜索网页、读取文件）后，自动聚合并格式化结果。

// 代码片段（简化版）：const emitBlockChunk = (text) => { // 剥离思考标签const chunk = stripTags(text); // 检测重复if (isDuplicate(chunk)) { return; // 跳过重复内容 } // 发送给用户 sendToUser(chunk); };

▍组件三：工具系统

工具是让 AI 从"只会聊天"变成"能干活"的关键。OpenClaw 内置了 20+ 种工具。

📋 内置工具清单：

💻编码工具

read —— 读取文件 | write —— 写入文件 | edit —— 编辑文件

bash —— 执行 shell 命令 | exec —— 执行进程

🌐网络工具

browser —— 浏览器自动化 | web_search —— 网络搜索 | web_fetch —— 网页抓取

💬通信工具

message —— 发送消息（支持多平台） | tts —— 文本转语音

🎨多媒体工具

canvas —— Canvas 操作 | image —— 图片处理 | pdf —— PDF 解析

⚙️系统工具

cron —— 定时任务管理 | gateway —— Gateway 控制

memory —— 记忆检索 | subagents —— 子代理管理

工具创建流程（6 步）：

⬇️

1️⃣ 解析工具策略（允许/禁止哪些工具）

2️⃣ 创建基础编码工具

3️⃣ 创建 OpenClaw 内置工具

4️⃣ 加载插件工具

5️⃣ 应用策略过滤

6️⃣ 包装钩子和中止信号

▍组件四：技能系统

技能是 OpenClaw 的特色功能，让你可以像安装 App 一样为 AI 添加新能力。

🎯 技能 = 工具集合 + 提示词模板 + 依赖配置

举个例子，一个"GitHub 技能"可能包含：

• 工具：
  查询 issue、创建 PR、读取仓库
• 提示词：
  如何写 commit message、代码审查规范
• 依赖：
  需要安装 git、配置 GitHub Token

技能加载流程：

1️⃣ 扫描 workspace/skills/ 目录

2️⃣ 解析 frontmatter 元数据

3️⃣ 验证依赖（bin、env、config）

4️⃣ 构建技能提示词

5️⃣ 注入到系统提示中

# 技能元数据格式（YAML）： --- skill: github emoji: 🐙 requires: bins: [git] env: [GITHUB_TOKEN] install: - npm install -g @octokit/cli ---

▍组件五：沙箱隔离机制

安全是 AI 系统的生命线。OpenClaw 通过 Docker 沙箱实现隔离，防止 AI"越狱"。

// 沙箱配置选项：{"enabled":true,"docker": {"image":"openclaw/sandbox:latest","networkMode":"bridge","env": {} },"workspaceAccess":"rw","browser": {"enabled":true,"bridgeUrl":"..." } }

沙箱如何工作？

1️⃣ 创建 Docker 容器

2️⃣ 挂载工作区目录（只读/读写）

3️⃣ 所有命令在容器内执行

4️⃣ 文件系统操作通过桥接层

5️⃣ 浏览器在独立容器中运行

🛡️ 安全优势：

✓ 防止 AI 访问宿主机敏感文件

✓ 限制网络访问范围

✓ 自动清理临时文件

✓ 资源使用受限

▍组件六：会话管理

会话是 AI 的"记忆"，让每次对话都有上下文。

Session Key 格式（5 种）：

🏠主会话：agent:main:main

👤直接消息（DM）：agent:main:direct:user123

👥群组/频道：agent:main:telegram:group:group456

🧵线程：agent:main:slack:channel:C123:thread:T456

🤖子代理：agent:main:subagent:parent:child

// 会话存储结构： { "sessionId": "agent:main:main", "messages": [...], "createdAt": 1709481600000, "updatedAt": 1709568000000, "metadata": { "provider": "anthropic", "model": "claude-sonnet-4", "usage": {} } }

03 完整工作流程

从你发送一条消息，到 AI 回复，中间经历了什么？让我们走完全流程。

【阶段一】路由解析

你在 Telegram 发送："帮我查一下天气"

⬇️

Gateway 收到消息，解析出：

• channel: telegram

• accountId: +8613800138000

• peerId: user123

⬇️

根据路由规则，确定目标 agentId: main

生成 sessionKey: agent:main:direct:user123

【阶段二】会话加载

从 sessions.json 加载历史对话：

user: 昨天北京天气怎么样？

assistant: 昨天北京晴转多云，最高温度 25°C。

加载身份链接（identityLinks）：

• user123 = "张三"

• 偏好：使用摄氏度、24 小时制

【阶段三】引导上下文加载

加载工作区文件：

📄 AGENTS.md —— Agent 行为规范

📄 SOUL.md —— 人格设定

📄 TOOLS.md —— 可用工具说明

📄 IDENTITY.md —— 身份信息

📄 USER.md —— 用户偏好

📄 BOOTSTRAP.md —— 启动指令

📄 MEMORY.md —— 长期记忆

这些文件构成 AI 的"系统提示"，告诉它"你是谁、能做什么、怎么做"。

【阶段四】技能加载

扫描 workspace/skills/ 目录：

⬇️

找到技能：

✓ weather（天气查询）

✓ location（地理位置）

✓ unit-converter（单位转换）

⬇️

验证依赖：

✓ weather 需要：OPENWEATHER_API_KEY

✓ location 需要：无

✓ unit-converter 需要：无

⬇️

构建技能提示词，注入系统提示。

【阶段五】工具创建

创建工具列表：

• 编码工具：read, write, edit, bash

• OpenClaw 工具：message, browser, web_search

• 插件工具：weather_api, location_api

⬇️

应用策略过滤：

允许：read, web_search, message

禁止：gateway（普通用户不能重启网关）

⬇️

包装钩子：

• Before Tool Call：检查工具循环

• After Tool Call：记录审计日志

【阶段六】模型解析与认证

解析配置：

• provider: anthropic

• model: claude-sonnet-4-20250514

⬇️

获取认证：从 auth-profiles.json 读取 API Key

⬇️

故障转移准备：

• 主 Profile: anthropic-main

• 备用 Profile: anthropic-oauth

【阶段七】Agent 运行

构建系统提示：

你是一个 AI 助手，运行在 OpenClaw 平台上。

【引导指令】使用中文回复，温度使用摄氏度...

【可用工具】read、web_search、message、weather_api...

【当前会话】user: 帮我查一下天气...

⬇️

调用模型 API（流式）：

stream = model.chat.completions.create({ model: "claude-sonnet-4", messages: [...], tools: [...], stream: true });

⬇️

处理工具调用：

if (tool_call.name === "weather_api") { const result = await weather_api.call({ location: "北京", date: "today" }); return result; // { temp: 23, condition: "晴" } }

⬇️

上下文溢出检测：

if (currentTokens > threshold) { await compactSession(); // 自动压缩 }

【阶段八】流式响应处理

订阅事件流：

subscribe(stream, { onTextChunk: (chunk) => { // 剥离 <think> 标签const clean = stripTags(chunk); // 分块发送 sendToTelegram(clean); }, onToolCall: (tool, args) => { // 显示"正在查询天气..." showToolStatus(tool); }, onToolResult: (result) => { // 聚合结果 aggregateResult(result); } });

【阶段九】响应交付

最终回复：

"北京今天晴，最高温度 23°C，最低 15°C。适合户外活动！☀️"

⬇️

通过 Telegram 发送给用户

⬇️

更新会话存储：

sessions.json += { role: "assistant", content: "北京今天晴...", timestamp: 1709568000000 }

⬇️

标记 auth profile 为"良好"（成功响应）

04 工具调用执行流程

当 AI 决定调用工具时，发生了什么？

步骤 1：工具调用验证

// 模型返回： { "tool_calls": [{ "id": "call_123", "name": "web_search", "arguments": { "query": "北京天气" } }] }

⬇️

验证：

✓ 工具在允许列表中

✓ 参数符合 schema

✓ 用户有权限调用

步骤 2：Before Tool Call 钩子

plugin.hooks.beforeToolCall(tool, args) → 记录审计日志 → 检查工具循环（防止死循环）

步骤 3：工具执行

根据工具类型执行：

• exec → 通过 bash/docker 执行命令

• read → 读取文件（沙箱化）

• message → 通过 channel 发送消息

• browser → 通过 sandbox browser 控制

• web_search → 调用搜索 API

步骤 4：结果处理

// 格式化结果： { text: "北京今天晴，23°C", images: [], media: [] }

⬇️

• 图像 sanitization（防止 XSS）

• 应用 tool_result 策略

步骤 5：After Tool Call 钩子

plugin.hooks.afterToolCall(tool, result) → 记录工具调用历史 → 更新使用量统计

步骤 6：返回结果给模型

// 构建 tool_result 消息： { role: "tool", tool_call_id: "call_123", content: "北京今天晴，23°C" }

⬇️

继续对话循环，模型生成最终回复

05 子代理派生机制

OpenClaw 支持"代理生代理"，实现任务分解和并行处理。

📌 场景示例

主代理收到任务："帮我写一个 Python 脚本，测试后提交到 GitHub"

⬇️

主代理决定派生子代理：

🤖 子代理 1：编写脚本

🤖 子代理 2：编写测试

🤖 子代理 3：提交到 GitHub

子代理创建流程

步骤 1：创建子会话

生成新的 sessionKey: agent:main:subagent:parent:child

继承父会话配置（model、sandbox、tools）

设置 spawnDepth = parentDepth + 1

步骤 2：注册子代理

记录 runId、childSessionKey、requesterSessionKey

设置超时和清理策略

持久化到磁盘

步骤 3：启动子代理运行

传递任务 prompt

继承工具策略（可能受限）

步骤 4：生命周期事件监听

监听 lifecycle start/end 事件

错误重试宽限期（15 秒）

步骤 5：完成处理

宣布完成（announce flow）

清理会话（如果 cleanup=delete）

归档记录（archiveAfterMinutes）

// 子代理配置示例： { "subagents": { "maxDepth": 5, "archiveAfterMinutes": 60, "tools": { "allow": ["read", "web_search"], "deny": ["gateway", "sessions_spawn"] } } }

06 认证与故障转移

高可用设计是 OpenClaw 的核心特性之一。

Auth Profile 类型

🔑 API Key 认证

{ "type": "api_key", "provider": "anthropic", "key": "sk-ant-..." }

🎫 Token 认证

{ "type": "token", "provider": "openai", "token": "..." }

🔐 OAuth 认证

{ "type": "oauth", "provider": "anthropic", "clientId": "...", "clientSecret": "...", "accessToken": "...", "refreshToken": "..." }

故障转移逻辑

尝试当前 profile

⬇️

成功 → 标记为"良好"，返回

⬇️

失败 → 分类错误原因

⬇️

• auth → 永久禁用该 profile

• rate_limit → 冷却 5 分钟

• billing → 冷却直到续费

• timeout → 重试 1 次

⬇️

尝试下一个 profile

⬇️

所有 profile 失败 → 抛出错误

07 配置实战

▍多 Agent 配置

（此处可添加实际配置示例）

08 技术亮点总结

✨模块化设计清晰的职责分离，每个子系统独立演进。

✨故障转移机制多认证 Profile 轮询，自动冷却和错误分类。

✨流式响应高效的流式处理，支持推理模式、消息分块。

✨工具系统20+ 内置工具，支持插件扩展，完善的策略管道。

✨沙箱隔离Docker 沙箱，文件系统桥接，浏览器隔离。

✨子代理支持完整的子代理生命周期管理，深度限制。

✨会话管理灵活的 session key 格式，支持线程、群组等场景。

09 架构启示

OpenClaw 的 Agent 模块设计给我们什么启发？

🎯 关注点分离运行时、工具、技能、会话各自独立，便于测试和维护。

🛡️ 防御性编程沙箱隔离、工具策略、循环检测，层层防护。

📉 优雅降级认证失败时故障转移，上下文溢出时自动压缩。

📊 可观测性详细的使用量统计、工具调用历史、审计日志。

🔌 扩展性插件系统、技能系统、子代理机制，无限可能。

📝 【结语】

OpenClaw 的 Agent 模块是一个工业级多代理系统的优秀范例。它不仅实现了强大的功能，更在安全性、高可用性、可维护性方面做了深思熟虑的设计。

如果你对构建自己的 AI 助手感兴趣，OpenClaw 的源码值得深入研究。

📚 参考资料

• OpenClaw GitHub: https://github.com/openclaw/openclaw

• 官方文档：https://docs.openclaw.ai

本文分析基于版本：2026.3.3