dsh-llm-openai-codex
Use a ChatGPT Plus, Pro, Business, or Enterprise subscription with Codex access as a DeepSeek Harness model provider.
This plugin adds the openai-codex route to DSH.
It uses OpenAI Codex OAuth, not OPENAI_API_KEY.
It uses pi-ai's Codex backend at https://chatgpt.com/backend-api.
Table of Contents
Background
The existing pi-ai adapter in DeepSeek Harness authenticates provider routes with API keys alone.
pi-ai's OAuth-backed providers have no key to resolve, so its own validation refuses them.
This plugin closes that gap for OpenAI's Codex backend: it reuses the pi-ai catalog's openai-codex provider and the generic pi-ai request machinery, and answers each request's credential with a ChatGPT OAuth access token.
The token is loaded from either a DSH-managed credential file or the Codex CLI's shared auth file, and refreshed when it nears expiry.
pi-ai derives the Codex request headers from that token, so the backend sees only a normal Codex client.
The paired Web card starts a browser PKCE OAuth login or a device-code fallback, and exposes only secret-free connection status.
- Access-token freshness uses the JWT
exp value with a 60-second default margin.
- Refresh requests use OpenAI's public Codex CLI OAuth client id.
- Token updates use a temporary file,
rename, and mode 0600.
- A shared-file refresh race reloads the credential file and retries once.
- The route retries empty-body and transient provider errors twice by default; set
retryPolicy to change this.
- Model discovery fetches the backend's live model manifest, so a newly released OpenAI model reaches the picker without a plugin or pi-ai upgrade.
- A login attempt waits 10 minutes at most and shows its remaining time; Cancel this login ends it at once.
- The DSH Settings card receives connection state, OAuth actions, and model-discovery status only.
Install
Requirements:
- DeepSeek Harness
0.1.1-rc.2, 0.1.2-rc.1, or 0.1.5-rc.1 and newer 0.1.5-rc.x with a web profile.
- Node.js
>=22.19.0.
- A ChatGPT subscription that includes Codex access.
- Either DSH-managed credentials or a ChatGPT Codex CLI login.
The plugin does not work with an API-key-only Codex CLI login.
No OPENAI_API_KEY is required.
Replace web below if you use another DSH profile.
The package must be a dependency of that profile.
Then add the insert row to that profile's cordis.patch.yml.
npm registry
Use this route after the package is published to npm.
dsh plugin --profile web add dsh-llm-openai-codex
GitHub
Use this route after the public GitHub repository is pushed.
dsh plugin --profile web add github:auggie246/dsh-llm-openai-codex
Git-hosted packages run prepare during installation.
pnpm 10 can block that script.
If it does, pnpm prints the blocked package key.
For this package, the key is exactly dsh-llm-openai-codex.
Add this to ~/.dsh/profiles/web/pnpm-workspace.yaml.
Then run the same install command again.
allowBuilds:
dsh-llm-openai-codex: true
Use the key pnpm prints if a future pnpm version prints a different key.
Do not allow an unrecognized key.
Activate the plugin
Add this exact block to ~/.dsh/profiles/web/cordis.patch.yml.
- insert:
- id: llm-openai-codex
name: 'dsh-llm-openai-codex'
Restart dsh web, or restart your DSH entry point.
Then select an openai-codex/<model> model.
Configure the connection in Settings → Plugin Configuration → OpenAI Codex / ChatGPT subscription.
Uninstall
First remove the llm-openai-codex insert row from cordis.patch.yml.
Then remove the dependency from the same profile.
dsh plugin --profile web remove dsh-llm-openai-codex
Restart dsh web, or restart your DSH entry point.
Removing the plugin does not delete shared Codex CLI credentials.
Delete $DSH_HOME/credentials/openai-codex.json yourself only when you no longer need DSH-managed credentials.
Usage
The Settings card supports two credential sources.
- DSH-managed stores credentials at
$DSH_HOME/credentials/openai-codex.json.
- Shared Codex CLI reads
~/.codex/auth.json or $CODEX_HOME/auth.json.
DSH-managed credentials are the default for a new installation.
Use Connect ChatGPT in browser to create them.
DSH receives the OAuth callback at http://localhost:1455/auth/callback.
Use Use device code when the callback port is busy or the browser is remote.
For the shared Codex CLI source, sign in through the Codex CLI with ChatGPT.
The shared source is read-only for interactive DSH login.
The plugin never starts an OAuth login that can replace the Codex CLI file.
The plugin refreshes the shared token pair safely when necessary.
The plugin never deletes the shared Codex CLI credential file.
Every plugin configuration key is optional.
- insert:
- id: llm-openai-codex
name: 'dsh-llm-openai-codex'
config:
route: openai-codex
displayName: OpenAI Codex
storage: dsh
# authPath: ~/.codex/auth.json
refreshMarginMs: 60000
streamIdleTimeoutMs: 300000
reasoning: medium
modelDiscovery: auto # fetch the backend's live model manifest
modelRefreshMs: 21600000 # re-fetch every 6 hours; 0 disables the timer
modelCachePath: <DSH home>/cache/openai-codex-models.json
modelOverrides: {}
models: [gpt-5.4, gpt-5.4-mini]
retryPolicy: { mode: normal, maxRetries: 2 }
Model discovery
With modelDiscovery: auto (the default), the route fetches the same live
model manifest the Codex CLI and ChatGPT web use, authenticated with your
ChatGPT token. The manifest answers for your account, so a model OpenAI
releases reaches the DSH picker without upgrading this plugin, pi-ai, or DSH.
- A model the installed catalog knows keeps its catalog entry — costs,
context window, and thinking levels stay the hand-audited values.
- A model the catalog lacks is synthesized: name and context window from the
manifest, wire protocol and modalities from its closest catalog sibling,
reasoning levels from the manifest's own effort list.
- A model the backend hides for your account (
visibility: hide) leaves the
picker.
- The last manifest persists at
modelCachePath, so a restart serves the
discovered list before the first fetch completes. Every failure keeps the
previous list — the picker degrades to the installed catalog, never to
empty.
The manifest refreshes at startup, after each login or credential-source
switch, every modelRefreshMs, and whenever you press Refresh model list
on the Settings card. A changed model set re-announces the route, so open
model pickers re-read without a page reload.
models filters that merged list. A named id nothing serves yet is warned
about in the host log, and appears once the backend's manifest includes it —
discovery makes an id valid before the installed catalog knows it.
modelOverrides corrects one resolved model per key without a plugin
upgrade. Recognized fields: name, contextWindow, maxTokens, input,
compat, and reasoningEfforts — a dict whose keys are pi-ai thinking
levels (off, minimal, low, medium, high, xhigh, max) and whose
values are the wire spellings to send (false marks a level unsupported;
false instead of a dict declares a non-reasoning model). For example:
modelOverrides:
gpt-9000-imaginary:
contextWindow: 400000
reasoningEfforts: { low: low, medium: medium, high: high, xhigh: false }
authPath pins the credential file and disables the Settings source selector.
route changes the provider prefix shown in model pickers.
Changing route can conflict with another plugin that owns the same route.
Troubleshooting
| Symptom | Meaning | Fix |
|---|
pnpm blocks prepare | Git installation needs an approved build script | Add the exact pnpm key under allowBuilds, then retry |
Callback port 1455 is busy | Another OAuth flow owns the redirect port | Use Use device code |
Not connected | The selected source has no ChatGPT OAuth login | Connect in Settings or select the Codex CLI source |
| API-key login message | The Codex CLI file has an API-key login | Log in to Codex with ChatGPT or use DSH-managed credentials |
| Refresh token rejected | The token expired or another client rotated it | Reconnect in Settings |
| A newly released OpenAI model is missing | The picker shows the last manifest, not the newest | Press Refresh model list in Settings; check modelDiscovery is not off |
config.models names … warning | A filtered id is not in the catalog or the manifest yet | Keep the id and wait for discovery, or remove it |
| Stuck on "Waiting for approval" | The browser closed before approval; the attempt waits 10 minutes | Use Cancel this login on the card, or wait out the countdown, then start again |
Request failed on a Codex turn | The backend sent an empty error response | The route retries twice by default. If it repeats every turn, check the connection in Settings |
Security
The package contains no user credentials, API keys, or telemetry settings.
CODEX_CLIENT_ID is OpenAI's public Codex CLI OAuth client identifier.
It identifies the OAuth application and cannot authenticate a user.
The plugin contacts OpenAI only for login, token refresh, and model requests.
It does not send local credential paths or account identifiers to the Web card.
It writes DSH-managed credentials with mode 0600.
The Settings Remote never sends access or refresh tokens to the browser.
Maintainers
@auggie246
Contributing
PRs accepted.
Small note: If editing the README, please conform to the standard-readme specification.
npm install
npm run build
npm test
npm run smoke:live
npm run build verifies every runtime artifact named by main and exports.
The package ships prebuilt JavaScript files from lib/.
npm run smoke:live uses your subscription and can spend tokens.
License
MIT © Augustine Teo
