dsh-openai-codex
OpenAI Codex (ChatGPT subscription) authentication and LLM provider for
deepseek-harness.
This plugin adds:
- A Settings card (web) with a “Sign in with OpenAI Codex” button —
OAuth against
auth.openai.com, backed by your ChatGPT/Codex subscription.
- The
codex LLM provider, exposing subscription models (e.g.
gpt-5.5) to any model-routing configuration in DSH.
There is no API key to paste: the plugin performs the same OAuth sign-in flow
as the Codex CLI (browser or device code), then keeps the credential refreshed
in DSH's own credential store.
Install
From inside a DSH profile directory (or with --profile), add the plugin
bundle:
dsh plugin --profile <name> add ./dsh-openai-codex
This consumes the bundle's patch (cordis.patch.yml), installing the
openai-codex plugin and wiring its client (Settings card). After install,
refresh the web GUI.
Authenticate
- Open Settings → Plugins (or the provider settings card).
- In the OpenAI Codex card, click Sign in with OpenAI Codex.
- A browser tab opens to
auth.openai.com (interactive login). Or use
Device code to get a one-time code to enter at
https://auth.openai.com/codex/device.
- Grant access; the plugin stores the OAuth credential envelope in DSH's
credential store (
$DSH_HOME/.credentials.yaml). The account id is
derived from the access-token JWT and used for the chatgpt-account-id
header.
On sign-out, the stored credential is cleared.
Use the provider
Select provider codex and a model in your model-routing config, e.g. in
cordis.yml:
llm:
routes:
- provider: codex
model: gpt-5.5
Available catalog models (configurable under the openai-codex settings
namespace): gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.3-codex-spark,
gpt-5.2, gpt-5-4-mini.
Configuration
All keys live under the plugin's settings namespace. With openai-codex
scoped globally, you can set defaults directly:
openai-codex:
# Reasoning effort applied when a request omits one.
reasoningEffort: high # off | low | medium | high | max
# Default output budget.
maxTokens: 128000
# Advisory context window for models without an exact catalog value.
defaultContextWindow: 400000
# Text verbosity.
verbosity: low # low | medium | high
# Refresh the access token this far before expiry.
refreshBeforeMs: 300000
# Drop an in-flight request after this much provider idle time.
streamIdleTimeoutMs: 30000
# Strip model-emitted redundant `sandbox_permissions: "workspace-write"` from
# tool calls before the harness sees them (kept when a sandbox denial in the
# conversation makes it a legitimate retry; genuine escalations preserved).
sanitizeSandboxPermissions: true
# Override the codex Responses endpoint (advanced/debugging).
baseURL: https://chatgpt.com/backend-api/codex/responses
Unset optional keys (reasoningEffort, verbosity, retryPolicy) fall back
to provider defaults.
How it works
- Host half (
src/index.ts): registers the codex LLM adapter + a
configurable provider, the credential store (OPENAI_CODEX_CREDENTIAL), a
settings namespace, and an RPC channel (/rpc-codex) the Settings card calls
to start/poll OAuth.
- Client half (
src/client): a React card injected into
settings.plugin.item; talks to the Host through the generic Connection RPC
bridge (authority: loopback).
- OAuth (
src/oauth): PKCE S256; interactive browser redirect to
http://127.0.0.1:1455/auth/callback or the device-code flow; token refresh
via the refresh_token grant.
- Codex wire (
src/codex): POST /backend-api/codex/responses, SSE, parsed
with eventsource-parser; Responses events are translated into harness
StreamChunks (text / reasoning / tool-call blocks, usage-before-finish).
Development
This checkout is a standalone package whose @deepseek-ai/* peer deps resolve
from a deepseek-harness checkout when installed into a profile (via
dsh plugin add), and from that same checkout's node_modules (symlinked under
node_modules/) when building/testing locally. The .npmrc sets
verify-deps-before-run=false so pnpm doesn't try to re-install the peer deps
here — do not run pnpm install in this directory expecting it to fetch them
from npm.
pnpm build # emits lib/index.js (Host ESM) + lib/client.js (browser bundle)
pnpm typecheck # tsc --noEmit over src + tests
pnpm test # vitest run (unit tests)
Before the first local build/typecheck/test, node_modules must expose the
toolchain and the @deepseek-ai/* sources. Recreate the symlink farm once,
pointing at your deepseek-harness checkout:
scripts/setup-local-dev.sh /absolute/path/to/deepseek-harness
The build ships the prebuilt lib/, so end users installing via dsh plugin add never need to build.
The browser client bundle artifact is the loader-wrapped CJS
(window.__ModuleLoader__.load({ id, factory: (require) => … })) the
client-module system serves at /plugins/dsh-openai-codex/client.js.
Layout
src/index.ts Host plugin entry (apply)
src/oauth/ PKCE, JWT account-id, callback server, OAuth flows
src/codex/ Responses wire: types, serialization, SSE, translate
src/codex/adapter.ts LlmAdapter implementing stream/listModels/resolveModel
src/client/ Settings card, RPC bridge, locales
test/ unit tests (vitest)
Notes / caveats
- The interactive login binds a localhost port (
1455) to catch the OAuth
redirect. A firewall or container can prevent this; the device-code flow
is the portable fallback.
- Codex streams are long-lived; the adapter ties liveness to a per-request
idle timeout and honors DSH's request abort signal.
- OAuth token expiry cannot be observed by this plugin in this environment;
expiry is derived from the issued
expires_in, and refresh is re-attempted
pre-emptively before each request near expiry.
