企业官网建设流程全解析

goose ACP Providers 实战指南：用 Claude Code、Codex、Amp 等 ACP 智能体作为 goose 模型提供者

【免费下载链接】goosean open source, extensible AI agent that goes beyond code suggestions - install, execute, edit, and test with any LLM项目地址: https://gitcode.com/GitHub_Trending/goose3/goose

goose 支持将实现 Agent Client Protocol（ACP）的编码智能体（如 Claude Code、Codex CLI、Amp）作为 provider 接入，替代传统按 token 计费的 API 调用方式。本文将基于当前仓库的官方指南与对应源码实现，完整讲解四个 ACP provider（Amp / Claude / Codex / Pi）的安装配置、环境变量与权限模式映射、扩展透传机制，以及 goose 侧 ACP provider 的底层工作方式与故障排查方法。读完本文，你可以用现有订阅零 token 成本驱动 goose，并理解 goose 如何将扩展作为 MCP 服务器传给 ACP 智能体、如何把GOOSE_MODE映射到各智能体的会话模式。

ACP Providers 是什么

ACP 是一种与编码智能体通信的标准协议，社区维护着一个持续增长的 ACP 智能体注册表。goose 通过 ACP provider 让上述智能体直接充当"模型层"：goose 启动一个 ACP 适配器子进程，通过 ACP 协议与其会话，智能体的每一次文本、思考、工具调用与权限请求都以流式更新的形式回传给 goose 的会话层。

接入 ACP provider 的核心价值是复用现有订阅：Claude Code 订阅、ChatGPT Plus/Pro 或 OpenAI API 额度、Amp 订阅都可以直接驱动 goose，无需为每次调用支付按 token 计算的 API 费用。官方文档明确指出，ACP providers 是已废弃的 CLI providers（cli-providers）的推荐替代方案。

同时需要注意两个已知限制：

• 暂不支持会话分叉或恢复：可以开启新会话，但goose session resume和goose session fork目前不可用；
• ACP 会话 ID 与 goose 会话 ID 不同：跨两侧的遥测字段可能无法关联。

可用的 ACP Provider 一览

当前仓库内置了四个 ACP provider，每个 provider 都由一个独立的 Rust 文件实现，且共用同一个核心类型AcpProvider（定义在 acp/provider.rs）：

各 provider 的通用要求：

• Node.js 和 npm：用于运行以 npm 分发的 ACP 适配器；
• 对应的 ACP 适配器已全局安装，并且二进制在 PATH（或 npm 全局 bin 目录）中可解析；
• 底层 CLI 已完成认证：amp、claude、codex、pi命令本身能够正常工作；
• 订阅额度未超限。

源码层面的一个细节是：各 provider 在解析适配器可执行文件时都使用了SearchPaths::builder().with_npm().resolve(...)，显式把 npm 全局 bin 目录加入搜索路径（见 claude_acp.rs 中from_env_with_working_dir的实现）。这是针对桌面应用场景的设计——桌面应用的进程 PATH 可能不包含 npm 全局 bin 目录，加入后npm install -g安装的适配器才能被找到。

各 Provider 安装与配置

Amp ACP

# 1. 安装 Amp CLI curl -fsSL https://ampcode.com/install.sh | bash # 2. 安装 ACP 适配器 npm install -g amp-acp # 3. 认证：运行 amp 并按提示完成登录 # 4. 配置 goose export GOOSE_PROVIDER=amp-acp

也可以改用goose configure交互式完成 provider 配置。源码中 Amp provider 的元数据（amp_acp.rs）将上述步骤固化为setup_steps，goose 的 provider 目录界面会直接展示这些安装指引。

Claude ACP

# 1. 安装 ACP 适配器 npm install -g @agentclientprotocol/claude-agent-acp # 2. 确认 Claude CLI 已认证（运行 claude 验证） # 3. 配置 goose export GOOSE_PROVIDER=claude-acp

通过goose configure配置时的交互流程示例：

┌ goose-configure │ ◇ What would you like to configure? │ Configure Providers │ ◇ Which model provider should we use? │ Claude Code │ ◇ Model fetch complete │ ◇ Enter a model from that provider: │ default

Codex ACP

# 1. 检查已安装的包版本 codex-acp --version

输出应以@agentclientprotocol/codex-acp开头。如果不是，说明装的是旧包@zed-industries/codex-acp，需要替换：

# 2. 卸载旧包 npm uninstall -g @zed-industries/codex-acp # 3. 安装正确的包 npm install -g @agentclientprotocol/codex-acp

然后认证并配置：

# 4. 运行 codex 完成 OpenAI 认证（可复用已有 Codex 登录态） export GOOSE_PROVIDER=codex-acp export GOOSE_MODEL=current # current 表示让 Codex 选择其默认模型

需要注意：替换 npm 包不会改动~/.codex配置，也不需要重建 goose 配置，goose 也不会自动替你替换该包。上述"先--version检查、再按需替换"的步骤同样固化在 codex_acp.rs 的setup_steps元数据中。

Pi ACP

# 1. 按项目说明安装 pi CLI 与 pi-acp 适配器 # 2. 运行 pi 完成认证 # 3. 配置 goose export GOOSE_PROVIDER=pi-acp

Pi provider 的元数据带有show_only_when_installed()标记（见 pi_acp.rs），即在 goose 的 provider 选择界面中，只有检测到本机安装了 Pi 相关二进制时才显示该选项。

使用示例

基础用法

goose session

启动交互式会话。goose 检测到GOOSE_PROVIDER指向某个 ACP provider 后，会启动对应适配器、建立 ACP 会话，然后把后续提示词转发给智能体。

带扩展使用（扩展透传）

ACP provider 的关键能力之一：通过--with-extension（stdio 扩展）或--with-streamable-http-extension（HTTP 扩展）配置的 goose 扩展会被直接作为 MCP 服务器传递给 ACP 智能体，智能体因此可以调用你的扩展工具：

GOOSE_PROVIDER=claude-acp goose run \ --with-extension 'npx -y @modelcontextprotocol/server-everything' \ -t 'Use the echo tool to say hello'

GOOSE_PROVIDER=codex-acp goose run \ --with-streamable-http-extension 'https://mcp.kiwi.com' \ -t 'Search for flights from BKI to SYD tomorrow'

这个透传机制在源码中对应 acp/provider.rs 的extension_configs_to_mcp_servers函数：它将 goose 的ExtensionConfig逐项转换为 ACP 协议的McpServer描述——StreamableHttp扩展变成带自定义 headers 的McpServer::Http，Stdio扩展变成带命令、参数和环境变量的McpServer::Stdio。随后还有一个filter_supported_servers步骤：如果智能体在 ACP 握手时声明不支持 HTTP MCP，HTTP 服务器会被跳过并输出 debug 日志；SSE 类型的服务器则一律跳过，因为 ACP 智能体侧不支持。这解释了为什么透传只覆盖--with-extension和--with-streamable-http-extension两种类型。

配置选项与权限模式映射

四个 provider 共享一组环境变量：

各 provider 的模型默认值：

模型选择如何到达智能体（current哨兵）

current不是普通的模型名，而是源码中的哨兵常量ACP_CURRENT_MODEL（acp/provider.rs 中pub const ACP_CURRENT_MODEL: &str = "current"）。它在connect()阶段被解析为智能体实际提供的模型名。对于通过配置选项选择模型的智能体（Claude、Codex、Pi 都在其AcpProviderConfig中设置了model_config_option_id: Some("model")），goose 在每次流式请求前会调用apply_model_if_changed：当会话活跃模型与已应用模型不同且不是current时，才发送一次session/set_config_option把模型选项重新下发，避免冗余调用。

一个容易踩坑的行为在 acp/mod.rs 的configured_model_for_provider函数中：只有当前激活的 provider 才是该 ACP provider 时才读取GOOSE_MODEL，否则回落到current。该函数的单元测试（configured_model_is_not_reused_for_another_provider）明确验证了这一点——比如配置了GOOSE_PROVIDER=openai、GOOSE_MODEL=gpt-5时，查询copilot-acp的模型会得到current而不是gpt-5，防止 A 智能体的模型名被错误套用到 B 智能体上。

Claude ACP 的权限模式映射

GOOSE_MODE的四种取值在 Claude provider 中被映射为 Claude Code 的会话模式（源码映射见 claude_acp.rs）：

源码中的注释解释了每条映射的意图：bypassPermissions最接近"自主"，Claude Code 的default对应"危险操作前询问"，acceptEdits自动接受编辑但保留危险操作提示，plan模式禁用工具执行，与 goose 的 chat-only 意图对齐。

Codex ACP 的权限模式映射

该映射硬编码在 codex_acp.rs 的mode_mapping中。与 Claude 不同的是，Codex 在approve和chat两档都落到read-only。此外，Codex provider 对GOOSE_MODE的解析更严格：未配置时默认auto（resolve_goose_mode把NotFound错误折叠为Auto），但非法取值会在启动适配器之前直接报错，而不是带错启动子进程——这一行为有专门的集成测试goose_mode_validation_precedes_codex_acp_launch验证，它用一个标记脚本充当假的codex-acp可执行文件，断言非法GOOSE_MODE下子进程根本不会被拉起。

Amp ACP 与 Pi ACP 的模式映射

Amp 的映射相对简单（见 amp_acp.rs）：auto→bypass（跳过确认），approve、smart-approve、chat均 →default。Pi provider 的mode_mapping为空，即不做模式映射，会话以智能体自身默认模式运行。

从源码结构看，AcpProvider::update_mode在切换模式时会先从映射表取出候选模式 ID，再通过select_mode_id与智能体实际声明的available_modes求交集——只有智能体真实提供的模式才会被下发；如果智能体支持mode配置选项，则走session/set_config_option，否则走session/set_mode。

底层工作方式：AcpProvider 的连接与流式处理

四个 provider 的from_env_with_working_dir最终都构造同一个配置结构AcpProviderConfig并调用AcpProvider::connect（acp/provider.rs）。该结构的核心字段为：

• command/args/env：适配器进程的可执行文件、参数与环境变量；
• env_remove：需要从环境中剔除的变量。例如 Claude provider 特意移除了CLAUDECODE变量，注释说明是为了防止 claude-agent-acp（它包装 Claude Code）误检测到嵌套会话；
• mcp_servers：由扩展透传转换而来的 MCP 服务器列表；
• session_mode_id/mode_mapping：初始模式与GOOSE_MODE映射；
• model_config_option_id：用于下发模型选择的配置选项 ID（"model"）。

连接过程（connect→start）的关键步骤：

1. 在一个专用 OS 线程中构建独立的 tokio 运行时并启动 ACP 客户端循环（因为 tokio 的 I/O 句柄不能跨运行时移动）；
2. 完成initialize握手，等待InitializeResponse；
3. 立即创建 ACP 会话（NewSession），把会话 ID 保存在 provider 实例中——这意味着 goose 侧每次与 ACP provider 建连都会获得一个全新的智能体会话，这也是文档中"session ID 与 goose 不同、遥测难以关联"这一限制的来源。

后续的每一轮stream调用：先按需下发模型与思考强度配置选项，再把对话转成 ACP 提示词块发出，然后把智能体的流式更新（Text、Thought、ToolCallStart、ToolCallComplete、PermissionRequest等）逐条转换为 goose 的消息流。工具调用会被标记external_dispatch，告知 goose 的智能体循环不要重复分发该调用——因为真正执行工具的是 ACP 智能体自己。权限确认则通过pending_confirmations映射表与 goose 的 ActionRequired 机制对接：智能体的requestPermission请求挂起等待，goose 侧的用户决策经handle_permission_confirmation回传。

错误处理与故障排查

ACP provider 依赖外部二进制，排障时按以下顺序检查：

1. 适配器二进制在 PATH 中可找到：amp-acp、claude-agent-acp、codex-acp、pi-acp（which <binary>验证）。若 goose 找不到二进制，会话启动会直接失败；
2. 底层 CLI 已认证且可用：分别运行amp/claude/codex/pi确认登录态；
3. 订阅限额未超；
4. npm-distributed 适配器需要 Node.js 与 npm 已安装。

源码中对常见错误的分类处理值得了解（acp/mod.rs 与 acp/provider.rs）：

• 认证错误：is_auth_required会遍历错误链，识别 ACP 协议错误码AuthRequired，转换为ProviderError::Authentication，让上层给出"需要重新认证"的明确提示而不是泛化的请求失败；
• 额度耗尽：常量CREDITS_EXHAUSTED_REASON = "credits_exhausted"写在 ACP 会话错误响应的data.reason中，由 ACP 服务器侧设置、provider 侧读取，用于把"账号余额花光"与"智能体拒绝提示词"区分开。

小结

ACP providers 让 goose 从"调 API"扩展到"驱动任意 ACP 编码智能体"：四个内置适配器（Amp / Claude / Codex / Pi）共享同一套AcpProvider核心实现，差异只体现在可执行文件解析、GOOSE_MODE模式映射表、模型下发方式和env_remove等细节上。配置层面记住三个环境变量即可：GOOSE_PROVIDER选择适配器、GOOSE_MODEL（默认current/default）选择模型、GOOSE_MODE控制权限档位；扩展则通过--with-extension/--with-streamable-http-extension以 MCP 服务器形式透传给智能体。当前限制是暂不支持goose session resume/goose session fork，且 ACP 会话 ID 与 goose 会话 ID 相互独立。

【免费下载链接】goosean open source, extensible AI agent that goes beyond code suggestions - install, execute, edit, and test with any LLM项目地址: https://gitcode.com/GitHub_Trending/goose3/goose