——
OpenClaw CLI 工具结果持久化：3 步实现完整执行追踪
OpenClaw 最新提交为 CLI 运行器带来了关键能力补齐——工具执行结果现在可以被完整记录并持久化了。此前，使用 CLI 方式启动的 AI Agent 运行会丢失工具调用的详细记录，而嵌入式运行则支持完整的 verbose 输出。这一差距现已抹平。
本文将深入解析该功能的技术实现、适用场景，以及如何在 Telegram 等集成环境中启用完整追踪。
—
问题背景：CLI 与嵌入式运行的日志差异
在 OpenClaw 的架构中，工具执行结果通过事件流传递。CLI 解析器（CLI parser）原本已经能够生成包含以下信息的工具结果事件：
| 字段 | 说明 |
|:—|:—|
| name | 工具名称 |
| toolCallId | 唯一调用标识 |
| isError | 是否执行出错 |
| sanitized result | 脱敏后的执行结果 |
然而，Runner Bridge（运行器桥接层）此前会丢弃这些事件，导致 CLI 启动的运行在 verbose 模式下无法查看完整的工具调用历史——而嵌入式运行器（embedded runner）则不受此限制。
> 影响场景：通过命令行启动的自动化任务、Docker 容器内运行的 Agent、以及需要审计追踪的生产环境部署。
—
核心改进：Bridge 转发与统一摘要追踪
架构变更图解
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ CLI Parser │────→│ Runner Bridge │────→│ Summary Tracker│
│ (emit events) │ │ (NOW: forwards) │ │ (统一格式输出) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
↓
┌─────────────────┐ ┌─────────────────┐
│ Embedded Runner │────→│ Same Tracker │
│ (原有行为不变) │ │ (格式一致) │
└─────────────────┘ └─────────────────┘
关键技术点
1. 事件转发机制
Bridge 层现在将工具结果事件无损转发至摘要追踪器（summary tracker），而非直接丢弃：
// 伪代码示意：Bridge 层的事件处理
// 之前：忽略 tool-result 事件
// 现在：转发至 summaryTracker.process(event)
bridge.on('tool-result', (event) => {
// 新增：转发至统一追踪器
summaryTracker.capture({
meta: event.startArgs, // 从 start 事件捕获的元数据
result: event.sanitizedResult,
isError: event.isError
});
// 保持原有路由不变
routeToTelegram(event); // Telegram 持久化路由
routeToVerboseOutput(event); // Verbose 输出控制
});
2. 统一格式渲染
两个运行器现在使用相同的 formatToolAggregate 格式输出摘要行：
典型输出格式示例
[TOOL] search_web (call_abc123) ✓ 2.3s
→ Query: "OpenClaw latest features"
→ Results: 5 items retrieved
3. 完整输出控制
当启用完整 verbose 模式时，额外输出工具原始返回内容：
完整 verbose 输出示例
[TOOL] search_web (call_abc123) ✓ 2.3s
─────────────────────────────
RAW OUTPUT:
{
"results": [
{"title": "OpenClaw v2.1 Release", "url": "..."},
...
]
}
─────────────────────────────
—
配置与启用方法
步骤 1：更新至最新版本
通过 npm 更新
npm update @openclaw/cli
或通过 Docker 拉取最新镜像
docker pull openclaw/cli:latest
步骤 2：启用 Verbose 模式
基础 verbose（仅摘要）
openclaw run --verbose
完整输出（摘要 + 原始工具返回）
openclaw run --verbose=full
步骤 3：验证工具记录
检查运行日志中是否包含 [TOOL] 标记的行
openclaw run --verbose=full --task "搜索最新 AI 新闻" 2>&1 | grep "\[TOOL\]"
预期输出：
[TOOL] search_web (call_xxx) ✓ 1.8s
[TOOL] summarize_text (call_yyy) ✓ 0.5s
—
Telegram 集成场景的特殊优势
该改进对 Telegram Bot 集成尤为重要。由于 Telegram 路由复用了原有的 tool-result 事件通道，以下行为无需任何配置变更即可生效：
| 特性 | 行为说明 |
|:—|:—|
| Verbose 门控 | 仅当 --verbose 启用时发送详细记录 |
| 顺序保证 | 工具摘要始终位于最终答案之前 |
| 持久化路由 | 自动进入 Telegram 的 durable 存储 |
Telegram Bot 部署示例（Docker Compose）
services:
openclaw-telegram:
image: openclaw/cli:latest
environment:
- OPENCLAW_TELEGRAM_BOT_TOKEN=${BOT_TOKEN}
- OPENCLAW_VERBOSE=full # 启用完整工具记录
command: ["telegram-bot", "--durable-tool-summaries"]
—
与嵌入式运行的对比
| 特性 | CLI Runner（更新后） | Embedded Runner |
|:—|:—|:—|
| 工具摘要记录 | ✅ formatToolAggregate | ✅ formatToolAggregate |
| 完整 verbose 输出 | ✅ 支持 | ✅ 支持 |
| 启动方式 | 命令行 / Docker | 代码内嵌 |
| 适用场景 | 自动化脚本、CI/CD | 应用内集成 |
| Telegram 路由 | ✅ 原生支持 | 需额外配置 |
—
FAQ
Q1: 该更新会影响现有 CLI 命令的兼容性吗？
不会。 所有变更均为内部事件转发机制的增强，命令行参数和输出格式保持不变。现有脚本无需修改即可运行。
Q2: 如何区分工具执行成功与失败？
工具摘要行包含状态标记：✓ 表示成功，✗ 表示失败。完整 verbose 模式下，错误详情会包含在输出块中：
[TOOL] api_call (call_err001) ✗ 0.2s
ERROR: HTTP 429 - Rate limit exceeded
Q3: Telegram 消息长度限制会截断工具输出吗？
OpenClaw 的 Telegram 路由已实现智能分片。超长工具输出会自动拆分为多条消息，并保留关联的 toolCallId 以便追踪。
Q4: 可以仅记录特定类型的工具吗？
当前版本支持通过环境变量过滤：
export OPENCLAW_TOOL_FILTER="search_,calculate_"
openclaw run --verbose
Q5: 该功能对性能有何影响？
事件转发引入的额外开销可忽略不计（<1ms/事件）。摘要追踪器采用流式处理，不会累积大量内存。
—
总结与下一步
本次更新消除了 OpenClaw CLI 与嵌入式运行器在工具追踪能力上的最后差距，为生产环境的可观测性提供了坚实基础。关键收益：
1. 完整审计追踪 —— 所有工具调用均可持久化检索
2. 统一调试体验 —— 无论采用何种部署方式，日志格式一致
3. 零配置集成 —— Telegram 等现有通道自动受益
建议操作：
- 升级至包含提交
4ce1d78的版本 - 在测试环境启用
--verbose=full验证输出 - 查阅 OpenClaw 文档 了解高级配置选项
—
相关阅读
—
参考来源
- GitHub Commit: 4ce1d78 —— 功能实现的完整代码变更
- OpenClaw 官方文档 —— CLI 与嵌入式运行器配置指南
- 阅读原文：OpenClaw 教学小站 —— 本文原始发布地址
