入门 Zed Industries 2026-09-14 17:42:19 · 1 阅读

第28章 Zed 编辑器配置 API 访问指南

当服务商提供 API 密钥、API 额度、充值服务或使用量计费时，请使用 API 访问方式。

付费的 API 额度、使用量计费和充值服务均属于 API 访问，即使你是直接向服务商付费也是如此。只要服务商提供 API 密钥，就应走这条路径。

支持的 API 服务商

Zed 支持以下一级 API 服务商，用于提供模型支撑的 Zed AI 功能：

Anthropic
- 自定义 Anthropic 模型
OpenAI API
- 自定义 OpenAI 模型
Google AI
- 自定义 Google AI 模型
Mistral
- 自定义 Mistral 模型
DeepSeek
- 自定义 DeepSeek 模型
xAI
- 自定义 xAI 模型
OpenCode API
- 自定义 OpenCode 模型
兼容 Anthropic 的端点
兼容 OpenAI 的端点

API 访问的适用范围

请为 Zed Agent、Inline Assistant、Git 提交信息生成、线程摘要以及类似的 Zed 自有 AI 功能使用 API 访问。

外部 Agent 和 Terminal Threads 通常需要在 Agent 或 CLI 本身中配置模型访问。关于 Agent 路径和模型访问路径的区别，请参阅 Agents。

API 密钥与环境变量

大多数 API 访问服务商可以通过 设置 → AI → LLM 服务商 页面进行配置 {#action agent::OpenSettings}。通过 Zed 保存的密钥存储于系统钥匙串中，而非 settings.json。

Zed 还会读取服务商特定的环境变量。非空的环境变量优先级高于钥匙串中的值。如果密钥来自环境变量，请取消设置该变量并重启 Zed 以停止使用它。

服务商	环境变量
Anthropic	`ANTHROPIC_API_KEY`
OpenAI	`OPENAI_API_KEY`
Google AI	`GEMINI_API_KEY`，若缺失则回退至 `GOOGLE_AI_API_KEY`
Mistral	`MISTRAL_API_KEY`
DeepSeek	`DEEPSEEK_API_KEY`
xAI	`XAI_API_KEY`
OpenCode	`OPENCODE_API_KEY`
OpenRouter	`OPENROUTER_API_KEY`
Vercel AI Gateway	`VERCEL_AI_GATEWAY_API_KEY`
Ollama	`OLLAMA_API_KEY`
LM Studio	`LMSTUDIO_API_KEY`

OpenAI 兼容提供商的环境变量由配置的提供商 ID 转换生成，规则是转为大写下划线命名并附加 _API_KEY 后缀。例如，提供商 ID my-gateway 对应的变量是 MY_GATEWAY_API_KEY。

自定义请求头

你可以为 Zed 向支持的 HTTP 提供商发送的每个请求附加额外的 HTTP 请求头。这在企业环境或可观测性工具集成中非常实用。

通过 language_models.<provider>.custom_headers 进行配置：

{
  "language_models": {
    "openai": {
      "custom_headers": {
        "Fancy-Auth": "Bearer <your-fancy-key>",
        "X-My-Tag": "zed"
      }
    }
  }
}

custom_headers 支持 Amazon Bedrock、Anthropic、DeepSeek、Google AI、LM Studio、Mistral、Ollama、OpenAI、OpenAI 兼容提供商、OpenCode、OpenRouter、Vercel AI Gateway 和 xAI。

Zed 为各提供商内部管理的请求头（如 Authorization、Content-Type、Accept 以及提供商特有的认证头）不可被覆盖。若尝试修改，系统会忽略并给出警告。

远程项目

Zed AI 功能所用的 LLM 提供商在本地 Zed 应用中初始化。在 SSH、开发容器及其他远程项目中，Zed 保存的 API 密钥从本地系统钥匙串读取，提供商环境变量则从本地 Zed 进程环境中读取。

External Agents 和 Terminal Threads 可能会运行各自的进程，并使用各自的远程或本地环境。详见 External Agents 和 Terminal Threads。

Provider 注意事项

Anthropic

如果你有 Anthropic 的 API key 或 API 额度，可以使用 Anthropic API access。Claude Pro 和 Max 订阅是分开的，参见 Use an Existing Subscription。

注册 Anthropic 并创建 API key。
确保你的 Anthropic 账户有 API 额度。
使用 {#action agent::OpenSettings} 打开 Agent Settings，进入 Anthropic 部分。
填入你的 Anthropic API key。

Zed 也会从本地 Zed 进程的环境中读取 ANTHROPIC_API_KEY。

自定义 Anthropic 模型

当你需要指定其他模型 ID、显示名称、上下文窗口、输出上限、工具覆盖（tool override）或思考模式时，可以在设置中添加自定义 Anthropic 模型。

{
  "language_models": {
    "anthropic": {
      "available_models": [
        {
          "name": "claude-3-5-sonnet-20240620",
          "display_name": "Sonnet 2024-June",
          "max_tokens": 128000,
          "max_output_tokens": 2560,
          "tool_override": "some-model-that-supports-toolcalling"
        }
      ]
    }
  }
}

对于支持 extended thinking 的 Anthropic 模型，可以添加 mode 配置：

{
  "language_models": {
    "anthropic": {
      "available_models": [
        {
          "name": "claude-sonnet-4-latest",
          "display_name": "claude-sonnet-4-thinking",
          "max_tokens": 200000,
          "mode": {
            "type": "thinking",
            "budget_tokens": 4096
          }
        }
      ]
    }
  }
}

OpenAI API

使用 OpenAI API 访问权限需要 OpenAI API 密钥或 API 计费。ChatGPT Plus 和 Pro 订阅采用不同的配置路径，请参阅使用现有订阅。

访问 OpenAI 平台并创建 API 密钥。
确保 OpenAI 账户已充值或启用计费。
通过 {#action agent::OpenSettings} 打开 Agent 设置，导航至 OpenAI 部分。
输入 OpenAI API 密钥。

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

自定义 OpenAI 模型

如果需要备用模型 ID、预览版本或自定义请求参数，可在设置文件中添加自定义 OpenAI 模型。

{
  "language_models": {
    "openai": {
      "available_models": [
        {
          "name": "gpt-5.2",
          "display_name": "gpt-5.2 high",
          "reasoning_effort": "high",
          "max_tokens": 272000,
          "max_completion_tokens": 20000
        }
      ]
    }
  }
}

必须通过 max_tokens 指定模型的上下文窗口。对于侧重推理的模型，请设置 max_completion_tokens 以避免高昂的推理令牌成本。

Google AI

拥有 Gemini API 密钥时，可使用 Google AI API 访问权限。

前往 Google AI Studio 并创建 API 密钥。
通过 {#action agent::OpenSettings} 打开 Agent 设置，导航至 Google AI 部分。
输入 Google AI API 密钥。

Zed 从本地 Zed 进程环境中读取 GEMINI_API_KEY，若未找到则回退至 GOOGLE_AI_API_KEY。

自定义 Google AI 模型

若需指定特定的 Gemini 模型版本（包括实验性模型）或思考模式配置，可添加自定义 Google AI 模型。

{
  "language_models": {
    "google": {
      "available_models": [
        {
          "name": "gemini-3.1-pro-preview",
          "display_name": "Gemini 3.1 Pro",
          "max_tokens": 1000000,
          "mode": {
            "type": "thinking",
            "budget_tokens": 24000
          }
        },
        {
          "name": "gemini-3-flash-preview",
          "display_name": "Gemini 3 Flash (Thinking)",
          "max_tokens": 1000000,
          "mode": {
            "type": "thinking",
            "budget_tokens": 24000
          }
        }
      ]
    }
  }
}

Mistral

若已拥有 Mistral API 密钥，请使用 Mistral API 接入。

访问 Mistral 平台并创建 API 密钥。
通过 {#action agent::OpenSettings} 打开代理设置，进入 Mistral 部分。
输入您的 Mistral API 密钥。

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

自定义 Mistral 模型

如需替代模型 ID、自定义限制、工具支持、图像支持或自定义端点，请添加自定义 Mistral 模型。

{
  "language_models": {
    "mistral": {
      "api_url": "https://api.mistral.ai/v1",
      "available_models": [
        {
          "name": "mistral-tiny-latest",
          "display_name": "Mistral Tiny",
          "max_tokens": 32000,
          "max_output_tokens": 4096,
          "max_completion_tokens": 1024,
          "supports_tools": true,
          "supports_images": false
        }
      ]
    }
  }
}

DeepSeek

若已付费使用 API、充值或持有 API 密钥，请使用 DeepSeek API 接入。在 Zed 中，DeepSeek 仅支持 API 接入，不支持订阅登录。

访问 DeepSeek 平台并创建 API 密钥。
通过 {#action agent::OpenSettings} 打开代理设置，进入 DeepSeek 部分。
输入您的 DeepSeek API 密钥。

Zed 也会从本地 Zed 进程的环境变量中读取 DEEPSEEK_API_KEY。

自定义 DeepSeek 模型

如果需要使用其他模型 ID、自定义 token 上限或自定义 endpoint，可以添加自定义 DeepSeek 模型。

{
  "language_models": {
    "deepseek": {
      "api_url": "https://api.deepseek.com/v1",
      "available_models": [
        {
          "name": "deepseek-v4-flash",
          "display_name": "DeepSeek V4 Flash",
          "max_tokens": 1000000,
          "max_output_tokens": 384000
        },
        {
          "name": "deepseek-v4-pro",
          "display_name": "DeepSeek V4 Pro",
          "max_tokens": 1000000,
          "max_output_tokens": 384000
        }
      ]
    }
  }
}

xAI

如果你有 xAI 的 API key，可以使用 xAI API 访问。

在 xAI Console 中创建 API key。
通过 {#action agent::OpenSettings} 打开 Agent Settings，进入 xAI 部分。
填入你的 xAI API key。

Zed 也会从本地 Zed 进程的环境变量中读取 XAI_API_KEY。

自定义 xAI 模型

如果需要使用其他 Grok 模型 ID、自定义上限、图片支持或自定义 endpoint，可以添加自定义 xAI 模型。

{
  "language_models": {
    "x_ai": {
      "api_url": "https://api.x.ai/v1",
      "available_models": [
        {
          "name": "grok-1.5",
          "display_name": "Grok 1.5",
          "max_tokens": 131072,
          "max_output_tokens": 8192
        },
        {
          "name": "grok-1.5v",
          "display_name": "Grok 1.5V (Vision)",
          "max_tokens": 131072,
          "max_output_tokens": 8192,
          "supports_images": true
        }
      ]
    }
  }
}

OpenCode API

如果你有 OpenCode 的 API key，可以使用 OpenCode API 访问。OpenCode Zen 和 Go 会影响可用的 OpenCode 模型。

Zed 不会使用 OAuth 登录 OpenCode，也不会检测你的 OpenCode 订阅状态；它使用保存在系统钥匙串或 `OPENCODE_API_KEY` 环境变量中的 OpenCode API 密钥。

访问 OpenCode 控制台并创建账户。
若要使用 Zen 或 Go 模型，请确保你有足够的信用额度或有效的订阅。在 Zed 的 Agent 中将 OpenCode 作为提供商时，无法使用 OpenCode 免费模型。你可以通过ACP 将 OpenCode 作为外部 Agent 运行来在 Zed 中使用这些模型。
在 OpenCode 控制台的 API Keys 部分生成一个 API 密钥。
通过 {#action agent::OpenSettings} 打开 Agent 设置，然后前往 OpenCode 部分。
输入你的 OpenCode API 密钥。

Zed 也会从本地 Zed 进程环境中读取 `OPENCODE_API_KEY`。默认情况下，会显示所有 OpenCode 订阅类型的模型。你可以在提供商界面或设置中隐藏与你无关的订阅：

{
  "language_models": {
    "opencode": {
      "show_zen_models": false,
      "show_go_models": true
    }
  }
}

自定义 OpenCode 模型

Zed Agent 预配置了 OpenCode 模型。当你需要更新的模型或使用自定义端点的模型时，可以添加自定义 OpenCode 模型。在设置文件中添加自定义模型：

{
  "language_models": {
    "opencode": {
      "available_models": [
        {
          "name": "my-custom-model",
          "display_name": "My Custom Model",
          "max_tokens": 123456,
          "max_output_tokens": 98765,
          "protocol": "openai_chat",
          "reasoning_effort_levels": ["low", "medium", "high", "max"],
          "interleaved_reasoning": false,
          "subscription": "go",
          "custom_model_api_url": "https://example.com/zen"
        }
      ]
    }
  }
}

自定义 OpenCode 模型的可用配置选项包括：

name (必需)：OpenCode 使用的模型 ID，例如 glm-9000
display_name（可选）：在 UI 中显示的人类可读模型名称，例如 Custom GLM 9000
max_tokens（必填）：模型最大上下文窗口大小，例如 1000000
max_output_tokens（可选）：模型可生成的最大 token 数，例如 64000
protocol（可选，默认 "openai_chat"）：模型 API 协议，取值之一为 "anthropic"、"openai_responses"、"openai_chat" 或 "google"
reasoning_effort_levels（可选）：支持的推理力度级别列表，例如 ["none", "low", "medium", "high", "xhigh", "max"]。列表中的最后一个值将被用作默认级别
interleaved_reasoning（可选，默认 false）：思考 token 是否通过专用的 reasoning_content 字段发送。仅在使用 openai_chat 协议时生效
subscription（可选）："zen" 或 "go"；默认为 "zen"
custom_model_api_url（可选）：自定义 API 基础 URL，用于替代默认的 OpenCode API

自定义 OpenCode 模型会列在 Agent 面板的模型下拉菜单中。

Anthropic 兼容端点

当服务实现了 Anthropic 的 Messages API（/v1/messages），并提供了自定义基础 URL、模型 ID 和 API key 时，可使用 Anthropic 兼容端点。

你可以通过 {#action agent::OpenSettings} 在 Agent 设置中添加自定义 Anthropic 兼容提供商。请在 LLM Providers 部分找到 Add Provider，选择 Anthropic，并填写提供商名称、API URL、模型 ID 和上下文窗口。

你也可以在配置文件中设置该提供商：

{
  "language_models": {
    "anthropic_compatible": {
      "Some Provider": {
        "api_url": "https://api.someprovider.com",
        "custom_headers": {
          "X-Some-Header": "some-value"
        },
        "available_models": [
          {
            "name": "some-model",
            "display_name": "Some Model",
            "max_tokens": 200000,
            "max_output_tokens": 32000,
            "capabilities": {
              "tools": true,
              "images": false,
              "prompt_caching": false
            }
          }
        ]
      }
    }
  }
}

默认情况下，与 Anthropic 兼容的模型会继承以下能力配置：

tools：true
images：false
prompt_caching：false

开启 prompt_caching 后，会为提示词缓存发送显式的 cache_control 断点；如果服务商不支持包含这些断点的请求，则保持关闭。

可选的 custom_headers 映射会为每个请求添加额外的请求头，某些服务商有此要求。由 Zed 管理的请求头（如 X-Api-Key 和 Anthropic-Version）无法被覆盖。

模型还支持几个可选字段：default_temperature、extra_beta_headers（以 anthropic-beta 请求头发送）、mode 和 tool_override，其行为与自定义 Anthropic 模型中所述一致。

在服务商设置界面中输入 API key，或设置对应的环境变量（<PROVIDER_NAME>_API_KEY；上例中为 SOME_PROVIDER_API_KEY）。不要把 API key 写进 settings.json。

OpenAI 兼容端点

如果你有自定义的 base URL、模型 ID 和 API key，可以使用 OpenAI 兼容端点。

通过 {#action agent::OpenSettings} 打开 Agent Settings，即可添加自定义的 OpenAI 兼容服务商。在 LLM Providers 区域找到 Add Provider，填入服务商名称、API URL、模型 ID 和上下文窗口大小即可。

你也可以在设置文件中配置提供商：

{
  "language_models": {
    "openai_compatible": {
      "my-provider": {
        "api_url": "https://example.com/v1",
        "available_models": [
          {
            "name": "my-model",
            "display_name": "My Model",
            "max_tokens": 128000
          }
        ]
      }
    }
  }
}

默认情况下，OpenAI 兼容模型继承以下功能配置：

tools：true
images：false
parallel_tool_calls：false
prompt_cache_key：false
chat_completions：true
interleaved_reasoning：false
max_tokens_parameter：false

如果模型仅支持 Responses API，请将 capabilities.chat_completions 设为 false。Zed 将对该模型使用 Responses 端点。

对于推理模型（如 GPT-5），请将 reasoning_effort 设为你的端点所支持的、非 none 的 effort 等级。这会在 Agent 面板中启用思考功能，并告知 Zed 在启用思考时应发送哪个 effort。在添加 OpenAI 兼容提供商时，提供商设置界面可以配置此参数。Zed 会在 chat-completions 请求中发送 OpenAI 风格的 reasoning_effort。

如果模型需要 Responses API 来处理推理状态，请将 capabilities.chat_completions 设为 false：

{ "language_models": { "openai_compatible": { "my-provider": { "api_url": "https://example.com/v1", "available_models": [ { "name": "gpt-5", "max_tokens": 272000, "reasoning_effort": "high", "capabilities": { "tools": true, "images": false, "parallel_tool_calls": false, "prompt_cache_key": false, "chat_completions": false, "interleaved_reasoning": false, "max_tokens_parameter": false } } ] } } } }

有效的设置值包括 "none"、"minimal"、"low"、"medium"、"high"、"xhigh" 和 "max"。如果需要强制禁用某端点的推理功能，请在 settings.json 中使用 "none"；对于支持思考功能的模型，提供商的设置界面会展示除 none 以外的其他数值。对于希望将先前的思考内容通过专用的 reasoning_content 字段接收的 chat-completions 端点，还需将 capabilities.interleaved_reasoning 设为 true。若端点期望使用 max_tokens 而非 max_completion_tokens 来指定输出令牌限制，请将 capabilities.max_tokens_parameter 设为 true。

例如，一个具有最大 OpenAI 风格推理强度、支持流式思考以及 max_tokens 输出限制的 chat-completions 端点，可以配置如下：

{
  "language_models": {
    "openai_compatible": {
      "my-reasoning-provider": {
        "api_url": "https://example.com/v1",
        "available_models": [
          {
            "name": "reasoning-model",
            "max_tokens": 1000000,
            "max_output_tokens": 128000,
            "reasoning_effort": "max",
            "capabilities": {
              "tools": true,
              "images": false,
              "parallel_tool_calls": false,
              "prompt_cache_key": false,
              "chat_completions": true,
              "interleaved_reasoning": true,
              "max_tokens_parameter": true
            }
          }
        ]
      }
    }
  }
}

请在提供商设置界面中输入 API 密钥，或设置生成的环境变量。不要把 API 密钥写进 settings.json。

第27章 Zed 编辑器中的 Inline AI 代码编辑

第29章 Zed 集成现有 AI 订阅：ChatGPT、Claude 与 Copilot 接入指南