Coze本地Agent从零搭建完整教程：支持本地部署的智能体拆解与实战

Coze 3.0 更新正式推出本地 Agent 支持，可对接 Claude Code、Codex CLI 等工具。这直接呼应了我此前的构想：构建一个统一调度中枢，将任务分配给多个本地 AI 编程智能体，使其以团队协作模式运行。

早在 OpenClaw 兴起时（约两个月前），我曾尝试用 Git 仓库充当任务看板，驱动多 Agent 协作，并由 Claude 协助设计了一套方案。然而，翻遍现有资料，始终未找到具体连接实现。多数文章仅寥寥数语：“只需一行命令即可连接本地 Claude Code。”

于是直接查阅官方文档，从接入本地 Agent 的界面获取了以下命令：

npx -y coze-bridge@latest --pat-token=sat_QK6PJiIoT6cN......GsZ0zj95Wetq2 --pair-code=ab0d0a......c7d19e

获取命令后，我将 coze-bridge 这个 npm 包下载并完成了全面的源码分析。其核心是一套名为 ACP（Agent Client Protocol）的协议。ACP 本质上是基于 JSON-RPC 2.0 的开放协议，用于标准化编辑器或 IDE（客户端）与 AI 编程助手（Agent）之间的通信方式。该协议的应用已超越编程领域，扩展至各类桌面或 Web 应用与 AI Agent 的交互场景。

这一发现为我的构想提供了具体实现路径：基于 ACP 协议的特性，完全可以打造一款真正的多 Agent 协同管理产品。

coze-bridge 核心功能与架构

coze-bridge 是字节跳动发布的 npm 包，当前版本 0.1.90。它的本质是本机的后台守护程序，负责将 Coze 云端的 Agent 服务与本地 AI Agent（如 Claude Code、Codex、OpenClaw）桥接。简而言之，它充当翻译器：Coze 云端使用自有的 Frontier 协议，本地 Agent 使用 ACP 协议，coze-bridge 实现两者之间的协议转换。

架构上，用户在 Coze 网页端操作，云端通过 Frontier WebSocket 下发指令；本机的 bridge 守护进程接收并解析指令，生成本地 ACP Agent 子进程执行，最终结果沿原路径返回。

守护进程生命周期管理

coze-bridge 以守护进程模式运行，通过 ~/.coze/bridge/bridge.pid 文件实现单实例锁定。启动时生成一个 detached: true 的子进程，在 127.0.0.1 的随机端口开启 HTTP IPC 服务，使用 token 进行认证。系统自启方面，支持 macOS（launchd）、Linux（systemctl）和 Windows（schtasks），覆盖三大主流平台。

配对机制与流程

配对流程清晰：CLI 携带 --pat-token 和 --pair-code 启动，若守护进程未运行则先启动，随后向本地 IPC 服务发送 POST /pair 请求。接着调用 Coze 云端的 handshake API（https://www.coze.cn），获取 deviceId，并建立 Frontier WebSocket 连接。此后每 10 秒发送一次心跳（_agent/health），并自动连接 Agent。

子进程生成机制

值得注意的是，coze-bridge 会启动全新的子进程，而非连接用户本地已运行的 Agent。它安装的是专用的 ACP wrapper 包，而非用户日常使用的 CLI 工具。因此，执行 Coze 命令时，我的 Mac 弹出了两次 Codex 对电脑有危害的提示，原因即在于此。

coze-bridge 通过 Node.js 的 child_process.spawn() 启动子进程，stdio 设置为管道模式，通过 stdin 写入命令、stdout 读取响应。

外部调用清单

ACP 协议：面向 AI Agent 的通信标准

ACP（Agent Client Protocol）是一套标准化的本地进程间通信协议，设计思路与 LSP（Language Server Protocol）类似，但专为 AI Agent 场景打造。

协议格式规范

每个数据帧是一行 JSON（ldjson，Line-Delimited JSON），通过 stdin/stdout 实现双向通信。

每帧格式示例：{"method":"session.prompt","params":{...},"id":"1"}

协议核心能力一览

协议栈层级关系

协议栈底层，ACP 在 bridge 与本地 agent 子进程之间通过 stdin/stdout 传输 ldjson 数据。上层是字节内部的 Frontier 协议，通过 WebSocket 在 Coze 云端与本机 bridge 守护进程之间传输自定义帧格式。中间的 coze-bridge 作为协议转换连接器，由于 Frontier 协议与 ACP 不兼容，bridge 的翻译作用尤为关键。

基于 ACP 的多 Agent 团队管理方案

ACP 协议的核心特性恰好解决了 Agent 团队管理中的几个关键难题：

产品架构设计思路

基于 ACP 的 Agent 团队管理产品，架构可划分为三个层次：

• 上层：产品控制面板（Web UI），涵盖任务管理、Agent 管理、监控看板、成果输出等功能。
• 中层：调度引擎（Scheduler），负责任务编排、拆解、依赖管理、并行调度与结果聚合。
• 底层：ACP Agent 池，多个 Agent 实例并行工作，例如 #1 编码（claude）、#2 设计（claude）、#3 测试（codex）、#4 审查（openclaw）等。

任务拆解与分发流程

用户提交复杂任务后，主控 Agent 首先进行任务拆解，再将子任务分发给多个专职 Agent 并行执行。例如，用户输入“开发一个用户登录模块”，主控 Agent 通过 session.prompt 接收任务，分解出子任务列表：数据库设计 → API 接口 → 前端页面 → 单元测试 → 代码审查。随后通过 ACP 并行分发给对应 Agent。

Agent 间协作机制

ACP 协议内置的 fs/read_text_file 和 fs/write_text_file 方法，允许 Agent 通过共享 workspace 文件实现间接协作。典型协作链路为：Agent #1 编写 schema.sql → Agent #2 读取 schema 编写 API → Agent #3 读取 API 编写前端 → Agent #4 读取 API 编写测试。整个协作过程完全依托文件系统作为通信媒介。

实现方案与技术挑战

分阶段实施路线图

实现该产品可大致划分为三个迭代阶段：

• MVP：启动多个 ACP Agent，提供简易 Web UI 创建任务，具备基础的任务队列能力。
• 智能调度：主控 Agent 自动拆解任务，引入 DAG 依赖管理，支持并行执行与失败重试。
• 团队协作：多用户共享 Agent 池，实时监控看板，成果自动聚合。

关键技术挑战与解决方案

总结

通过拆解 coze-bridge 的源码，我们发现一个关键事实：业内早已存在 ACP 这样的开放协议。它采用统一的 stdin/stdout ldjson 协议，使得不同厂商的 AI Agent 均可被程序化控制。这为“Agent 团队管理”从概念走向可落地的技术方案提供了坚实的基础。

我计划抽空开发一个本地管理小工具，如果大家感兴趣，欢迎在评论区讨论具体需求。

来源：互联网