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
• Install
• Usage
• Troubleshooting
• Security
• Maintainers
• Contributing
• License

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 or 0.1.2-rc.1 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