# 实战记录：OpenClaw 中 ACP 后端不可用问题的排查与解决

> **时间**: 2026-02-28 12:00 - 12:56  

> **环境**: Windows 11, OpenClaw 2026.2.26, Node.js v24.13.1  

> **问题**: 尝试使用 `runtime: "acp"` 创建隔离会话时报错 "ACP runtime backend is currently unavailable"  

> **结果**: 确认为组件缺失，成功切换至 `runtime: "subagent"` 模式作为替代方案

---

## 🚨 问题现象

在 OpenClaw 中尝试创建 ACP 隔离会话时，持续报错：

```json

{

  "status": "error",

  "error": "ACP runtime backend is currently unavailable. Try again in a moment."

}

```

即使多次重启 Gateway 服务，问题依旧存在。

---

## 🔍 排查过程

### 第一阶段：配置检查

1. **读取配置文件** (`openclaw.json`)

   - 发现配置中完全缺失 `acp` 字段

   - `acpx` 插件虽在 `plugins.entries` 中标记为 `enabled: true`，但无实际后端配置

2. **尝试修复配置**

   ```json

   "acp": {

     "defaultAgent": "nvidia/nvidia/llama-3.3-nemotron-super-49b-v1.5",

     "allowedAgents": ["nvidia/nvidia/llama-3.3-nemotron-super-49b-v1.5"]

   }

   ```

   - ❌ **错误**: 使用了模型 ID 而非 Agent ID

   - ✅ **修正**: 改为 `defaultAgent: "magic"`, `allowedAgents: ["magic"]`

3. **策略报错**

   - 初期报错：`"forbidden": "ACP agent ... is not allowed by policy"`

   - 修正配置后报错变为：`"error": "ACP runtime backend is currently unavailable"`

   - **结论**: 策略配置正确，但底层服务未运行

### 第二阶段：依赖检查

1. **检查 `acpx` 安装状态**

   ```bash

   read C:/Users/fly/AppData/Roaming/npm/node_modules/acpx/package.json

   ```

   - ❌ 文件不存在 (`ENOENT`)

   - 确认 `acpx` 未正确安装

2. **安装 `acpx`**

   ```bash

   npm install -g acpx --force

   ```

   - ✅ 安装成功，版本 v0.1.13

   - 可执行文件路径：`.../node_modules/acpx/dist/cli.js`

3. **重启 Gateway**

   - 期望自动加载新安装的插件

   - ❌ 结果：依旧报 "unavailable" 错误

### 第三阶段：深入分析

1. **`acpx` 的真实身份**

   - 通过 `acpx --help` 发现：

     - `acpx` 是 **客户端工具** (Client)，用于调用 Codex/Claude/Gemini 等外部 AI

     - 并非 OpenClaw 内部的 **服务端** (Server)

   - **关键认知**: OpenClaw 的 `runtime: "acp"` 需要一个内部的 ACP Server 来接收请求，而 `acpx` 只是用来发请求的客户端

2. **尝试验证后端**

   ```bash

   openclaw acp status  # 命令存在但无响应

   acpx codex sessions new  # 尝试启动外部依赖，失败

   ```

   - 确认 OpenClaw 内部缺少 ACP Server 实现或组件未激活

---

## 💡 根本原因

**OpenClaw 当前环境缺少 ACP 运行时服务端组件。**

- `acpx` (Client) 已安装，但 OpenClaw 需要的 **ACP Server** 未安装或未激活。

- 可能的原因：

  1. OpenClaw 的 ACP 支持仍处于实验阶段，需手动安装额外插件（如 `openclaw-acp-server`）。

  2. 或者，`runtime: "acp"` 功能依赖的外部服务（如 Docker 容器或独立进程）未启动。

  3. 当前版本 (2026.2.26) 可能尚未完整实现 ACP Server。

---

## ✅ 解决方案

### 方案 A：使用 SubAgent 模式（推荐，已验证）

OpenClaw 内置的 `runtime: "subagent"` 模式可实现与 ACP 类似的隔离会话功能，且无需额外组件。

**使用方法**:

```javascript

sessions_spawn({

  task: "您的任务描述",

  runtime: "subagent",  // 替代 "acp"

  agentId: "magic",     // 使用已配置的 agent

  mode: "run"           // 或 "session"

})

```

**验证结果**:

```json

{

  "status": "accepted",

  "childSessionKey": "agent:magic:subagent:30fc086e...",

  "runId": "c5642381-..."

}

```

✅ **成功创建隔离会话**

### 方案 B：等待官方修复/安装缺失组件（长期）

1. 查阅 OpenClaw 官方文档，确认是否需要安装 `openclaw-acp-server` 插件。

2. 关注 OpenClaw 更新日志，等待 ACP Server 功能稳定。

3. 向 OpenClaw 社区反馈此问题。

---

## 📚 经验总结

### 1. 概念区分

| 组件 | 角色 | 状态 |

|------|------|------|

| `acpx` | 客户端 (Client)，调用外部 AI | ✅ 已安装 |

| ACP Server | 服务端 (Server)，OpenClaw 内部组件 | ❌ 缺失 |

| `runtime: "acp"` | 依赖 ACP Server | ❌ 不可用 |

| `runtime: "subagent"` | OpenClaw 内置隔离模式 | ✅ 可用 |

### 2. 配置陷阱

- `acp.allowedAgents` 必须使用 **Agent ID** (如 `"magic"`)，而非模型 ID (如 `"nvidia/llama-3.3..."`)。

- 配置修改后需重启 Gateway (`openclaw gateway restart` 或 `gateway.action: "restart"`)。

### 3. 排查思路

1. 先查配置 (JSON Schema 是否正确)

2. 再查依赖 (npm 包是否安装)

3. 最后查服务 (进程是否运行)

4. 善用替代方案 (SubAgent vs ACP)

---

## 🚀 后续计划

- [x] 确认 `runtime: "subagent"` 模式可用

- [ ] 监控 OpenClaw 官方文档，等待 ACP Server 支持完善

- [ ] 如有需要，协助开发 ACP Server 插件

---

> **备注**: 本文记录了一次完整的故障排查过程，从配置错误到依赖缺失，最终找到可行的替代方案。在实际生产中，优先选择稳定可用的 `subagent` 模式是明智之举。