【AI大模型】OpenClaw接入OpenCode可行性调研

概述

调研 OpenClaw 接入 OpenCode（AI Coding 环境）的可行性方案，基于 OpenClaw 官方文档（ACP 协议、MCP 协议、Codex Harness）与 OpenCode 已知集成模式，分析三条核心集成路径并给出可执行的操作步骤。

相关说明

调研时间：2026-05-17

信息来源：OpenClaw 官方文档（docs.openclaw.ai）+ 技术推理

OpenCode 背景：TheBrowserCompany 开发的开源 AI Coding 终端工具（推测，基于同名生态与 OpenClaw 的命名关联）

⚠️ OpenCode 详情未能通过 Web 搜索确认，以下分析基于 OpenClaw 现有集成机制的类推

[toc]

1. 前置背景

1.1 OpenClaw 的三种核心集成协议

OpenClaw 支持三种对外集成协议，理解它们是方案设计的前提：

协议	方向	OpenClaw 角色	文档入口	典型客户端
ACP（Agent Client Protocol）	IDE ↔ OpenClaw	ACP 服务器	`cli/acp`	Zed, Codex (`acpx openclaw`), Claude Code
MCP（Model Context Protocol）	工具 ↔ OpenClaw	MCP 服务器或 MCP 客户端注册表	`cli/mcp`	Claude Desktop, Cursor, VS Code
Codex Harness	OpenAI 代理 ↔ OpenClaw	Codex 运行载体	`plugins/codex-harness`	ChatGPT/Codex 订阅

1.2 OpenClaw 的 Agent 运行时体系

text

OpenClaw Gateway（会话路由 + 渠道接入）
    ├── PI harness（内置 AI 运行时）
    ├── Codex harness（通过 Codex app-server）
    └── ACP harness（外部 ACP 客户端接入）

关键模型引用约定：

openai/gpt-* → 通过 Codex harness（当 codex 插件启用时）
anthropic/claude-* → 通过 PI harness
agentRuntime.id: "codex" → 显式强制走 Codex 运行时
agentRuntime.id: "pi" → 显式强制走 PI 运行时

2. OpenCode 可能的产品定位

⚠️ 说明：由于 Web 搜索未能获取 OpenCode 官方资料，以下基于 OpenClaw 生态命名规律与现有 AI Coding 工具形态的合理推断。

基于以下观察：

OpenClaw + OpenCode 命名高度相似，大概率同源（TheBrowserCompany）
OpenClaw 文档中已存在 acpx openclaw 与 Codex、Claude Code 的集成案例
Zed 编辑器通过 ACP 桥接 OpenClaw 的方案已在官方文档中记录

OpenCode 可能的定位：

开源、终端优先的 AI Coding 工具
支持 ACP 或 MCP 作为通信协议
与 OpenClaw 形成「IDE 端 ↔ 网关端」的分工协作

📌 建议：向 OpenCode 官方确认其使用的通信协议（推荐 ACP），以便选择最优集成路径。

3. 三大集成方案

方案 A：通过 ACP 桥接（推荐）

原理：openclaw acp 是 OpenClaw 官方提供的 IDE 集成路径，Claude Code、Codex 均有成熟案例。

text

OpenCode（ACP 客户端）
    │
    │  stdio (ACP 协议)
    ▼
openclaw acp
    │
    │  WebSocket
    ▼
OpenClaw Gateway
    │
    ├── 会话路由 → WeChat / Telegram / Discord 等渠道
    └── AI 运行时 → PI / Codex

操作步骤

Step 1：确认 OpenCode 支持 ACP 协议

在 OpenCode 配置文件中检查是否有类似以下配置：

json

{
  "agent_servers": {
    "openclaw": {
      "command": "openclaw",
      "args": ["acp"]
    }
  }
}

Step 2：配置 OpenClaw Gateway 访问凭证

bash

# 方式 1：配置持久化
openclaw config set gateway.remote.url wss://127.0.0.1:18789
openclaw config set gateway.remote.token-file ~/.openclaw/gateway.token
 
# 方式 2：命令行直接指定
openclaw acp --url wss://127.0.0.1:18789 --token-file ~/.openclaw/gateway.token

Step 3：指定目标 Agent

bash

# 路由到主 Agent
openclaw acp --session agent:main:main
 
# 路由到特定 Agent（如有多个）
openclaw acp --session agent:codex:main

Step 4：重启 Gateway

bash

openclaw gateway restart

配置示例（OpenCode 配置文件）

json

{
  "agents": {
    "openclaw": {
      "command": "env",
      "args": [
        "OPENCLAW_HIDE_BANNER=1",
        "openclaw",
        "acp",
        "--url", "wss://127.0.0.1:18789",
        "--token-file", "~/.openclaw/gateway.token",
        "--session", "agent:main:main"
      ]
    }
  }
}

✅ 优点

OpenClaw 官方推荐路径，文档完善
Codex、Claude Code 已有成功案例
支持会话持久化（--session-label）
支持 /acp spawn 在 OpenClaw 内部运行外部 Agent

⚠️ 缺点

要求 OpenCode 必须支持 ACP 协议

方案 B：通过 MCP 桥接

原理：openclaw mcp serve 将 OpenClaw 暴露为 MCP 服务器，支持标准 MCP 客户端（如 Claude Desktop、Cursor）。

text

OpenCode（MCP 客户端）
    │
    │  stdio（MCP 协议）
    ▼
openclaw mcp serve --url wss://127.0.0.1:18789 --token-file ~/.openclaw/gateway.token
    │
    │  WebSocket
    ▼
OpenClaw Gateway

MCP 暴露的工具

工具	功能
`conversations_list`	列出最近的会话
`conversation_get`	获取单个会话详情
`messages_read`	读取历史消息
`messages_send`	通过原渠道发送回复
`events_poll` / `events_wait`	实时事件轮询
`permissions_list_open`	列出待审批请求
`permissions_respond`	响应审批请求

操作步骤

Step 1：在 OpenCode 的 MCP 客户端配置中添加

json

{
  "mcpServers": {
    "openclaw": {
      "command": "openclaw",
      "args": [
        "mcp",
        "serve",
        "--url", "wss://127.0.0.1:18789",
        "--token-file", "~/.openclaw/gateway.token"
      ]
    }
  }
}

Step 2：启用 Claude 通知模式（如 OpenCode 支持）

bash

openclaw mcp serve --claude-channel-mode on

Step 3：重启 Gateway 并验证

bash

openclaw mcp list

✅ 优点

MCP 是开放标准，生态成熟
不要求 OpenCode 专门支持 ACP
安全边界清晰（只暴露已有路由的会话）

⚠️ 缺点

MCP 工具集偏向「消息读写」而非「AI Coding 操作流」
不如 ACP 方案深度集成

方案 C：OpenClaw 内部通过 acpx 调度 OpenCode

原理：如果 OpenCode 也支持 acpx，可以直接在 OpenClaw 内部通过 /acp spawn 调度 OpenCode 处理任务。

bash

/acp spawn opencode --cwd /path/to/project "分析当前代码库的漏洞"

这属于 OpenClaw 作为 ACP Agent Host 的场景：

text

OpenClaw Gateway
    │
    ├── /acp spawn opencode
    │
    └── acpx opencode exec "..."
        │
        └── OpenCode（作为 ACP 客户端处理任务）

✅ 优点

在 OpenClaw 内部直接调度 OpenCode
可以通过 OpenClaw 渠道（微信等）触发 OpenCode 任务

⚠️ 缺点

依赖 OpenCode 支持 acpx 协议
需要验证 OpenCode 是否发布 acpx 适配器

4. 安全与权限考量

4.1 ACP 桥的安全模型

控制层	说明
Gateway Token	ACP 客户端必须持有有效 Token
会话隔离	默认 `acp:<uuid>` 独立会话，可指定 `agent:main:main` 共享主会话
exec 审批	危险操作触发 `session/request_permission`，在 OpenClaw 侧审批
环境变量隔离	ACP 运行时子进程设置 `OPENCLAW_SHELL=acp`

4.2 MCP 桥的安全模型

控制层	说明
路由限制	只暴露 Gateway 已有的路由会话，无法主动发起新会话
Token 认证	同样需要 Gateway Token
env 安全过滤	stdio MCP 服务器启动时，OpenClaw 会过滤 `NODE_OPTIONS`、`PYTHONPATH` 等危险环境变量
审批工具	`permissions_respond` 允许批准/拒绝待处理操作

4.3 建议安全配置

json5

{
  // 最小权限原则：为 OpenCode 创建专用 Agent
  agents: {
    list: [
      {
        id: "main",
        default: true,
        model: "anthropic/claude-opus-4-6",
      },
      {
        id: "opencode-bridge",
        name: "OpenCode Bridge",
        model: "openai/gpt-5.5",  // 通过 Codex 运行时
      },
    ],
  },
}

5. 最佳实践建议

5.1 推荐集成路径

text

优先级排序：
1. ✅ 方案 A（ACP 桥接）—— OpenClaw 官方推荐，Codex/Claude Code 已有案例
2. 🔶 方案 B（MCP 桥接）—— 开放标准，适合 MCP-first 的客户端
3. 🔶 方案 C（acpx 调度）—— 仅当 OpenCode 原生支持 acpx 时考虑

5.2 验证步骤

确认 OpenCode 通信协议：检查 OpenCode 是否支持 ACP 或 MCP

本地测试：

bash

# ACP 测试
openclaw acp client --cwd /path/to/project
 
# MCP 测试
openclaw mcp serve --verbose

会话绑定：

bash

# 绑定到主 Agent 会话
openclaw acp --session agent:main:main

监控 Gateway 日志：
bash
```
openclaw gateway logs --follow
```

5.3 OpenClaw 侧增强配置

如果需要增强 OpenCode 的 AI Coding 能力，可以在 OpenClaw 侧启用 Codex harness：

json5

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
  agents: {
    defaults: {
      model: "openai/gpt-5.5",  // 通过 Codex 运行
    },
    list: [
      {
        id: "opencode-bridge",
        model: "openai/gpt-5.5",
      },
    ],
  },
}

6. 待确认事项

编号	问题	优先级	状态
Q1	OpenCode 使用哪种通信协议（ACP / MCP / 其他）？	🔴 高	⏳ 待确认
Q2	OpenCode 是否提供 acpx 适配器？	🟡 中	⏳ 待确认
Q3	OpenCode 是否支持 `--session` 参数指定目标会话？	🟡 中	⏳ 待确认
Q4	OpenCode 的 MCP 工具集支持哪些工具？	🟡 中	⏳ 待确认

7. 参考资料

来源	链接	关键内容
OpenClaw 官方文档	https://docs.openclaw.ai	完整文档索引
ACP 协议	https://docs.openclaw.ai/cli/acp	IDE 集成标准路径
MCP 协议	https://docs.openclaw.ai/cli/mcp	MCP 服务/客户端配置
Codex Harness	https://docs.openclaw.ai/plugins/codex-harness	Codex 运行时配置
Codex Harness 参考	https://docs.openclaw.ai/plugins/codex-harness-reference	完整配置字段
ACP Agents	https://docs.openclaw.ai/tools/acp-agents	ACP Agent 调度
acpx openclaw	https://docs.openclaw.ai/cli/acp#use-from-acpx-codex-claude-other-acp-clients	Codex/Claude Code 接入案例
Zed ACP 配置	https://docs.openclaw.ai/cli/acp#zed-editor-setup	Zed 编辑器 ACP 集成参考
Agent Client Protocol	https://agentclientprotocol.com	ACP 协议规范

8. 下一步行动

向 OpenCode 官方/社区确认其支持的通信协议
在本地使用 openclaw acp client 进行 ACP 协议自测
确认 OpenCode 是否为 TheBrowserCompany 产品（如果是，可参考 Codex 集成模式）
待 OpenCode 协议确认后，更新本文档并输出可执行配置

更新记录

2026-05-17：初稿，基于 OpenClaw 官方文档 + 技术推理撰写

tags	ai, openclaw, opencode, mcp, acp, 集成
aliases	OpenClaw OpenCode集成

小M-Quartz

探索

【AI大模型】OpenClaw接入OpenCode可行性调研

1. 前置背景

1.1 OpenClaw 的三种核心集成协议

1.2 OpenClaw 的 Agent 运行时体系

2. OpenCode 可能的产品定位

3. 三大集成方案

方案 A：通过 ACP 桥接（推荐）

操作步骤

配置示例（OpenCode 配置文件）

✅ 优点

⚠️ 缺点

方案 B：通过 MCP 桥接

MCP 暴露的工具

操作步骤

✅ 优点

⚠️ 缺点

方案 C：OpenClaw 内部通过 acpx 调度 OpenCode

✅ 优点

⚠️ 缺点

4. 安全与权限考量

4.1 ACP 桥的安全模型

4.2 MCP 桥的安全模型

4.3 建议安全配置

5. 最佳实践建议

5.1 推荐集成路径

5.2 验证步骤

5.3 OpenClaw 侧增强配置

6. 待确认事项

7. 参考资料

8. 下一步行动

关系图谱

目录

反向链接