适合人群
- 正在使用 Claude Code、Codex 等 AI 编程工具的开发者
- 对 ACP（Agent Client Protocol）协议感兴趣的架构师
- 想了解 acpx（ACP 执行器）最新功能的技术团队负责人
- 需要在 IDE 或终端中管理多个 AI Agent 的重度用户
准备清单
- 已安装 acpx 或正在评估 ACP 协议
- 了解 Claude Code、Codex 等 AI 编程工具的基本使用
- Node.js 18+ 环境
- 熟悉终端命令行操作
acpx 0.6.0 更新概览
2026 年 4 月 25 日，acpx（Agent Client Protocol 执行器）发布了 v0.6.0 版本。这是 2026 年以来最重要的更新之一，包含 7 项新功能、17 项 Bug 修复，覆盖了系统提示词定制、会话管理、WSL 支持、安全加固等核心场景。
acpx 是什么？简单说，它是一个统一的 AI Agent 运行时。通过 ACP 协议，你可以用同一套工具链驱动 Claude Code、OpenAI Codex、Pi 等不同的 AI Agent，而不需要为每个 Agent 单独配置。
重点新功能详解
1. 自定义系统提示词（System Prompt）
这是本次更新最实用的功能。新增两个全局参数：
--system-prompt <text>：完全替换 Claude Code 的默认系统提示词--append-system-prompt <text>：在默认提示词基础上追加内容
实际用途：
# 给 Claude Code 追加你的项目规范
acpx claude --append-system-prompt "本项目使用 TypeScript strict 模式，所有函数必须有返回类型注解"
# 完全替换系统提示词（高级用户）
acpx claude --system-prompt "你是一个专注于代码审查的 AI 助手..."
关键细节：自定义的提示词会持久保存在会话中。即使会话被复用或恢复，你的自定义提示词也不会丢失。这个功能目前只对 Claude Code 有效，Codex 等其他 Agent 会忽略这个参数。
使用场景举例：
- 团队统一编程规范：在系统提示词中定义代码风格和架构约定
- 项目上下文注入：把项目的技术栈、目录结构等信息写进提示词
- 角色定制：让 Claude Code 专注于代码审查、测试生成等特定任务
2. 会话清理工具（sessions prune）
长期使用 acpx 会积累大量已关闭的会话记录。v0.6.0 新增了 sessions prune 命令来清理这些历史数据。
# 先预览会被清理的会话（不实际删除）
acpx sessions prune --dry-run
# 清理 7 天前的已关闭会话
acpx sessions prune --age 7d
# 同时清理事件流历史（更彻底）
acpx sessions prune --age 7d --include-history
这个功能对服务器上长期运行 acpx 的场景特别有用，可以防止磁盘占用持续增长。
3. 嵌入式运行时 Turn 句柄（startTurn）
v0.6.0 为嵌入 acpx 运行时的应用（如 IDE 插件）新增了 startTurn() API。
以前嵌入器只能通过 runTurn() 等待完整结果。现在可以用 startTurn() 单独观察实时事件流，还能中途取消一个 Turn，而不影响底层的 runTurn() 兼容性。
对普通用户的影响： IDE 插件（如 VS Code 扩展）可以更流畅地显示 AI 的实时输出，支持中途取消操作，体验更接近 ChatGPT 网页版的流式输出。
4. 禁用终端能力（--no-terminal）
新增 --no-terminal 参数，可以在启动新 Agent 时禁用其终端能力。
# 启动一个没有终端执行权限的 Agent（更安全）
acpx claude --no-terminal
适合以下场景：
- 在 CI/CD 环境中使用 AI Agent，不希望它执行任意命令
- 给团队成员使用 AI 助手，但限制其系统级操作能力
- 安全审计要求
5. 内置 Agent 版本升级
acpx 内置的三个 Agent 适配器都更新到了最新版本：
@agentclientprotocol/claude-agent-acp：Claude Code 适配器@zed-industries/codex-acp：OpenAI Codex 适配器pi-acp：Pi 适配器
新安装的 acpx 会自动使用最新版本的适配器。
6. ACP 后置消息处理
新增了 session/prompt 完成后的消息排空机制。
以前某些 Agent 在回复完成后还会发出额外的工具更新消息，这些消息会被丢弃。v0.6.0 会正确捕获这些"迟到"的消息，确保输出完整。
重要修复
配置持久化
修复了一个恼人的 Bug：之前像 Codex 的 reasoning_effort 这类配置选项，在会话被复用时会丢失。v0.6.0 会正确持久化和重放所有非 mode 类型的配置选项。
模型选择修复
--model 参数现在在向已有的持久会话发送 prompt 时也能正确生效了。之前这个参数只在新建会话时有效。
WSL 路径转换
Windows Subsystem for Linux 用户有福了。v0.6.0 会在 WSL 环境下自动用 wslpath 转换工作目录路径，让运行在 Windows 侧的 Agent（如 .exe 文件）能正确访问 WSL 中的项目目录。
安全加固
两个重要的安全修复：
- 队列目录权限收紧：IPC socket 和持久队列目录现在限制为仅所有者可访问，包括之前创建的权限过宽的目录
- 加密随机 Owner ID：队列 Owner 的生成 ID 改用加密安全的随机数，防止快速重启时 ID 复用
认证修复
acpx 现在要求显式设置 ACPX_AUTH_* 环境变量或在配置文件中指定认证方式。以前环境中的 OPENAI_API_KEY 等变量可能意外触发 Codex 适配器的登录流程，这个行为已被修正。
错误信息改进
常见的错误场景现在都有清晰的文字提示：
- 认证失败
- 会话不存在
- ACP 会话错误
- 超时
- 速率限制
- 无效模型名
JSON 格式的错误输出保持不变，文字提示只在终端模式下显示。
Token 使用统计
quiet 模式下，如果适配器返回了 Token 使用量和费用信息，acpx 会将这些数据输出到 stderr，同时保持 stdout 只包含 AI 的回复文本。
升级指南
从旧版本升级
# 全局安装最新版
npm install -g @openclaw/acpx@latest
# 验证版本
acpx --version
# 应输出 0.6.0
# 清理旧会话（可选但推荐）
acpx sessions prune --dry-run
acpx sessions prune --age 30d
全新安装
# 安装
npm install -g @openclaw/acpx
# 启动 Claude Code
acpx claude
# 启动 Codex
acpx codex
# 查看所有可用 Agent
acpx agents list
配置认证
# 方法一：环境变量
export ACPX_AUTH_ANTHROPIC_API_KEY="sk-ant-..."
export ACPX_AUTH_OPENAI_API_KEY="sk-..."
# 方法二：配置文件（~/.acpx/config.json）
{
"auth": {
"anthropic": { "apiKey": "sk-ant-..." },
"openai": { "apiKey": "sk-..." }
}
}
配合 Claude Pro 订阅 使用可以获得完整的 Claude Code 体验。
完整变更清单
新增功能（7 项）
--system-prompt/--append-system-prompt系统提示词自定义sessions prune会话清理工具startTurn()嵌入式运行时 Turn 句柄--no-terminal禁用终端能力- 内置 Agent 适配器版本升级
- ACP 后置消息排空机制
- 会话身份标识文档完善
修复（17 项）
- 配置选项持久化和重放
--model参数在持久会话中生效- 持久会话连接池保活和关闭
- 后置 session 更新消息不丢失
- 运行时控制操作复用已有会话
- 活跃 prompt 的历史记录正确保存
- WSL 路径自动转换
- 认证方式显式化
- 自定义 Agent 参数正确传递
- 队列目录权限收紧
- Owner ID 加密随机化
- 错误信息文字提示改进
- quiet 模式 Token 统计输出
- 空闲持久会话状态正确报告
- ACP SDK 关闭 API 兼容
- doctor 诊断详情类型安全
- Replay 文件读取路径安全
常见问题
Q: acpx 和 Claude Code 是什么关系？
Claude Code 是 Anthropic 的 AI 编程助手，acpx 是一个统一的 Agent 运行时。通过 acpx 你可以用同一套工具链驱动 Claude Code、Codex 等多个 AI Agent。acpx 不是 Claude Code 的替代品，而是它的"多 Agent 管理层"。
Q: 升级到 0.6.0 需要注意什么？
没有破坏性变更，可以直接升级。建议升级后运行 acpx sessions prune --dry-run 检查一下是否有需要清理的旧会话。认证方式从自动检测改为显式配置，如果你之前依赖环境变量自动识别，升级后需要确认认证配置正确。
Q: --system-prompt 和 CLAUDE.md 文件有什么区别？
CLAUDE.md 是项目级别的配置文件，放在项目根目录，每次打开项目自动加载。--system-prompt 是命令行级别的参数，更灵活——可以用于临时测试、CI/CD 环境或不同场景的快速切换。两者可以配合使用。
Q: sessions prune 会删除正在使用的会话吗？
不会。prune 只清理已关闭的会话。建议先用 --dry-run 预览，确认无误后再执行。
Q: WSL 用户需要做什么额外配置吗？
不需要。v0.6.0 会自动检测 WSL 环境并用 wslpath 转换路径。只要你的 acpx 运行在 WSL 中，调用 Windows 侧的 Agent 时路径会自动处理。
参考来源
下一步建议
- 刚接触 Claude Code？→ Claude Code 完整安装教程
- 想在国内使用？→ Claude Code 国内配置教程
- 想了解 MCP 协议？→ Claude Code MCP 配置指南
- 想了解 Claude 订阅方案？→ Claude Pro vs API 费用对比
- 需要 Claude Pro？→ Claude Pro 月卡