# 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 ```sh npm install -g openai-ws-opencode openai-ws-opencode setup --global opencode auth login openai-ws ``` For project-local setup: ```sh 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 ` output: ```jsonc { "$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-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 ` - `ChatGPT-Account-ID` when available - `originator: codex-tui` - `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: ```sh bun install bun run build npm pack ``` Then point OpenCode at the packed tarball through the plugin array: ```jsonc { "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): ```sh bun scripts/ws-load-harness.ts --streams 1000 --mode cold --json ``` Modes: `cold`, `warm`, `blackhole`, `slow-reader`, `abrupt-close`, `provider-limit`. ## Development ```sh 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.