openai-ws-opencode

Standalone OpenCode provider plugin for routing OpenAI Responses API streaming requests over WebSocket transport.

What it provides

• Provider id: openai-ws
• API-key transport: wss://api.openai.com/v1/responses
• Realtime transport: wss://api.openai.com/v1/realtime for gpt-realtime-* models (text in/out, tool calls, accurate context windows: 128k/32k out for gpt-realtime-2.1, 2.1-mini, and 2; 32k/4k out for gpt-realtime-1.5 and mini)
• Realtime reasoning variants: minimal, low, medium, high, and xhigh for gpt-realtime-2.1, gpt-realtime-2.1-mini, and gpt-realtime-2; reasoning is omitted for gpt-realtime-1.5 and gpt-realtime-mini
• ChatGPT/Codex OAuth transport: wss://chatgpt.com/backend-api/codex/responses
• Curated GPT/Codex model table with OpenCode variants
• Auth-aware model discovery at auth-load time: Codex backend models for ChatGPT OAuth, OpenAI /v1/models IDs for API keys, bundled table fallback for both
• Setup-time promotion of live Codex WebSocket models, including newly released GPT-5 families without package updates
• WebSocket-to-SSE bridge so OpenCode can keep using its normal streaming path
• Priority service tier pinned on WebSocket and HTTP fallback requests
• Bounded socket admission, reconnects, inbound queues, and circuit breaking for high-concurrency use

Install

npm install -g openai-ws-opencode
openai-ws-opencode setup --global
opencode auth login openai-ws

For project-local setup:

openai-ws-opencode setup --project
opencode auth login openai-ws

The setup command is idempotent. It adds the npm plugin entry and a fallback provider.openai-ws model registry to opencode.json, preserving existing user model overrides.

At setup and runtime the plugin attempts short best-effort model discovery for the selected auth mode. ChatGPT/Codex OAuth uses https://chatgpt.com/backend-api/codex/models, accepts provider models or data catalogs, and maps flat or nested model metadata. It resolves the current Codex alpha version from npm's small dist-tags response and caches it for inference identity headers. API-key auth uses https://api.openai.com/v1/models to discover GPT-5 family IDs. Setup writes discovered WebSocket-capable models into opencode.json; runtime refreshes the active provider from the authenticated catalog. Both paths remain fail-soft and fall back to the bundled table if discovery is unavailable.

The transport allows one active turn per session scope. A concurrent turn for the same session fails fast to HTTP fallback; independent sessions can use separate sockets in parallel.

On normal same-socket turns, the plugin attaches the prior previous_response_id only when the new OpenCode input exactly extends the completed conversation, and sends only the new suffix. Prefix mismatches safely send full history without a cursor. Compaction-agent requests always send full history, while caller-supplied continuation IDs remain untouched.

Set OPENAI_WS_OPENCODE_SKIP_CATALOG=1 to skip runtime catalog lookups and use only the bundled fallback table plus your config overrides.

Realtime reasoning is selected with OpenCode's normal variant picker. The plugin maps the selected variant to response.create.response.reasoning.effort; it does not put reasoning on session.update. The 2.x Realtime models support minimal, low, medium, high, and xhigh. The 1.5 and legacy mini models do not accept Realtime reasoning, so they expose no reasoning variants.

Manual config

If you do not want to use the setup command, add this shape to your OpenCode config and copy model entries from openai-ws-opencode setup --path <temp-file> output:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["openai-ws-opencode@latest"],
  "provider": {
    "openai-ws": {
      "name": "OpenAI WebSocket",
      "api": "https://api.openai.com/v1",
      "npm": "@ai-sdk/openai",
      "models": {
        "gpt-5.3-codex": {
          "name": "GPT 5.3 Codex (WebSocket)",
          "reasoning": true,
          "temperature": false,
          "attachment": true,
          "tool_call": true,
          "limit": { "context": 258400, "output": 128000 },
          "modalities": { "input": ["text", "image"], "output": ["text"] },
          "options": {},
          "provider": { "npm": "@ai-sdk/openai", "api": "https://api.openai.com/v1" }
        }
      }
    }
  }
}

Auth modes

API key

Choose OpenAI (WebSocket) - API Key during opencode auth login openai-ws.

This path uses the public OpenAI Responses WebSocket endpoint and sends:

• Authorization: Bearer <OPENAI_API_KEY>
• OpenAI-Beta: responses_websockets=2026-02-06

ChatGPT/Codex OAuth

Choose the browser or headless ChatGPT Pro/Plus OAuth option during opencode auth login openai-ws.

This path uses the Codex/ChatGPT backend and sends:

• Authorization: Bearer <access-token>
• ChatGPT-Account-ID when available
• originator: codex-tui
• version: <current Codex alpha version>
• x-codex-beta-features: remote_compaction_v2

The OAuth Responses WebSocket is GA, so this path omits OpenAI-Beta.

Important: the OAuth/Codex WebSocket path is unofficial, reuses Codex OAuth behavior, targets a private ChatGPT backend, can break without notice, and may carry account or terms-of-service risk. This project is not affiliated with OpenAI or OpenCode.

Local development install

From this repo:

bun install
bun run build
npm pack

Then point OpenCode at the packed tarball through the plugin array:

{
  "plugin": ["openai-ws-opencode@file:/absolute/path/openai-ws-opencode-0.1.5.tgz"]
}

Direct file:///absolute/path/dist/index.js imports are useful for debugging, but npm/tarball installs better match how OpenCode resolves dependencies.

Scale controls and load harness

Transport limits are boot-latched from env at process start. Defaults: process max sockets 64, provider max 32, max connecting 8, prewarm max connecting 2 with demand reserve 1, one active connection/turn per session scope, per-stream queue 1024 messages / 16 MiB, aggregate queue 256 MiB.

Raising OPENAI_WS_PROCESS_MAX_SOCKETS above 64 requires positive OPENAI_WS_SHED_MAX_SESSIONS, OPENAI_WS_SHED_LAG_MS, and OPENAI_WS_SHED_RSS_MB, and the aggregate queue must be at most 25% of that RSS guard.

Deterministic local harness (no live OpenAI):

bun scripts/ws-load-harness.ts --streams 1000 --mode cold --json

Modes: cold, warm, blackhole, slow-reader, abrupt-close, provider-limit.

Development

bun install
bun run lint
bun run typecheck
bun run test
bun run build
npm pack --dry-run

The root package export intentionally exposes only the OpenCode plugin function because OpenCode calls every function exported by the root module. Test helpers are available from openai-ws-opencode/testing.

Troubleshooting

• Provider is not visible: run openai-ws-opencode setup --global or add provider.openai-ws manually.
• Missing auth: run opencode auth login openai-ws.
• OAuth refresh failed: re-run opencode auth login openai-ws and choose a ChatGPT OAuth method.
• Expired or invalid OAuth: OpenCode still starts and other providers remain available; log in to openai-ws again before selecting its models.
• WebSocket 401/403: verify the selected auth mode and account entitlement. OAuth/Codex behavior may change upstream.
• Local file:// install cannot find ws: use the packed tarball install path or add dependencies to your OpenCode config directory.