OpenAI Responses Provider

Docs home · Provider guide · Configuration · DeepSeek · OpenAI-compatible · Anthropic · Gemini · 简体中文

Use this provider when your selected model is served by the OpenAI Responses API at /v1/responses. It is separate from the OpenAI-compatible provider, which speaks the Chat Completions protocol and is intended for compatible gateways.

Minimal Setup

For temporary local use:

export SIGIL_OPENAI_RESPONSES_API_KEY="sk-..."
sigil

For a reusable config:

[agent]
provider = "openai_responses"
model = "gpt-4.1"
tool_timeout_secs = 30

[model_request]
request_timeout_secs = 120
stream_idle_timeout_secs = 180

[providers.openai_responses]
base_url = "https://api.openai.com/v1"
# Prefer SIGIL_OPENAI_RESPONSES_API_KEY.
# api_key = "sk-..."
organization = "org_..."
project = "proj_..."

A full starting template is available at openai-responses.toml.

Authentication

Sigil resolves Responses authentication in this order:

1. SIGIL_OPENAI_RESPONSES_API_KEY
2. [providers.openai_responses].api_key

Optional organization and project fields are only needed for accounts that require them.

Environment Overrides

Behavior Notes

The provider streams text, supported reasoning deltas, tool calls, and usage from the Responses event stream. It preserves each completed native output-item array as opaque provider state and reuses it unchanged for the matching assistant turn on later requests. This protects provider-specific items such as encrypted reasoning content without changing the Chat Completions provider contract.

Normal requests use the full local session context and do not use remote response-handle continuation. Background requests and provider-hosted tools are not enabled on this provider. The native compact endpoint is not a user action.

Image attachments are available only for model IDs that Sigil explicitly recognizes as image-capable, including supported dated snapshots. Unknown IDs and malformed or unrecognized aliases fail before provider transport; Sigil does not infer image support from the endpoint alone. See Image Attachments for input methods, local limits, cache behavior, and resume guidance.

Guarded overflow recovery is enabled only for the official https://api.openai.com/v1 endpoint and exact gpt-4.1-2025-04-14 snapshot after a provider-confirmed context-window rejection before output or side effects. Its request/session-owned preparation records separate non-generating measurements for the rejected request and compacted target, then requires exact before/after savings and target-fit proof before one frozen retry. Aliases, compatible endpoints, ordinary errors, count failures, stale frontiers, restored sessions, and recursive recovery remain excluded.

Verify

Run:

sigil doctor

Check that [agent].provider is openai_responses, the base URL includes the expected /v1 path, and the key source is SIGIL_OPENAI_RESPONSES_API_KEY or your local config.

Common Problems