Zed 中配置 AI 网关：OpenRouter、Vercel AI Gateway 与 Amazon Bedrock 的完整实践

本文基于 Zed 官方文档 use-a-gateway.md，系统讲解如何在 Zed 编辑器中通过网关平台路由模型请求：包括 OpenRouter 的 API Key 接入、自定义模型与上游提供商路由控制，Vercel AI Gateway 的端点配置，以及 Amazon Bedrock 的多种认证方式、跨区域推理、Guardrails 与 Mantle 模型。读完后你可以直接在 settings.json 中复制可用的配置片段，并将 Zed 的 Agent、外部 Agent 与终端线程功能接入任意 OpenAI 兼容的网关服务。

何时使用网关：Zed 支持的网关总览

当你希望将模型请求经由 OpenRouter、Vercel AI Gateway、Amazon Bedrock 或其他 OpenAI 兼容服务路由时，应使用网关（gateway）而非直接对接单一模型厂商。Zed 文档给出的四类网关及其能力矩阵如下：

网关	Zed AI 功能	外部 Agent	终端线程	说明
OpenRouter	支持	需单独配置	需单独配置	使用 OpenRouter API 访问
Vercel AI Gateway	支持	需单独配置	需单独配置	使用 Vercel AI Gateway API 访问
Amazon Bedrock	支持	需单独配置	需单独配置	使用 AWS 凭据或 Bedrock bearer token
OpenAI 兼容网关	支持	需单独配置	需单独配置	需自行配置 base URL、模型与密钥

需要注意的一个区分：上表中的“外部 Agent”与“终端线程”两列标记为 Separate config，意味着这两类功能不直接复用网关 provider 的密钥，而是通过各自的配置（如 Agent Server 配置）接入，网关的 API key 仅覆盖 Zed 内置的 AI 功能（Agent 线程、编辑预测等）。

OpenRouter 接入

基本配置步骤

1. 在 OpenRouter 平台创建账户并生成 API Key；
2. 在 Zed 中打开 Settings → AI → LLM Providers（对应源码中的 agent::OpenSettings 动作），找到 OpenRouter 行；
3. 输入你的 OpenRouter API Key。

Zed 同时会从本地 Zed 进程环境中读取 OPENROUTER_API_KEY。这一点可以从源码中得到印证：open_router.rs 中定义了 const API_KEY_ENV_VAR_NAME: &str = "OPENROUTER_API_KEY"，并通过 env_var! 宏注册为环境读取源，与 UI 中手动输入的密钥互为补充。

将 OpenRouter 设为助手 provider 时，需要在设置中显式选择模型：

{
  "agent": {
    "default_model": {
      "provider": "openrouter",
      "model": "openrouter/auto"
    }
  }
}

其中 openrouter/auto 会由 OpenRouter 路由到其当前可用的模型；也可以指定 OpenRouter API 上任意可用模型。

自定义模型（available_models）

在设置中为 OpenRouter provider 添加自定义模型：

{
  "language_models": {
    "open_router": {
      "api_url": "https://openrouter.ai/api/v1",
      "available_models": [
        {
          "name": "google/gemini-2.0-flash-thinking-exp",
          "display_name": "Gemini 2.0 Flash (Thinking)",
          "max_tokens": 200000,
          "max_output_tokens": 8192,
          "supports_tools": true,
          "supports_images": true,
          "mode": {
            "type": "thinking",
            "budget_tokens": 8000
          }
        }
      ]
    }
  }
}

自定义模型条目支持的字段包括 name、display_name、max_tokens、max_output_tokens、max_completion_tokens、supports_tools、supports_images 以及 mode（用于开启思考模式并指定思考预算 token 数）。

从源码结构看，open_router.rs 中的 OpenRouterSettings 结构包含 api_url、available_models 和 custom_headers 三个字段，说明除了文档示例中的模型列表，你还可通过 custom_headers 为请求附加自定义 HTTP 头（源码中标记了 HTTP-Referer、X-Title 为保留头名，OpenRouter 使用这两个头做来源标识）。

上游提供商路由控制（provider 对象）

OpenRouter 的一个独特能力是控制请求在上游 provider 之间的路由策略。Zed 允许在每个自定义模型条目上使用 provider 对象，支持字段包括 order、allow_fallbacks、require_parameters、data_collection、only、ignore、quantizations 和 sort：

{
  "language_models": {
    "open_router": {
      "available_models": [
        {
          "name": "openrouter/auto",
          "display_name": "Auto Router",
          "max_tokens": 2000000,
          "supports_tools": true,
          "provider": {
            "order": ["anthropic", "openai"],
            "allow_fallbacks": true,
            "require_parameters": true,
            "data_collection": "allow"
          }
        }
      ]
    }
  }
}

该示例表示：优先尝试 Anthropic 上游、其次是 OpenAI，允许降级回退，并要求上游支持所请求的参数；data_collection 用于声明是否允许数据收集（取 allow/deny 之类的值，对应 OpenRouter 的隐私控制）。这套字段直接映射到 OpenRouter API 的请求参数，让企业在合规与成本约束下精确控制模型流量走向。

Vercel AI Gateway 接入

使用 Vercel AI Gateway 路由 Zed AI 功能只需三步：

1. 在 Vercel AI Gateway 的 keys 页面创建 API Key；
2. 打开 Settings → AI → LLM Providers，找到 Vercel AI Gateway 行；
3. 输入你的 API Key。

Zed 同样会读取环境变量 VERCEL_AI_GATEWAY_API_KEY——在 vercel_ai_gateway.rs 中可以确认该常量定义，默认端点为 https://ai-gateway.vercel.sh/v1。

如需自定义端点（例如自建代理或私有部署），在设置中覆盖 api_url：

{
  "language_models": {
    "vercel_ai_gateway": {
      "api_url": "https://ai-gateway.vercel.sh/v1"
    }
  }
}

从源码看，VercelAiGatewaySettings 与 OpenRouter 结构一致，也包含 api_url、available_models、custom_headers 字段，因此 Vercel AI Gateway 同样支持自定义模型列表与自定义请求头的扩展方式。

Amazon Bedrock 接入

认证方式与 ZED_ 前缀环境变量

通过 AWS 访问模型时，Bedrock 凭据需要以下权限：

• bedrock:InvokeModelWithResponseStream
• bedrock:InvokeModel

Zed 支持带 ZED_ 前缀的 AWS 环境变量，以避免覆盖或消费你系统中用于其他用途的常规 AWS 凭据（在 bedrock.rs 中可以看到这些环境变量的读取实现）：

• ZED_ACCESS_KEY_ID
• ZED_SECRET_ACCESS_KEY
• ZED_SESSION_TOKEN
• ZED_AWS_PROFILE
• ZED_AWS_REGION
• ZED_AWS_ENDPOINT
• ZED_BEDROCK_BEARER_TOKEN

Bedrock 支持三种认证方式：命名 profile、静态凭据、Bedrock API key。

命名 profile：

{
  "language_models": {
    "bedrock": {
      "authentication_method": "named_profile",
      "region": "your-aws-region",
      "profile": "your-profile-name"
    }
  }
}

静态凭据：打开 Agent Settings（agent::OpenSettings 动作），进入 Amazon Bedrock 区域，输入 access key ID、secret access key 和 region。

Bedrock API key：

{
  "language_models": {
    "bedrock": {
      "authentication_method": "api_key",
      "region": "your-aws-region"
    }
  }
}

选择 API key 认证后，密钥本身保存在系统钥匙串（system keychain）中，而不是写入 settings.json——这一点在源码中也可印证：ZED_BEDROCK_BEARER_TOKEN_VAR 等凭据经由 CredentialsProvider（如 keychain）存取，settings 只记录认证方法类型。

跨区域推理（Cross-Region Inference）

Zed 以尽力（best-effort）方式使用 Bedrock 的 Cross-Region inference。默认使用区域性推理 profile；若希望启用全球 profile，添加 allow_global：

{
  "language_models": {
    "bedrock": {
      "authentication_method": "named_profile",
      "region": "your-aws-region",
      "profile": "your-profile-name",
      "allow_global": true
    }
  }
}

并非所有模型都支持全球推理 profile，具体清单以 AWS Bedrock 支持的模型文档为准。在 bedrock.rs 中可以看到，allow_global 会被传入 cross_region_inference_id 的解析过程，用于在模型 ID 前附加 global/ 等区域前缀。

Guardrails：为所有请求附加合规护栏

某些 AWS 环境要求每次 Bedrock API 调用都附带 guardrail。通过 guardrail_identifier 与 guardrail_version 对全部 Bedrock 请求强制应用护栏：

{
  "language_models": {
    "bedrock": {
      "guardrail_identifier": "arn:aws:bedrock:us-east-1:123456789012:guardrail/abc123",
      "guardrail_version": "DRAFT"
    }
  }
}

源码中的 get_guardrail_config() 会将这两个值附加到每个推理请求体中，实现企业级的内容合规管控。

Mantle 模型与 OpenAI 兼容推理端点

部分模型（如 GPT-5.6 家族的 Sol/Terra/Luna、GPT-5.5、GPT-5.4、Grok 4.3）不在 Bedrock Converse API 中提供，只能通过 bedrock-mantle（AWS 的 OpenAI 兼容推理端点）访问。Zed 会自动将这类模型路由到 bedrock-mantle，认证成功后它们会直接出现在模型选择器中，无需额外配置。

使用前提（两个硬性限制）：

• IAM 需要 bedrock-mantle 端点的额外权限（例如通过 AmazonBedrockMantleInferenceAccess 托管策略），与现有 Bedrock 权限叠加；
• bedrock-mantle 仅在部分 AWS Region 可用；Zed 在受支持 Region 之外尝试调用 Mantle 模型时，会抛出明确列出当前 Region 和支持 Region 的错误。

自定义 Mantle 模型

通过 mantle_available_models 添加经由 bedrock-mantle 提供的自定义模型：

{
  "language_models": {
    "bedrock": {
      "mantle_available_models": [
        {
          "name": "openai.gpt-oss-120b",
          "display_name": "GPT-OSS 120B",
          "max_tokens": 128000,
          "protocol": "chat_completions",
          "supports_tools": true,
          "supports_images": false,
          "supports_thinking": true
        }
      ]
    }
  }
}

关键字段说明：

• protocol：选择模型所走的 OpenAI 兼容 API，必须是 chat_completions 或 responses 之一；
• supports_thinking：对接受 OpenAI reasoning effort 参数的 Mantle 模型设为 true，Zed 会在 thinking effort 选择器中暴露 low、medium、high、xhigh 四个档位；关闭思考时发送 none。

OpenAI 兼容网关的通用接入

如果你的网关暴露的是 OpenAI 兼容 API（无论是自建的 LiteLLM、one-api 类聚合层，还是云厂商的私有端点），Zed 提供了统一的 OpenAI 兼容配置路径，可参见 Zed 文档 use-api-access.md 中的 OpenAI-compatible 章节，核心思路相同：配置 base URL（api_url）、模型标识与 API key，即可复用 Zed 的流式对话、工具调用等能力。

小结

场景	关键配置位置	备注
OpenRouter 密钥	Agent Settings UI 或 OPENROUTER_API_KEY	需显式 agent.default_model
OpenRouter 路由控制	language_models.open_router.available_models[].provider	order/allow_fallbacks 等字段
Vercel AI Gateway	Agent Settings UI 或 VERCEL_AI_GATEWAY_API_KEY	默认端点 https://ai-gateway.vercel.sh/v1
Bedrock profile	language_models.bedrock.authentication_method	密钥存于系统钥匙串
Bedrock 护栏	guardrail_identifier / guardrail_version	适用于合规强制场景
Mantle 模型	mantle_available_models	仅限部分 Region，需额外 IAM 策略

配置时建议遵循以下顺序：先在 UI 中完成密钥认证并确认模型列表能正常拉取，再在 settings.json 中细化 available_models / mantle_available_models 的字段（token 上限、工具与图片支持、思考模式），最后按合规需求叠加 provider 路由、allow_global 与 guardrails 配置。所有配置项均可在当前仓库源码中查证：open_router.rs、vercel_ai_gateway.rs、bedrock.rs 与 settings.rs。