Zed Integration

Zed Integration

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.

Local proxy boundary

Zed sends requests to ProxAI’s local base URL. ProxAI then routes by inbound protocol, model, and provider configuration. Keep long-lived routing in config.toml, not in ad hoc client settings.

Connection checklist

1. 1

   Run ProxAI locally

   Goal: Start the local proxy before configuring Zed.

   Do

   • Run ProxAI with your chosen config.toml.
   • Confirm the configured local port from [server] or your temporary CLI override.

   Verify: A basic health/request check reaches the local listener rather than the upstream provider directly.

   Quick StartCLI Reference
2. 2

   Point Zed at the local base URL

   Goal: Make Zed use ProxAI as the OpenAI-compatible endpoint.

   Do

   • Use the ProxAI local base URL, usually http://127.0.0.1:<port>/v1.
   • Use a local client key if the client requires one; upstream provider keys belong in ProxAI provider configuration.

   Verify: ProxAI logs show the inbound request and the selected route/provider.

   Client IntegrationObservability
3. 3

   Match the endpoint to the desired inbound protocol

   Goal: Let ProxAI detect the actual request protocol from the request path.

   Do

   • Use /v1/responses for openai_responses clients.
   • Use /v1/chat/completions for openai_chat_completions clients.
   • Only add route 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.

   ProtocolsRoute Matching
4. 4

   Debug streaming/tool-call symptoms narrowly

   Goal: Capture only the phase needed to explain a Zed-visible issue.

   Do

   • For stalled tool calls, start with upstream_response or outbound_response captures.
   • Do not share full captures without redaction; they may contain prompts, tool arguments, or provider output.

   Verify: The terminal event, stop reason, or stream translation error explains the client symptom.

   Streaming and ToolsCapture Phases

What to configure where

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

Common Zed-facing decisions

Zed uses Responses

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.

Provider speaks Anthropic Messages

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.

Tool stream appears stuck

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.

Error is hard to read

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.

Privacy notes

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.