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

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/goosegoose 支持将实现 Agent Client ProtocolACP的编码智能体如 Claude Code、Codex CLI、Amp作为 provider 接入替代传统按 token 计费的 API 调用方式。本文将基于当前仓库的官方指南与对应源码实现完整讲解四个 ACP providerAmp / 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 providerscli-providers的推荐替代方案。同时需要注意两个已知限制暂不支持会话分叉或恢复可以开启新会话但goose session resume和goose session fork目前不可用ACP 会话 ID 与 goose 会话 ID 不同跨两侧的遥测字段可能无法关联。可用的 ACP Provider 一览当前仓库内置了四个 ACP provider每个 provider 都由一个独立的 Rust 文件实现且共用同一个核心类型AcpProvider定义在 acp/provider.rsProvider 名称包装的适配器底层智能体认证方式实现文件amp-acpamp-acpnpm 包AmpAmp 账号amp_acp.rsclaude-acpclaude-agent-acpClaude CodeAnthropic 账号claude_acp.rscodex-acpcodex-acpCodex CLIOpenAI 账号 / API 额度codex_acp.rspi-acppi-acpPiPi 账号pi_acp.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_PROVIDERamp-acp也可以改用goose configure交互式完成 provider 配置。源码中 Amp provider 的元数据amp_acp.rs将上述步骤固化为setup_stepsgoose 的 provider 目录界面会直接展示这些安装指引。Claude ACP# 1. 安装 ACP 适配器 npm install -g agentclientprotocol/claude-agent-acp # 2. 确认 Claude CLI 已认证运行 claude 验证 # 3. 配置 goose export GOOSE_PROVIDERclaude-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: │ defaultCodex 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_PROVIDERcodex-acp export GOOSE_MODELcurrent # 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_PROVIDERpi-acpPi provider 的元数据带有show_only_when_installed()标记见 pi_acp.rs即在 goose 的 provider 选择界面中只有检测到本机安装了 Pi 相关二进制时才显示该选项。使用示例基础用法goose session启动交互式会话。goose 检测到GOOSE_PROVIDER指向某个 ACP provider 后会启动对应适配器、建立 ACP 会话然后把后续提示词转发给智能体。带扩展使用扩展透传ACP provider 的关键能力之一通过--with-extensionstdio 扩展或--with-streamable-http-extensionHTTP 扩展配置的 goose 扩展会被直接作为 MCP 服务器传递给 ACP 智能体智能体因此可以调用你的扩展工具GOOSE_PROVIDERclaude-acp goose run \ --with-extension npx -y modelcontextprotocol/server-everything \ -t Use the echo tool to say helloGOOSE_PROVIDERcodex-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::HttpStdio扩展变成带命令、参数和环境变量的McpServer::Stdio。随后还有一个filter_supported_servers步骤如果智能体在 ACP 握手时声明不支持 HTTP MCPHTTP 服务器会被跳过并输出 debug 日志SSE 类型的服务器则一律跳过因为 ACP 智能体侧不支持。这解释了为什么透传只覆盖--with-extension和--with-streamable-http-extension两种类型。配置选项与权限模式映射四个 provider 共享一组环境变量环境变量说明默认值GOOSE_PROVIDER设为amp-acp/claude-acp/codex-acp/pi-acp无GOOSE_MODEL要使用的模型因 provider 而异见下表GOOSE_MODE权限模式auto各 provider 的模型默认值ProviderGOOSE_MODEL默认值说明amp-acpcurrent由 Amp 决定当前模型claude-acpdefault即 opus还支持sonnet、haikucodex-acpcurrentCodex ACP 动态上报可用模型保持current即使用其默认模型也可显式选择某个已发现的模型pi-acpcurrent显式模型经model配置选项下发模型选择如何到达智能体current哨兵current不是普通的模型名而是源码中的哨兵常量ACP_CURRENT_MODELacp/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_PROVIDERopenai、GOOSE_MODELgpt-5时查询copilot-acp的模型会得到current而不是gpt-5防止 A 智能体的模型名被错误套用到 B 智能体上。Claude ACP 的权限模式映射GOOSE_MODE的四种取值在 Claude provider 中被映射为 Claude Code 的会话模式源码映射见 claude_acp.rsGOOSE_MODEClaude 会话模式行为autobypassPermissions跳过所有权限检查smart-approveacceptEdits自动接受文件编辑危险操作仍需确认approvedefault所有需要权限的操作都提示确认chatplan仅规划不执行工具源码中的注释解释了每条映射的意图bypassPermissions最接近自主Claude Code 的default对应危险操作前询问acceptEdits自动接受编辑但保留危险操作提示plan模式禁用工具执行与 goose 的 chat-only 意图对齐。Codex ACP 的权限模式映射GOOSE_MODECodex ACP 模式autoagent-full-accesssmart-approveagentapproveread-onlychatread-only该映射硬编码在 codex_acp.rs 的mode_mapping中。与 Claude 不同的是Codex 在approve和chat两档都落到read-only。此外Codex provider 对GOOSE_MODE的解析更严格未配置时默认autoresolve_goose_mode把NotFound错误折叠为Auto但非法取值会在启动适配器之前直接报错而不是带错启动子进程——这一行为有专门的集成测试goose_mode_validation_precedes_codex_acp_launch验证它用一个标记脚本充当假的codex-acp可执行文件断言非法GOOSE_MODE下子进程根本不会被拉起。Amp ACP 与 Pi ACP 的模式映射Amp 的映射相对简单见 amp_acp.rsauto→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::connectacp/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用于下发模型选择的配置选项 IDmodel。连接过程connect→start的关键步骤在一个专用 OS 线程中构建独立的 tokio 运行时并启动 ACP 客户端循环因为 tokio 的 I/O 句柄不能跨运行时移动完成initialize握手等待InitializeResponse立即创建 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 依赖外部二进制排障时按以下顺序检查适配器二进制在 PATH 中可找到amp-acp、claude-agent-acp、codex-acp、pi-acpwhich binary验证。若 goose 找不到二进制会话启动会直接失败底层 CLI 已认证且可用分别运行amp/claude/codex/pi确认登录态订阅限额未超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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考