OpenClaw CLI 工具结果持久化：3 步实现完整执行追踪

OpenClaw 最新提交为 CLI 运行器带来了关键能力补齐——工具执行结果现在可以被完整记录并持久化了。此前，使用 CLI 方式启动的 AI Agent 运行会丢失工具调用的详细记录，而嵌入式运行则支持完整的 verbose 输出。这一差距现已抹平。

本文将深入解析该功能的技术实现、适用场景，以及如何在 Telegram 等集成环境中启用完整追踪。

问题背景：CLI 与嵌入式运行的日志差异

在 OpenClaw 的架构中，工具执行结果通过事件流传递。CLI 解析器（CLI parser）原本已经能够生成包含以下信息的工具结果事件：

然而，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 格式输出摘要行：

# OpenClaw CLI 工具结果持久化：3 步实现完整执行追踪
[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 事件通道，以下行为无需任何配置变更即可生效：

# Telegram Bot 部署示例（Docker Compose）
services:
  openclaw-telegram:
    image: openclaw/cli:latest
    environment:
      - OPENCLAW_TELEGRAM_BOT_令牌=${BOT_令牌}
      - OPENCLAW_VERBOSE=full  # 启用完整工具记录
    command: ["telegram-bot", "--durable-tool-summaries"]

与嵌入式运行的对比

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 文档^[1] 了解高级配置选项

相关阅读

• OpenClaw CLI 完整命令参考^[2]
• Telegram Bot 集成指南^[3]
• AI Agent 可观测性最佳实践^[4]

参考来源

• GitHub Commit: 4ce1d78^[5] —— 功能实现的完整代码变更
• OpenClaw 官方文档^[6] —— CLI 与嵌入式运行器配置指南
• 阅读原文：OpenClaw 教学小站^[7] —— 本文原始发布地址

引用链接