OpenClaw — Agent Runtime 核心
📍 位置：OpenClaw学习框架 / 第 2 层-B
📌 核心发现：Pi Agent Runtime 是执行引擎，管理 LLM 调用→工具执行→上下文压缩的完整循环
📥 输入：DeepWiki Section 3（Agent Runtime 及其 6 个子章节）
📤 流向：→ findings.md [Agent 执行模型理解]
Agent Runtime 职责
Agent Runtime（Pi Agent）编排一次 AI 助理回合的完整生命周期：
消息输入 → 指令解析 → 模型选择 → 提示词组装 → LLM 调用 → 工具循环 → 响应输出
↑ │
└──────┘
(工具结果反馈)
3.1 执行管线（7 个阶段）
Stage 1: 输入处理
parseReplyDirectives()：提取内联指令（/think、/model、/verbose）detectCommand()：识别独立命令（/status、/reset、/new）- 独立命令走快速路径，直接返回，不经过模型
Stage 2: 模型解析
resolveModel()：按优先级选择模型（指令 > 会话覆盖 > Agent 配置 > 全局默认）resolveAuthProfileOrder()：解析 Auth Profile 链- 支持动态模型 ID（
resolveDynamicModel 处理未来模型如 GPT-5、Claude 4）
Stage 3: 系统提示词组装
buildEmbeddedSystemPrompt() 从多个模块组装：
| 模块 | 内容 |
|---|
| Identity | 核心人格 + 安全护栏 |
| Tools | 允许的工具描述 |
| Skills | 来自 .skill 文件的动态指令 |
| Context | 注入的 SOUL.md、AGENTS.md 等 |
| Runtime | Shell、OS、沙箱环境信息 |
三种提示词模式优化 token 使用：
full（默认）：完整提示词minimal：子 Agent 使用，精简版none：仅基础身份
Stage 4: 执行
嵌套函数调用链：
runReplyAgent()
→ runAgentTurnWithFallback()
→ runEmbeddedPiAgent()
→ runEmbeddedAttempt()
Stage 5: 工具调度
createOpenClawCodingTools()：组装可用工具集isToolAllowedByPolicies()：策略过滤- 工具调用 → 结果返回 → 继续推理（循环直到无工具调用）
Stage 6: 响应处理
subscribeEmbeddedPiSession()：流式 delta 输出- 文本分块投递到通道
Stage 7: 状态管理
updateSessionStoreEntry()：更新会话元数据compactEmbeddedPiSession()：触发上下文压缩（如需要）
并发控制
- Lane 序列化：每个会话同时只运行一个回合
- 全局并发限制：限制同时进行的 LLM 调用数
Auth Profile 轮换
尝试 Profile A → 速率限制/认证错误
│
▼
markAuthProfileFailure(A)
│
▼
尝试 Profile B → 成功 ✓
3.2 Transcript 处理
不同 LLM 供应商对消息格式有不兼容要求，系统自动适配：
| 供应商 | 关键处理 |
|---|
| OpenAI | 最少清洗，保留工具调用 ID |
| Anthropic | 删除 thinking blocks，校验轮次结构 |
| Google | 严格 ID 清洗，强制 user 消息开头（不允许 assistant 先说） |
| Mistral | 工具 ID 必须 9 字符字母数字 |
其他处理：
- 孤立消息修复：删除没有对应
tool_use 的 tool_result
- 图片约束：Anthropic 有最大尺寸/字节限制，自动缩放
- 内容块过滤：移除某些端点拒绝的 thinking block
3.3 模型供应商与认证
支持的供应商
Anthropic、OpenAI、Google Gemini、Ollama、Minimax、Moonshot/Kimi、Qwen、Volcengine、Amazon Bedrock 等
Auth Profile 存储
// ~/.openclaw/agents/<id>/agent/auth-profiles.json
{
"anthropic:default": {
"type": "apiKey",
"apiKey": "sk-ant-..." // 明文
},
"openai:default": {
"type": "apiKey",
"apiKey": { "source": "env", "id": "OPENAI_API_KEY" } // SecretRef
},
"openai-codex:user@example.com": {
"type": "oauth",
"accessToken": "...",
"refreshToken": "..."
}
}
隐式供应商发现
自动注册三个阶段：
- API Key 供应商（Minimax、Moonshot、Kimi）
- OAuth Profile 供应商（Qwen-portal、OpenAI-codex）
- 配对供应商（Volcengine、Byteplus）
特殊：Ollama 通过 API 发现本地模型
3.4 工具系统
工具组装管线
Pi Agent 基础工具
│
▼
OpenClaw 替换/增强
（read/write/edit → 工作区隔离版本，bash → exec）
│
▼
策略过滤（8 层级联）
│
▼
供应商适配
（Gemini 去掉 minLength/pattern，xAI 去掉 web_search 等）
│
▼
安全包装
（循环检测 + 中止信号）
│
▼
最终 AnyAgentTool[] → 传给 LLM API
工具清单
| 工具组 | 包含工具 |
|---|
group:runtime | exec（命令执行）, process（后台进程管理） |
group:fs | read, write, edit, apply_patch |
group:sessions | sessions_list, sessions_history, sessions_send, sessions_spawn |
group:memory | memory_search, memory_get |
group:web | web_search, web_fetch |
group:ui | browser, canvas |
group:automation | cron, gateway |
group:messaging | message |
| Channel 工具 | telegram_react, discord_thread 等 |
工具策略级联（8 层，从低到高优先级）
① 全局 tools.allow/deny
↓
② 工具 Profile（minimal/coding/messaging/full）
↓
③ 供应商特定约束
↓
④ Agent 级配置
↓
⑤ Agent + 供应商组合覆盖
↓
⑥ 通道群组策略
↓
⑦ 发送者级别限制
↓
⑧ 运行时沙箱 + 子 Agent 继承
工具 Profile 预设：
| Profile | 可用工具 |
|---|
minimal | 仅 session_status |
coding | group:fs + group:runtime + group:sessions + group:memory |
messaging | group:messaging + session 工具 |
full | 无限制 |
Owner-Only 工具（需 senderIsOwner: true）：
cron、gateway、nodes、whatsapp_login
Exec 工具
| 参数 | 说明 |
|---|
command | 要执行的 shell 命令（必需） |
background | 立即后台运行 |
yieldMs | 超时后自动后台化（默认 10 秒） |
timeout | 超时终止（默认 30 分钟） |
pty | 分配伪终端 |
安全措施：
- Shell 注入检测：检查
$VAR_NAME 出现在脚本文件中的模式
- 审批流程：allowlist + safe binaries（
ls、git 等）+ skill 关联工具
- 进程隔离：按
scopeKey 隔离，防跨 Agent 干扰
工作区隔离
tools.fs.workspaceOnly: true 时，文件操作工具强制路径守卫，拒绝访问工作区外的系统文件。
3.5 命令与指令
独立命令（快速路径）
| 命令 | 用途 |
|---|
/status | 显示模型、token 用量、上下文窗口、缓存统计等 |
/reset | 重置会话 |
/new | 新建会话 |
/think <level> | 控制推理深度 |
/model <name> | 切换模型 |
内联指令
| 指令 | 用途 |
|---|
/think <level> | 推理深度 |
/verbose <level> | 输出详细度 |
/elevated <level> | 权限提升 |
/reasoning <mode> | 推理模式 |
/exec <params> | 执行参数 |
/queue <mode> | 队列行为 |
授权模型
- 默认拒绝：所有命令需通过
CommandAuthorized 检查
- 优先级：
commands.allowFrom > 通道白名单 + 配对系统 > commands.useAccessGroups
bash、config、debug 三个特殊命令需要显式配置标志
3.6 上下文压缩（Compaction）
触发条件
estimateTokens(messages + prompt) > contextWindow × 0.85
阈值：硬最低 8,192 tokens，警告 32,768 tokens
压缩流程
Token 超限检测
│
▼
Memory Flush（如需要）
└── tokens > 75% 且本轮未 flush → 持久化到记忆存储
│
▼
获取会话写锁（防 transcript 损坏）
│
▼
加载完整 JSONL transcript
│
▼
调用 LLM 压缩（runEmbeddedAttempt + 特殊指令）
└── 模型可配置：agents.defaults.compaction.model
│
▼
替换旧消息为生成的摘要
│
▼
广播诊断事件
│
▼
后压缩同步（memory 重索引）
└── off / async（默认）/ await
超时保护
- 单次压缩超时：180 秒
- 累计重试超时：防止无限循环
错误恢复
- 压缩失败 →
resetSessionAfterCompactionFailure()：生成新 sessionId，清空 transcript
- 轮次校验 →
validateAnthropicTurns() / validateGeminiTurns()：确保符合供应商要求
诊断追踪
每次压缩生成：
- 诊断 ID：
ovf-{timestamp36}-{random4}
- 指标：消息数、字符总量、工具结果大小、top 贡献者
3.7 记忆与搜索
双后端架构
| 后端 | 技术 | 特点 |
|---|
| Built-in (SQLite) | sqlite-vec + FTS5 | 向量相似度 + 关键词搜索 |
| QMD (Quick Markdown) | 外部 qmd CLI | 大规模集合优化 |
嵌入模型支持
- OpenAI
text-embedding-3-small
- Google Gemini
text-embedding-004
- Voyage
voyage-3
- Ollama（用户自定义）
混合搜索评分
FinalScore = (VectorScore × VectorWeight) + (KeywordScore × KeywordWeight)
CLI 命令
memory status：索引健康状态和 chunk 数memory index：强制重新扫描工作区memory search：测试查询
关键源文件
| 文件 | 职责 |
|---|
src/agents/pi-tools.ts | 工具组装入口 |
src/agents/tool-policy.ts | 策略解析 |
src/agents/tool-policy-pipeline.ts | 策略管线 |
src/agents/openclaw-tools.ts | 原生工具定义 |
src/agents/bash-tools.ts | Exec/Process 实现 |