Use this page when Zed should talk to ProxAI instead of a provider directly. ProxAI stays local, accepts OpenAI-compatible requests, and forwards them to the configured upstream provider.
Goal: Start the local proxy before configuring Zed.
config.toml.[server] or your temporary CLI override.Verify: A basic health/request check reaches the local listener rather than the upstream provider directly.
Goal: Make Zed use ProxAI as the OpenAI-compatible endpoint.
http://127.0.0.1:<port>/v1.Verify: ProxAI logs show the inbound request and the selected route/provider.
Goal: Let ProxAI detect the actual request protocol from the request path.
/v1/responses for openai_responses clients./v1/chat/completions for openai_chat_completions clients.request_protocol when the same model pattern needs endpoint-specific behavior.Verify: Route selection uses the expected inbound protocol and does not silently fall through across explicit protocol guards.
Goal: Capture only the phase needed to explain a Zed-visible issue.
upstream_response or outbound_response captures.Verify: The terminal event, stop reason, or stream translation error explains the client symptom.
| Concern | Where it belongs |
|---|---|
| Zed base URL | Zed client settings, pointing to ProxAI local /v1 base URL |
| Local client key requirement | Zed/client settings if required by the client integration |
| Provider API key | config.toml provider config or supported environment expansion, never in docs or captures |
| Model-to-provider routing | [[routes]] and [routing.defaults] in config.toml |
| Provider protocol behavior | providers.<name>.protocol |
| Temporary port/upstream override | CLI flags for short-lived local tests |
When: The client sends /v1/responses requests.
Choose: request_protocol = "openai_responses" only for endpoint-specific routes; otherwise let path detection handle it.
Why: Responses has richer output item semantics, tool events, and terminal status behavior.
When: The upstream provider expects Anthropic Messages wire payloads.
Choose: Set the selected provider protocol = "anthropic_messages".
Why: Provider protocol controls outbound wire behavior; provider names are just labels.
When: Zed waits while tool-call arguments or terminal events are incomplete.
Choose: Inspect streaming/tool-call behavior and semantic timeout settings before changing routing.
Why: Streaming regressions are user-visible and are often phase-specific.
When: Zed surfaces a compact local error without enough detail.
Choose: Temporarily use JSON error responses and a narrow capture phase.
Why: This keeps the default readable while preserving structured diagnostics during debugging.
Zed uses two related but different setting layers for OpenAI-compatible reasoning models:
| Layer | Fields | Meaning |
|---|---|---|
`language_models.openai_compatible.<provider>.available_models[]` | name, display_name, reasoning_effort, capabilities | Defines the model exposed by the OpenAI-compatible provider. reasoning_effort here is the provider-model default and makes the model support thinking when it is not none. |
`agent.default_model` and `agent.favorite_models[]` | provider, model, enable_thinking, effort | Selects a model for the Agent UI. Use effort, not reasoning_effort, to choose the default thinking effort for that selection. |
For a single model, configure both layers explicitly:
{ "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" } }}The effective effort order is:
agent.default_model.effort or the matching agent.favorite_models[].effort.language_models.openai_compatible.<provider>.available_models[].reasoning_effort.The model must still advertise thinking support at the provider-model layer: for OpenAI-compatible models, that means reasoning_effort is present and not none.
Zed identifies Agent models by provider/model, where model is the provider model name. display_name, enable_thinking, effort, and reasoning_effort do not participate in model identity or favorite-model de-duplication. Therefore, do not create multiple favorite_models entries with the same provider and model just to vary effort.
Instead, expose distinct provider model names and let ProxAI rewrite those aliases to the same upstream model:
{ "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" } ] }}Then route or rewrite gpt-5.5-low and gpt-5.5-high to the real upstream model in config.toml. This keeps Zed’s model selector unambiguous while keeping upstream routing centralized in ProxAI.
Zed integration can involve private prompts, tool calls, file snippets, and provider output. ProxAI should not log request bodies, Authorization headers, API keys, or private upstream URL details. Captures are local debugging artifacts and should be treated as sensitive.
See Privacy and Local Data and Environment and Files before sharing logs or captures.