本页译自英文文档。命令、标识符和示例保持原样。运行时 7.24.4 · SDK 2.6.7。 英文原文

自定义与网关提供方

状态：生效 范围：当前状态 最近审阅：2026-09-06 负责人：ax-code 运行时

AX Code 通过标准提供方协议与模型对话。任何说 OpenAI 兼容（/v1/chat/completions）或 Anthropic 兼容（/v1/messages）API 的端点，都可以通过把 baseURL 指向它来添加为自定义提供方——无需改代码，也无需等待内置预设。

这涵盖自托管聚合器和中继网关，例如 LiteLLM、one-api、new-api 和 Vercel AI Gateway，以及私有企业代理和任何其他兼容服务。AX Code 统一对待它们：它说线路协议，你提供 URL 和密钥。

责任说明。 网关位于 AX Code 与上游模型之间，因此你的提示、代码和凭据都会经过它。当你把 AX Code 指向第三方或账户池中继时，你有责任信任该运营者处理你的数据，并遵守它路由到的每个上游提供方的服务条款。诸如 OpenRouter 的内置网关预设使用同一标准协议路径；自定义网关配置并不意味着认可任何中继运营者。

交互式设置

对兼容网关使用 /connect -> API 云提供方 -> 自定义 API 提供方，或对 AX Trust 网关使用 /connect -> AX Trust -> 连接 AX Trust。输入其基础 URL（AX Trust 包括 /v1）和客户端 API 密钥。编辑器发现模型 ID 和元数据，并把凭据存入加密的认证存储。如果发现不可用，它也可以接受显式的模型 ID。重新连接已保存的 URL 时，若令牌留空，会保留其提供方 ID 和密钥。AX Trust 连接在编辑和模型刷新之后保持其类别。AX Code 在这些连接上随会话 ID 发送 X-AX-Prompt-Cache-Key，以便网关把会话保持在一个合格账户上；把 provider.<id>.options.axTrust 设为 false 可禁用它。此头不会转发到上游，也不是正文中的 prompt_cache_key。

已连接的 AX Trust 提供方在启动时于后台刷新其模型列表。AX Code 用现有凭据调用已配置端点的 GET /models，并更新模型名称、上下文/输出限制、推理、工具调用、temperature 支持和图像支持。具备图像能力的模型在 /models 中显示视觉标记，包括当 AX Trust 公布其图像支持时的网关别名。发现完成时 TUI 会更新。对于精确的第一方 DeepSeek 模型 ID，缺失的元数据会从捆绑的 models.dev 目录填充。显式的网关能力标志和限制优先；未知别名不会因名称相似而继承能力。

成功的刷新会替换运行时列表，移除网关不再公布的模型，并且仍然应用已配置的允许/阻止列表。超时、错误、空或无效响应会保留已保存列表并记录发现失败。启动不会等待网络。此次刷新不改写提供方配置或凭据；已保存的配置仍是启动回退。普通自定义 API 提供方保留手动刷新。

提供方如何解析

对每个请求，AX Code 需要提供方条目中的三样东西：

• npm — 说线路协议的 AI SDK 适配器。OpenAI 风格端点使用 @ai-sdk/openai-compatible，Anthropic 风格端点使用 @ai-sdk/anthropic。只有 @ai-sdk/* 适配器被捆绑/可安装。
• options.baseURL — 网关 URL。回退到提供方的 api 字段，然后是模型自己的 api.url。支持 ${ENV_VAR} 替换。
• 凭据 — 按顺序从 options.apiKey 解析，然后是持久化的认证存储，然后是提供方的 env 变量。

手动配置还需要显式的 models 映射。交互式编辑器从端点或你提供的模型 ID 填充此映射。

专用私有 GPU 云是 /connect → 私有 GPU 云 下的一等提供方。粘贴 OpenAI 兼容的 URL 和令牌（alibaba-pai、runpod、huggingface-endpoints、sagemaker、volcengine-ark、modelarts、tencent-ti 或 custom-private-gpu）；AX Code 调用 GET …/models 并自动使用已部署的模型 ID。

托管 GPU 目录（nebius、fireworks-ai、togetherai、baseten、nvidia、deepinfra）使用 API 密钥和捆绑的模型快照，与 OpenCode 使用的模式相同。

OpenAI 兼容网关

大多数聚合器（LiteLLM、one-api、new-api、免费/自托管网关）暴露 OpenAI 兼容表面。把下面内容加入你的 ax-code.json（全局在 ~/.config/ax-code/ax-code.json，或在仓库根的按项目配置）：

{
  "$schema": "https://ax-code.app/docs-assets/schema/config.schema.json",
  "provider": {
    "my-gateway": {
      "name": "My Gateway",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://gateway.example.com/v1",
        "apiKey": "${MY_GATEWAY_API_KEY}",
      },
      "models": {
        "gpt-4o": {
          "name": "GPT-4o (via gateway)",
          "tool_call": true,
          "reasoning": false,
          "attachment": true,
          "limit": { "context": 128000, "output": 16384 },
        },
      },
    },
  },
}

• 键 "my-gateway" 是你在 /connect 和 ax-code models 中选择的提供方 id。
• models 下的每个键是本地选择 ID。当它与该键不同时，把条目的 id 设为网关期望的确切模型 ID；否则，对于没有现有目录映射的手工声明模型，使用该键。
• 优先使用 ${ENV_VAR} 而不是字面密钥，以免秘密进入已提交的配置。

更改端点之后的网关模型别名

更改 options.baseURL 不会翻译手工配置的模型 ID。例如，AX Trust 端点可能公布 deepseek-flash，而现有的本地选择是 ax-trust/deepseek-v4-flash。保留本地键，并把 provider.ax-trust.models.deepseek-v4-flash.id 设为 deepseek-flash。AX Code 随后在 API 请求中发送网关 ID。

见 AX Trust DeepSeek Flash 配置示例。把相关提供方字段合并进你现有的配置，保留其他模型及其能力设置。该示例使用 {env:AX_TRUST_API_KEY}；在启动 AX Code 之前设置该环境变量，或保留你现有的凭据配置。编辑之后重启 AX Code。

诊断 403 model is not allowed 时，把请求的模型 ID 与端点已认证的 GET /models 响应比较。仅成功的模型列表请求并不能确立运行模型的权限。如果确切 ID 仍然失败，检查网关的密钥/模型权限。

Anthropic 兼容网关

暴露 /v1/messages（Claude API 形态）的中继使用 Anthropic 适配器：

{
  "$schema": "https://ax-code.app/docs-assets/schema/config.schema.json",
  "provider": {
    "my-claude-gateway": {
      "name": "My Claude Gateway",
      "npm": "@ai-sdk/anthropic",
      "options": {
        "baseURL": "https://gateway.example.com",
        "apiKey": "${MY_GATEWAY_API_KEY}",
      },
      "models": {
        "claude-sonnet-4-6": {
          "name": "Claude Sonnet (via gateway)",
          "tool_call": true,
          "reasoning": true,
          "attachment": true,
          "limit": { "context": 200000, "output": 64000 },
        },
      },
    },
  },
}

一些 Anthropic 形态的中继也直接尊重 Claude 环境变量。若要在不编辑配置的情况下快速无头运行，可以设置：

export ANTHROPIC_BASE_URL="https://gateway.example.com"
export ANTHROPIC_AUTH_TOKEN="sk-..."

当你希望网关作为自己的可选提供方出现、并带有策展的模型列表时，仍然建议使用配置条目。

模型字段

模型条目复用登记模式；对自定义端点，有用的字段是：

把能力标志设成与上游模型实际支持的一致；AX Code 用它们来门控工具调用、附件和上下文预算。

核验

保存配置之后：

• ax-code models 列出你的提供方暴露的每个模型。
• TUI 内的 /connect 显示提供方，并在你使用 env 键而不是 options.apiKey 时让你认证。

如果缺少某个模型，请确认提供方 id、模型键，以及网关在 baseURL 可达。

故障排除

• 认证错误 — 确认凭据解析顺序：options.apiKey 优先，否则使用 env/认证存储密钥。
• 停滞的流 — 网关有时会缓冲 SSE。在提供方上调整 options.chunkTimeout（每块）和 options.timeout（整个请求）。
• 工具调用被拒绝 — 在模型上设置 "tool_call": true，并确认网关后面的上游模型确实支持工具。