【203篇系列】047 基于openclaw的一些使用情况

版本升级：一次“惊心动魄”的体验与背后的思考

OpenClaw的版本迭代速度，用“日新月异”来形容毫不为过。功能快速上线是好事，但随之而来的升级会引发什么，恐怕是每个用户都绕不开的“心跳时刻”。

就拿最近一次来说，Dashboard上明晃晃地挂着一个升级提醒：当前版本2026.3.1，可升级至2026.3.2。看着那个诱人的update now按钮，最终还是没忍住点了下去。

先说好消息：升级过程出奇地顺利，前后不到十分钟就完成了。但坏消息接踵而至：升级完后，界面上只剩下一个孤零零的Main Session，其他所有会话都消失了，包括至关重要的飞书通信链路也断了。

遇到这种情况怎么办？别慌，OpenClaw自家的“家庭医生”Code Buddy能派上大用场。用它检查修复，诊断结果是新版本缺失了飞书插件，并且部分配置存在冲突。虽然还有些小配置问题，但好在都不致命，修复后便能恢复正常。

这次经历其实很典型。坦率地说，OpenClaw在整体设计上的稳定性，目前还远未达到“坚若磐石”的境界。但有趣的是，为什么仍有大量开发者和团队愿意容忍这种不稳定性，并持续投入其中？这背后揭示了一个更深层的逻辑：人们真正期待的，或许不是某个工具的完美无缺，而是它所代表的高层抽象和范式潜力。这才是值得深入挖掘的价值所在。

ACPX：Agent Spawn背后的“隐形管理者”

在排查问题时，还注意到一个关于ACPX的提示。由于我需要用到Agent Spawn功能，便多研究了一下。

当Agent通过sessions_spawn工具创建子Agent时，需要有一个运行时来管理这些子Agent的生命周期。ACPX就是这个运行时后端。

工作流程

整个过程可以分解为四个清晰的步骤：

1. 发起请求：主Agent Zoe需要生成子Agent，于是调用sessions_spawn工具。
2. 配置检查：OpenClaw检查系统配置，确认后端指向了“acpx”。
3. 接管执行：ACPX正式接管，负责启动并全程管理新创建的子Agent实例。
4. 资源回收：子Agent任务执行完毕后，ACPX负责清理相关资源。

一个形象的比喻是：如果把单个Agent运行时看作一个容器，那么ACPX所扮演的角色，就类似于Docker引擎，负责容器的编排与管理。

配置说明

那么，如何判断自己的配置是否到位呢？以我当前的配置为例：

ACP核心配置：

{
  "acp": {
    "enabled": true,
    "defaultAgent": "minimax_coder"
  }
}

ACPX插件配置：

{
  "plugins": {
    "entries": {
      "acpx": {
        "enabled": true
      }
    }
  }
}

配置解读与检查：

• ✅ acp.enabled: true - ACP核心功能已启用。
• ✅ acp.defaultAgent: "minimax_coder" - 默认子Agent已指定，这是关键一步。
• ✅ acpx.enabled: true - ACPX后端运行时已就绪。

所以，启用ACP的核心门槛其实很低，两个基本配置足矣：一是打开ACP总开关，二是指定一个默认的子Agent。

使用示例

配置完成后，Zoe就可以这样调用：

{
  "task": "帮我写一个Python脚本来处理CSV文件",
  "runtime": "acp",
  "agentId": "minimax_coder",
  "mode": "session"
}

你甚至可以省去agentId，系统会自动使用默认的minimax_coder：

{
  "task": "帮我分析一下日志文件",
  "runtime": "acp",
  "mode": "run"
}

一句话总结：ACPX是实现Agent Spawn功能的基石组件。只要你按照上面两步完成了配置，就可以直接使用了。

ACP：为AI“副驾驶”铺设标准轨道

上面我们深入了解了ACPX，它本质上是ACP体系中的一个具体实现延伸。那么，什么是ACP本身？

ACP（Agent-Client Protocol）的目标非常明确：它要解决的，是AI代理与客户端应用之间“语言不通”的问题。无论是代码编辑器、IDE还是命令行终端，ACP旨在为AI助手无缝嵌入日常工作流，搭建一座标准化的通信桥梁。

???? ACP的核心思想可以概括为： 让AI代理成为你身边的“专家副驾驶”。

在这个框架下，系统被清晰地划分为两个角色：

• 客户端：这是你直接打交道的“操作台”，比如Zed、VS Code、JetBrains全家桶，或者一个简单的终端。它负责呈现界面、管理项目环境、接收你的指令。
• 代理：这是隐藏在幕后的“智慧大脑”，比如OpenClaw、Claude Code、Gemini CLI等。它负责接收任务、进行复杂的思考、规划和执行，比如编写代码、查询文档或分析数据。

理解ACP，关键不在于理解“点”，而在于理解“边”。它定义的正是Agent与Client之间的那根“连接线”——一套标准的通信协议。

协议的交互过程可以通过下图一目了然：

（这里插一句，会话这种交互形式，其普适性可能远超我们最初的想象。如果抽象来看，一次API请求又何尝不是一次短暂的会话？周末思考时对此有些模糊的想法，未来可以专门展开聊聊。）

如图所示，这套交互机制确保了合作是动态、可中断且能续传的。

在实际应用中，ACP主要支持两种工作模式：

子代理 vs. ACP：两种不同的“分身术”

在讨论多智能体协作（Swarm）时，我们经常会遇到需要一个任务由多个Agent协同完成的情况。那么这里涉及的subagent和前面讲的ACP到底是什么关系？

简单来说，subagent和ACP代表了两种截然不同的子任务运行模式。

它们的主要区别如下：

• 运行后端不同： subagent：使用OpenClaw原生的子代理运行时。 ACP：走ACP后端插件（比如acpx），专门用于对接外部的Agent Runtime（如Codex、Claude、Gemini等）。
• 默认行为不同： 调用sessions_spawn时，默认是runtime: "subagent"。如果想使用ACP模式，必须显式指定runtime: "acp"。
• 适用场景不同： subagent：更适合OpenClaw内部的任务拆分与并行执行。 ACP：目的是将任务委派给外部的、专精于编码或其他领域的代理来执行。
• 控制命令不同： subagent：有一整套/subagents ...命令族进行管理。 ACP：则使用/acp ...命令族（例如/acp spawn, /acp status, /acp doctor）。
• 会话标识不同： subagent：会话ID格式为agent::subagent:。 ACP：格式为agent::acp:。

用一句话概括二者的选择：当你需要“OpenClaw自己处理内部子任务”时，用subagent；当你需要“调用外部强大的专用Agent运行时”时，就选ACP。

持久化差异

此外，两者在持久化策略上也有显著区别。subagent的会话生命周期通常较短，可能在闲置一段时间后被系统自动清理。而ACP会话则更具韧性，往往会持续存在，直到收到明确的终止指令。

Pi Agent：一个精巧的轻量级执行引擎设计

在研究架构图时，还注意到了一个名为“Pi Agent”的组件，其标注为“编程智能体”。

Pi agent 实际上就是一个“轻量级 AEE（Agent Execution Engine）”

这个**“Pi Agent + Worker”**的分层架构设计得非常精妙。Pi Agent作为轻量的协调层，负责决策和分发，具体的重活、累活则由背后的Worker去执行。这种关注点分离的设计，清晰且高效，完全可以作为未来设计类似系统时的一个优秀参考范本。