第30章 Zed 使用网关连接 OpenRouter 等 AI 服务指南

当需要将模型请求通过 OpenRouter、Vercel AI Gateway、Amazon Bedrock 或其他兼容 OpenAI 的平台进行路由时，请使用网关。

OpenRouter

若需通过 OpenRouter 路由 Zed AI 功能，请使用 OpenRouter。

1. 访问 OpenRouter 并创建账户。
2. 在 OpenRouter 密钥页面 生成 API 密钥。
3. 通过 {#action agent::OpenSettings} 打开 设置 → AI → LLM 提供商，找到 OpenRouter 条目。
4. 输入 OpenRouter API 密钥。

Zed 还会从本地 Zed 进程环境中读取 OPENROUTER_API_KEY。

将 OpenRouter 设为助手提供商时，请在设置中明确选择模型：

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

openrouter/auto 模型会将请求路由至 OpenRouter 选定的可用模型。您也可以指定通过 OpenRouter API 可用的任意模型。

OpenRouter 自定义模型

可以在设置中为 OpenRouter 提供商添加自定义模型：

{
  "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 等字段。

OpenRouter Provider Routing

通过每个模型条目上的 provider 对象，可以控制 OpenRouter 在多个上游提供商之间如何路由自定义模型请求。

支持的字段包括 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"
          }
        }
      ]
    }
  }
}

Vercel AI Gateway

如果想通过 Vercel 来路由 Zed 的 AI 功能，可以使用 Vercel AI Gateway。

1. 在 Vercel AI Gateway 的密钥页面创建一个 API key。
2. 通过 {#action agent::OpenSettings} 打开 Settings → AI → LLM Providers，找到 Vercel AI Gateway 那一行。
3. 填入你的 Vercel AI Gateway API key。

Zed 还会从本地 Zed 进程环境中读取 VERCEL_AI_GATEWAY_API_KEY。

你可以在设置中配置 Vercel AI Gateway 的自定义端点：

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

Amazon Bedrock

如果你希望通过 AWS 使用模型，可以选用 Amazon Bedrock。

Bedrock 支持支持流式工具调用的模型。详情请参阅 Amazon Bedrock 工具使用文档。

你的 AWS 凭据需要具备以下权限：

• bedrock:InvokeModelWithResponseStream
• bedrock:InvokeModel

Bedrock 支持带 Zed 前缀的 AWS 环境变量，以避免覆盖或占用你常规的 AWS 凭据：

• 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 身份验证

你可以使用命名配置文件、静态凭据或 Bedrock API 密钥进行身份验证。

若使用命名配置文件，请在设置中配置 Bedrock：

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

若使用静态凭据，通过 {#action agent::OpenSettings} 打开 Agent 设置，在 Amazon Bedrock 部分填写 Access Key ID、Secret Access Key 和 Region。

若使用 Bedrock API 密钥，请选择 API 密钥身份验证方式：

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

API 密钥本身存储在系统钥匙串中，而非 settings.json 文件里。

Bedrock 跨区域推理

Zed 在 Bedrock 上以尽力而为的方式使用跨区域推理（Cross-Region inference）。

默认情况下，Zed 使用区域推理配置。若要启用全球配置，请添加 allow_global：

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

并非所有模型都支持全球推理配置。当前支持列表请参阅 AWS Bedrock 支持模型的文档。

Bedrock 防护栏（Guardrails）

部分 AWS 环境要求每次 Bedrock API 调用都附带防护栏。在配置中添加 guardrail_identifier 即可为所有 Bedrock 请求应用防护栏：

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

Bedrock Mantle 模型

部分模型（如 GPT-5.6 系列（Sol、Terra 和 Luna）、GPT-5.5、GPT-5.4 以及 Grok 4.3）无法通过 Bedrock 的 Converse API 访问，只能通过 AWS 的 OpenAI 兼容推理端点 bedrock-mantle 调用。Zed 会自动将这些模型路由至 bedrock-mantle；认证完成后，它们会与其他 Bedrock 模型一同显示在模型选择器中，无需额外配置。

使用 Mantle 模型需要 IAM 对 bedrock-mantle 端点具备相应权限（例如通过 AmazonBedrockMantleInferenceAccess 托管策略），并在现有 Bedrock 凭据权限的基础上补充。此外，bedrock-mantle 仅在部分 AWS 区域可用。若在不受支持的区域尝试使用 Mantle 模型，Zed 会报错并明确提示当前区域及支持的区域列表。

自定义 Bedrock 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。如果自定义 Mantle 模型支持 OpenAI 的 reasoning effort 参数，可以把 supports_thinking 设为 true，这样 Zed 的 thinking effort 选择器中会出现 low、medium、high 和 xhigh 选项；关闭思考模式时则会发送 none。

OpenAI 兼容网关

如果你的网关提供 OpenAI 兼容 API，请参考 Use API Access 进行配置。