Agents 智能体引擎详解
前置知识：本章节面向具备 TypeScript/Node.js 基础、了解 AI 模型 API 调用机制的开发者。 目标读者：希望深入理解 OpenClaw 智能体内部实现机制、进行二次开发或问题诊断的开发者。 维护状态：本文档基于 OpenClaw v2026.4+ 源码分析，描述的是当前实现细节，可能随版本更新变化。
📖 入门参考：若您希望了解如何使用智能体循环（而非其内部实现），请参阅 使用手册。
1. Agent 循环概述
1.1 完整生命周期
1.2 源码文件对应
| 阶段 | 主要文件 | 关键函数 |
|---|---|---|
| 入口 | agents/pi-embedded-runner/run.ts | runEmbeddedPiAgent() |
| 模型 | agents/pi-embedded-runner/model.ts | resolveModelAsync() |
| 上下文 | agents/pi-embedded-runner/compact*.ts | 上下文压缩 |
| 工具 | agents/pi-embedded-runner/run/attempt.ts | runEmbeddedAttempt() |
| 输出 | agents/pi-embedded-runner/stream*.ts | 流式处理 |
2. 上下文组装
2.1 上下文组成
2.2 系统提示构建流程
3. 模型选择
3.1 多模型配置
3.2 模型配置示例
json5
{
agents: {
defaults: {
model: {
primary: "anthropic/claude-sonnet-4-5",
fallbacks: [
"openai/gpt-4",
"anthropic/claude-haiku"
]
}
}
}
}3.3 提供商配置
json5
{
models: {
providers: {
anthropic: {
apiKey: "${ANTHROPIC_API_KEY}",
baseUrl: "https://api.anthropic.com"
},
openai: {
apiKey: "${OPENAI_API_KEY}"
}
}
}
}4. 工具执行
4.1 工具调用流程
4.2 工具源码位置
| 工具 | 源码路径 | 功能 |
|---|---|---|
exec | agents/bash-tools.exec.ts | 执行系统命令 |
exec (核心) | agents/bash-tools.ts | 命令执行核心 |
browser | agents/tools/web-tools.ts | 网页浏览 |
web-fetch | agents/tools/web-fetch.ts | 网页抓取 |
web-search | agents/tools/web-search.ts | 网页搜索 |
image | agents/tools/image-tool.ts | 图片处理 |
tts | agents/tools/tts-tool.ts | 语音合成 |
pdf | agents/tools/pdf-tool.ts | PDF 处理 |
4.3 exec 工具安全
4.4 工具权限配置
json5
{
tools: {
exec: {
enabled: true,
security: "allowlist",
ask: "on-miss",
allowlist: ["ls", "cat", "grep", "git"],
safeBins: ["jq", "sed"]
}
}
}5. 上下文压缩
5.1 压缩触发条件
5.2 压缩流程
5.3 手动压缩
/compact Focus on decisions and open questions6. 子智能体
6.1 子智能体架构
6.2 配置示例
json5
{
agents: {
defaults: {
subagents: {
enabled: true,
maxDepth: 3,
timeoutMs: 60000
}
}
}
}7. 会话管理
7.1 会话状态
7.2 会话范围
| 值 | 隔离级别 | 场景 |
|---|---|---|
main | 所有 DM 共享 | 单用户默认 |
per-peer | 按发送者 | 多用户 |
per-channel-peer | 通道+发送者 | 推荐多用户 |
per-account-channel-peer | 账户+通道+发送者 | 多账户 |
8. 流式输出
8.1 流式处理流程
8.2 渲染模式
json5
{
channels: {
feishu: {
renderMode: "raw" // 默认纯文本
}
}
}⚠️ 注意：飞书建议使用
raw模式，避免流式输出导致协议不匹配。
9. 错误处理与重试
9.1 重试策略
9.2 错误类型
| 类型 | 处理方式 |
|---|---|
rate_limit | 等待后重试 |
auth_error | 切换认证文件 |
context_overflow | 触发压缩 |
network_error | 指数退避 |
10. 调试与监控
10.1 查看运行日志
bash
# 实时查看 Agent 日志
openclaw gateway --verbose
# 查看特定会话
openclaw sessions view <session-id>10.2 关键指标
| 指标 | 说明 |
|---|---|
| 模型延迟 | 请求到响应的时间 |
| 工具调用次数 | 解决问题的工具数 |
| 上下文大小 | 消耗的 token 数 |
| 压缩次数 | 触发压缩的次数 |