Zed 接入

当你希望 Zed 访问 ProxAI，而不是直接访问 provider 时，用这页。ProxAI 保持本地运行，接收 OpenAI 兼容请求，再转发到配置好的上游 provider。

接入检查表

1
本地运行 ProxAI
目标: 先启动本地代理，再配置 Zed。
操作
- 使用目标 config.toml 启动 ProxAI。
- 从 [server] 或临时 CLI override 确认本地端口。
验证: 基础请求能到达本地 listener，而不是直接访问上游 provider。
快速开始 CLI 参考
2
让 Zed 指向本地 base URL
目标: 让 Zed 使用 ProxAI 作为 OpenAI 兼容 endpoint。
操作
- 使用 ProxAI 本地 base URL，通常是 http://127.0.0.1:<port>/v1。
- 如果客户端要求 key，可以使用本地 client key；上游 provider key 应放在 ProxAI provider 配置里。
验证: ProxAI 日志能看到入站请求和选中的 route/provider。
客户端接入观测与诊断
3
让 endpoint 匹配目标入站协议
目标: 让 ProxAI 从请求 path 检测真实 request protocol。
操作
- /v1/responses 对应 openai_responses。
- /v1/chat/completions 对应 openai_chat_completions。
- 只有当相同 model pattern 需要 endpoint-specific 行为时，才加 route request_protocol。
验证: 路由选择使用预期入站协议，显式 protocol guard 不会静默 fall through。
协议路由匹配
4
窄范围调试流式/工具症状
目标: 只 capture 解释 Zed 可见问题所需的 phase。
操作
- 工具调用卡住时，优先看 upstream_response 或 outbound_response capture。
- 未经脱敏不要分享完整 capture；其中可能包含 prompt、工具参数或 provider 输出。
验证: 终止事件、stop reason 或 stream translation error 能解释客户端症状。
流式与工具调用 Capture phases

应该配置在哪里

事项	归属位置
Zed base URL	Zed 客户端设置，指向 ProxAI 本地 `/v1` base URL
本地 client key 要求	如果客户端集成要求，放在 Zed/client 设置中
Provider API key	`config.toml` provider 配置或支持的环境展开，不要写进文档或 capture
模型到 provider 的路由	`config.toml` 中的 `[[routes]]` 和 `[routing.defaults]`
Provider 协议行为	`providers.<name>.protocol`
临时端口/上游 override	短期本地测试用 CLI flags

常见 Zed 决策

Zed 使用 Responses

场景: 客户端发送 /v1/responses 请求。

选择: 只有 endpoint-specific route 需要 request_protocol = "openai_responses"；其他情况让 path 检测处理。

原因: Responses 有更丰富的 output item、工具事件和终态语义。

Provider 使用 Anthropic Messages

场景: 上游 provider 期望 Anthropic Messages wire payload。

选择: 将选中 provider 设置为 protocol = "anthropic_messages"。

原因: Provider protocol 控制出站 wire 行为；provider 名称只是用户标签。

工具流看起来卡住

场景: Zed 在工具调用参数或终止事件不完整时等待。

选择: 先检查 streaming/tool-call 行为和语义 timeout，再改路由。

原因: 流式回归是用户可见的，而且通常只发生在某个 phase。

错误不好读

场景: Zed 展示的本地错误过于紧凑。

选择: 临时使用 JSON error responses，并开启窄 phase capture。

原因: 默认保持可读，调试时再拿结构化诊断。

Zed thinking 设置与模型变体

Zed 对 OpenAI-compatible reasoning 模型有两层相关但不同的配置：

层级	字段	含义
`language_models.openai_compatible.<provider>.available_models[]`	`name`, `display_name`, `reasoning_effort`, `capabilities`	定义 OpenAI-compatible provider 暴露的模型。这里的 `reasoning_effort` 是 provider-model 默认值；只要不是 `none`，Zed 就认为该模型支持 thinking。
`agent.default_model` 和 `agent.favorite_models[]`	`provider`, `model`, `enable_thinking`, `effort`	定义 Agent UI 选择哪个模型。这里要用 `effort`，不是 `reasoning_effort`，来指定该选择的默认 thinking effort。

单个模型建议两层都显式配置：

{
  "language_models": {
    "openai_compatible": {
      "proxai": {
        "api_url": "http://127.0.0.1:18080/v1",
        "available_models": [
          {
            "name": "gpt-5.5",
            "display_name": "GPT-5.5",
            "reasoning_effort": "high",
            "max_tokens": 400000,
            "max_output_tokens": 128000,
            "max_completion_tokens": 128000,
            "capabilities": {
              "tools": true,
              "images": true,
              "parallel_tool_calls": true,
              "prompt_cache_key": true,
              "chat_completions": false,
              "interleaved_reasoning": true
            }
          }
        ]
      }
    }
  },
  "agent": {
    "default_model": {
      "provider": "proxai",
      "model": "gpt-5.5",
      "enable_thinking": true,
      "effort": "high"
    }
  }
}

最终 effort 的优先级是：

当前 thread/UI 选择的 effort。
agent.default_model.effort 或匹配的 agent.favorite_models[].effort。
language_models.openai_compatible.<provider>.available_models[].reasoning_effort。

模型本身仍必须在 provider-model 层声明支持 thinking：对 OpenAI-compatible 模型来说，就是配置了非 none 的 reasoning_effort。

给同一个上游模型提供多个 Zed 入口

Zed 的 Agent 模型身份是 provider/model，其中 model 来自 provider model 的 name。display_name、enable_thinking、effort、reasoning_effort 都不参与模型身份或 favorite-model 去重。因此，不要试图用多个相同 provider 和 model 的 favorite_models 条目仅靠不同 effort 做变体。

正确做法是暴露不同的 provider model name，再让 ProxAI 把这些 alias rewrite 到同一个真实上游模型：

{
  "language_models": {
    "openai_compatible": {
      "proxai": {
        "api_url": "http://127.0.0.1:18080/v1",
        "available_models": [
          {
            "name": "gpt-5.5-low",
            "display_name": "GPT-5.5 Low",
            "reasoning_effort": "low",
            "max_tokens": 400000,
            "max_output_tokens": 128000,
            "max_completion_tokens": 128000,
            "capabilities": { "tools": true, "chat_completions": false }
          },
          {
            "name": "gpt-5.5-high",
            "display_name": "GPT-5.5 High",
            "reasoning_effort": "high",
            "max_tokens": 400000,
            "max_output_tokens": 128000,
            "max_completion_tokens": 128000,
            "capabilities": { "tools": true, "chat_completions": false }
          }
        ]
      }
    }
  },
  "agent": {
    "favorite_models": [
      {
        "provider": "proxai",
        "model": "gpt-5.5-low",
        "enable_thinking": true,
        "effort": "low"
      },
      {
        "provider": "proxai",
        "model": "gpt-5.5-high",
        "enable_thinking": true,
        "effort": "high"
      }
    ]
  }
}

然后在 config.toml 里将 gpt-5.5-low 和 gpt-5.5-high 路由或 rewrite 到真实上游模型。这样 Zed 模型选择器里不会混淆，长期路由仍集中在 ProxAI 管理。

隐私提示

Zed 接入可能包含私有 prompt、工具调用、文件片段和 provider 输出。ProxAI 不应记录 request bodies、Authorization headers、API keys 或不必要的私有上游 URL 细节。Capture 是本地调试产物，应视为敏感数据。

分享日志或 capture 前，先看隐私与本地数据和环境与文件。

Zed 接入

Zed 接入

接入检查表

本地运行 ProxAI

让 Zed 指向本地 base URL

让 endpoint 匹配目标入站协议

窄范围调试流式/工具症状

应该配置在哪里

常见 Zed 决策

Zed thinking 设置与模型变体

给同一个上游模型提供多个 Zed 入口

隐私提示