AI SDK ACP Harnesses 实战为 Claude Code、Codex 与 Grok Build 配置认证与 AI Gateway 路由【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai本指南围绕 GitHub推荐项目精选 / ai / ai 仓库中examples/harness-e2e-next示例的 ACPAgent Client Protocolharness 配置展开讲解如何通过createACP为 Claude Code、Codex、Grok Build 三个运行时声明直接凭据与 AI Gateway 配置并深入剖析认证自动选择机制、权限模式限制与 Gateway 端点映射原理。读完本文你将掌握在 AI SDK harness 抽象下编排外部编码 Agent 的完整配置方案并能依据仓库源码定位每个配置项的底层行为。ACP harnesses将运行时配置与应用代码放在一起在 AI SDK 的 harness 抽象中ACPAgent Client Protocol是让外部编码 Agent如 Claude Code、Codex、Grok Build通过标准协议与 AI SDK 应用对接的桥梁。examples/harness-e2e-next示例项目遵循一个核心组织原则将每个运行时特有的 ACP 配置紧挨着消费它的应用代码存放而不是散落在全局配置或环境变量里。具体做法是每个运行时提供一个独立的createACPprofile集中声明两件事——该运行时的直接凭据环境变量以及它的AI Gateway 配置。这些 profile 文件位于 examples/harness-e2e-next/agent/harness/ 目录下其中acp-claude-code/harness.ts与acp-codex/harness.ts是两个典型实现Grok Build 的对应 profile 则由ai-sdk/harness-grok-build包中的grokBuild工厂提供见 packages/harness-grok-build/src/grok-build-harness.ts。这种“profile 与应用同目录”的组织方式带来两个直接收益其一每个应用的 ACP 配置可独立演进、互不干扰其二配置语义一目了然——凭据从哪来、走哪条认证路径都被显式写死在 profile 里评审与排查都更有据可循。认证选择AI Gateway 自动识别与显式覆盖ACP profile 的认证行为遵循一套明确的自动选择规则这也是使用这些 harness 前必须理解的核心逻辑只要环境变量中存在AI_GATEWAY_API_KEY或VERCEL_OIDC_TOKEN中的任意一个profile 就会自动选择 AI Gateway作为认证与请求转发路径此时可用AI_GATEWAY_BASE_URL覆盖 Gateway 的默认端点。如果两种 Gateway 凭据都不存在profile 则只转发该运行时自身配置的直接凭据如ANTHROPIC_API_KEY、CODEX_API_KEY、XAI_API_KEY。当调用方需要强制覆盖自动选择结果时可把createACP的auth参数显式设为direct或ai-gateway。这套自动选择逻辑在源码中有完整印证。在 packages/harness-acp/src/acp-auth.ts 的resolveACPProviderAuthentication中可以看到当 profile 声明了providerAuthentication时函数会先解析认证模式若模式为direct则直接返回直接认证环境否则尝试解析 Gateway 凭据——若未显式指定模式auto且 Gateway 凭据缺失则回退到直接认证而一旦显式选择了ai-gateway却拿不到任何 Gateway 凭据就会抛出明确错误AI Gateway authentication was selected, but neither AI_GATEWAY_API_KEY nor VERCEL_OIDC_TOKEN is set.这保证了“自动回退”与“显式强制”两种语义都不会静默出错。从源码结构可以推断AI_GATEWAY_API_KEY与VERCEL_OIDC_TOKEN的优先级判定集中在ai-sdk/harness的getAiGatewayAuthFromEnv工具中见 packages/harness/src/utils/ai-gateway-auth.tsacp-auth.ts通过resolveGatewayCredential统一消费该结果并记录凭据来源gatewayCredentialSource用于认证 profile 的身份摘要。三个运行时 profile 一览示例项目为本次端到端矩阵固定了精确的实现版本每个 profile 对应一个 npm 包与一个可执行入口Profile固定版本包可执行入口acp-claude-codeagentclientprotocol/claude-agent-acp0.61.0claude-agent-acpacp-codexagentclientprotocol/codex-acp1.1.4codex-acpacp-grok-buildxai-official/grok0.2.111grok agent stdio注意上表中的包版本被 profile 精确固定pin确保端到端测试矩阵每次跑出的行为一致。以acp-claude-code为例其 profile 通过source: { type: npm-simple, packageName: agentclientprotocol/claude-agent-acp, packageVersion: 0.61.0 }声明安装来源见 examples/harness-e2e-next/agent/harness/acp-claude-code/harness.ts。Claude Code ACPAnthropic 启动环境与 Gateway 根端点Claude Code 的 ACP profileacp-claude-code使用被固定实现的Anthropic 启动环境并直连AI Gateway 的根端点即 Gateway base URL 本身不做/v1之类的后缀拼接。从 acp-claude-code/harness.ts 可以看到它的凭据与网关声明credentialEnv: [ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN],直接认证接受ANTHROPIC_API_KEY与ANTHROPIC_AUTH_TOKEN两类凭据当两者同时存在时profile 会为它们各生成一条凭据代理credential brokering转换把沙箱内的x-api-key/Authorization: Bearer请求头替换为宿主侧的真实凭据匹配目标 URL 为ANTHROPIC_BASE_URL或默认的https://api.anthropic.com。Gateway 路径下profile 将三个环境变量映射到 Gateway 动态注入的来源providerAuthentication: { gateway: { env: { ANTHROPIC_API_KEY: { $source: gateway-api-key }, ANTHROPIC_AUTH_TOKEN: { $source: gateway-api-key }, ANTHROPIC_BASE_URL: { $source: gateway-base-url }, CLAUDE_AGENT_SDK_CLIENT_APP: { $source: client-app }, }, }, },这里$source: gateway-api-key表示用 AI Gateway 的密钥填充 Anthropic 两类凭据$source: gateway-base-url表示把 Gateway 根端点作为 Anthropic 的 base URL$source: client-app则用于标记客户端应用身份。整个 profile 还通过modelMappingsession-config-option的model路径把模型选择落到 ACP 会话配置上并把allow-reads/allow-edits/allow-all三种 Harness 权限模式分别映射到 Claude Code 的default/acceptEdits/bypassPermissions会话模式。Codex ACPAPI Key 启动环境与 OpenAI 兼容 Gateway ProviderCodex 的 profileacp-codex走的是API Key 启动环境并且要求 Gateway 侧配置一个以/v1结尾的 OpenAI 兼容 Provider。这一点与 Claude Code 的“根端点”形成鲜明对比——Codex 的model_providers配置中ai_gatewayprovider 的base_url被显式要求追加/v1后缀ensureSuffix: /v1同时声明wire_api: responses、preferred_auth_method: apikey并透传User-Agent与x-client-app两个请求头用于客户端归属见 acp-codex/harness.ts。Codex profile 的凭据与环境转发也很有特点credentialEnv: [CODEX_API_KEY, OPENAI_API_KEY], forwardEnv: [CODEX_CONFIG],直接认证优先使用CODEX_API_KEY未设置时回退到OPENAI_API_KEYCODEX_CONFIG会被原样转发进沙箱同时被用作指令注入的载体——instructionMapping以launch-env-json的方式把系统提示写入CODEX_CONFIG的developer_instructions字段。而resolveCodexACPBaseUrl同文件 L97-L114会先从CODEX_CONFIG的 JSON 中解析model_provider与对应base_url以定位凭据代理的匹配 URL解析失败时回退到https://api.openai.com/v1。Codex 权限模式为什么只有 allow-allCodex ACP 只支持permissionMode: allow-all因为更严格的 Codex 权限模式会启用其内部沙箱与 AI SDK harness 的沙箱编排冲突。这一点在 profile 中有直接体现permissionModeMapping: { allow-reads: null, allow-edits: null, allow-all: { type: session-mode, modeId: agent-full-access }, } as const satisfies ACPPermissionModeMapping,null表示该 Harness 权限模式在 Codex ACP 下不可用。底层机制可见 packages/harness-acp/src/v1/bridge/permission-mode.tsconfigureACPPermissionMode会先在映射表中查找目标若对应项为null则抛出Permission mode allow-reads is not supported by this ACP harness.之类的错误并提示改用allow-all。对应行为在 packages/harness-acp/src/acp-harness.test.ts 中有专门测试用例覆盖transports explicit unsupported permission mode mappings。Grok Build ACP二进制验证、隔离 GROK_HOME 与双端点映射Grok Build 的 profileacp-grok-build在整个矩阵中比较特殊因为安装的xai-official/grok包的 npm trampoline 可能复用默认 Grok 主目录中已存在的旧二进制导致验证时看到的并非包内声明的版本。为此示例在验证阶段使用了隔离的GROK_HOME环境并确认grok --version报告0.2.111 (94172f2aa4e5)——这正是被验证的真实二进制版本。该精确版本二进制对外暴露以下环境变量环境变量用途XAI_API_KEY直接认证密钥GROK_XAI_API_BASE_URLOpenAI 兼容的推理端点GROK_MODELS_BASE_URL模型列表端点GROK_CLIENT_NAME/GROK_CLIENT_VERSION客户端归属attribution标识在 Gateway 启动路由下profile 会把两个端点推理端点与模型端点都映射到以/v1结尾的已配置 Gateway URL同时供应客户端归属标识而在直接模式下这些值原样保留、不做任何改写。实现见 packages/harness-grok-build/src/grok-build-harness.tsproviderAuthentication: { gateway: { env: { GROK_CLIENT_NAME: { $source: client-app-name }, GROK_CLIENT_VERSION: { $source: client-app-version }, XAI_API_KEY: { $source: gateway-api-key }, GROK_XAI_API_BASE_URL: { $source: gateway-base-url, ensureSuffix: /v1 }, GROK_MODELS_BASE_URL: { $source: gateway-base-url, ensureSuffix: /v1 }, }, }, },此外 Grok Build 的可执行入口是grok agent stdioexecutable: grokargs: [agent, stdio]指令通过文件系统映射写入.grok/AGENTS.md且其凭据代理在沙箱内将Authorization: Bearer sandbox key替换为宿主侧真实XAI_API_KEY。凭据环境变量速查表端到端示例所需的完整环境变量清单集中在 examples/harness-e2e-next/env.local.example 中与上述 profile 一一对应# Vercel OIDC tokenVercel Sandbox 必需 VERCEL_OIDC_TOKENxxxxxxx # AI Gateway 凭据任一 Harness 适配器使用ACP profile 检测到即自动启用 Gateway AI_GATEWAY_API_KEYxxxxxxx # Claude Code ACP 直接认证ANTHROPIC_AUTH_TOKEN 存在时也会一并转发 ANTHROPIC_API_KEYxxxxxxx ANTHROPIC_AUTH_TOKENxxxxxxx # Codex ACP 直接认证CODEX_API_KEY 未设置时回退到 OPENAI_API_KEY CODEX_API_KEYxxxxxxx OPENAI_API_KEYxxxxxxx # Grok Build ACP 直接认证 XAI_API_KEYxxxxxxx在应用中使用 ACP profile这些 profile 最终通过HarnessAgent接入应用。以 acp-claude-code/basic-agent.ts 为例profile 被直接作为harness传入配合createVercelSandbox提供的沙箱export const claudeCodeACPHarnessAgent new HarnessAgent({ harness: claudeCodeACPHarness, sandbox: createVercelSandbox({ runtime: node24, ports: [4000], }), tools: { getUserName: getUserNameTool }, debug: { enabled: true }, telemetry: { integrations: [ createTraceTreeReporter(), createFileReporter({ dir: .harness-observability/acp-claude-code/basic, }), ], }, });创建会话后即可用agent.generate({ session, prompt })驱动外部编码 Agent 完成任务。acp-codex的 basic-agent.ts 结构完全一致只是替换了 profile 与可观测性输出目录。示例中的两个 ACP profile 目录还各提供 8 个可复用 agent 变体basic-agent、basic-stepped-agent、weather-agent、weather-approval-agent、weather-only-agent、builtin-tools、question-tool、ai-sdk-coding-agent覆盖简单问答、分步执行、内置工具透传与编码仓库任务等场景。小结通过examples/harness-e2e-next的 ACP harnesses 示例可以看到AI SDK 把外部编码 Agent 的接入抽象成三个层次profile 声明createACP定义凭据、可执行文件与 Gateway 映射、自动/显式认证选择AI_GATEWAY_API_KEY/VERCEL_OIDC_TOKEN触发 Gatewayauth参数强制覆盖、运行时差异封装Claude Code 的 Anthropic 环境、Codex 的/v1OpenAI 兼容 provider 与allow-all限制、Grok Build 的隔离GROK_HOME与双端点映射。理解这三点即可在自己的应用中安全、可复现地接入任意 ACP 兼容编码 Agent。【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考