Preface¶

DeepSeek Harness (dsh) is an agent framework open-sourced by DeepSeek AI, currently in the developer preview stage. Its core design principle is everything is a plugin: models, tools, skills, conversations, sandboxes, and UIs can all be replaced at the configuration layer without modifying the framework source code. The official repository is located at deepseek-ai/deepseek-harness. The fastest way to start it locally is:

npx @deepseek-ai/dsh web

Model providers are also implemented as plugins. Many users already have ChatGPT/Codex subscriptions but do not want to purchase an additional OpenAI Platform API Key or patch the Harness framework. The community plugin dsh-codex-connect addresses this exact use case: it uses ChatGPT OAuth login to integrate the openai-codex model catalog into Harness’s native model selector.

Two important notes first:
1. deepseek-harness-plugin.com is a community-driven directory and has no official affiliation with DeepSeek/Hugging Face. It should not be treated as an official app store.
2. This plugin itself clearly states that it has no affiliation with or endorsement from OpenAI, ChatGPT, Codex, DeepSeek, or DeepSeek Harness.

What is this¶

dsh-codex-connect is a “model and provider” plugin with the display name Codex Connect, maintained by franksong2702 (Frank Song). It uses the Apache-2.0 license and is primarily written in TypeScript. Its directory page introduction reads: Provides ChatGPT OAuth and Codex models for DeepSeek Harness.

The repository README clearly defines its boundaries:
- It registers the openai-codex model catalog and provides independent ChatGPT OAuth login.
- Model requests still go through Harness’s standard LLM service. Features including streaming output, tool calling, reasoning replay, compression, file system control, permission gates, and approval prompts continue to be handled by Harness.
- Your ChatGPT subscription will not be converted into an OpenAI Platform API credential.
- Installation is incremental: it will not replace the current default model or global search routing; the independent search provider and view_image are disabled by default.

This project is forked from Yan-Zero/dsh-codex, and the upstream copyright is retained in the NOTICE file. Both plugins use the same provider ID (openai-codex) and cannot be enabled simultaneously. The GitHub repository currently has 22 stars (the directory page snapshot still shows 7 stars; please refer to the repository page for the latest count). The npm package name is dsh-codex-connect, and the current pre-release version is 0.1.0-alpha.4.9.

Core Features¶

Add Codex Models to the Native Selector¶

After successful login, open Harness’s native model selector, and the available models will appear under the OpenAI Codex group. Identifiers like GPT-5.6 Luna are canonical names and will not be translated even if the interface language is switched to Chinese.

This step only affects the model selected for the current agent or conversation, which is separate from the default model saved in the profile and the global search routing. Installing this plugin does not mean all new future sessions will use Codex by default.

Complete Login in the Settings Page, Do Not Write Tokens to Configuration¶

Open Settings → Plugins → Plugin Configuration → Codex Connect. For new installations, the account area will display “Not logged in”. Click “Log in with ChatGPT” and complete the approval flow in your browser.

The README explicitly requires: Do not copy authorization URLs, authorization codes, tokens, or account identifiers into issues, logs, or configuration files. The OAuth state is stored separately in $DSH_HOME/.openai-codex-auth.json (default path ~/.dsh), and will not copy or modify ~/.codex/auth.json. On supported platforms, the parent directory and file use owner-only access permissions, writes are atomic replacements, and cross-process file locks are used during refresh.

When the card shows “Re-login” or the server requires re-authentication, follow the same browser flow. Do not run logout just to refresh a session; uninstalling the plugin will not delete these credentials either. Only log out when you truly want to clear the login state.

Search and Image Tools Disabled by Default¶

The post-installation configuration roughly looks like:

- id: llm-openai-codex
  config:
    enableSearch: false
    enableImageTool: false

You can modify these two options on the same Codex Connect card. Clicking “Save Changes” only affects this plugin’s capabilities and will not alter the default model or global search routing.
- enableSearch: true: Registers Codex as an optional search provider, but will not automatically set it as the global search.
- enableImageTool: true: Enables view_image for models with visual capabilities, used for post-approval local reading and public network image acquisition. Remote addresses only allow public HTTP(S); each DNS result and redirect will be rechecked, and connections will be pinned to verified addresses to avoid targeting localhost, private networks, link-local addresses, or cloud metadata services.

The default values for remaining fields specified in the repository documentation are as follows:

Diagnostic Commands Do Not Print Secrets¶

Checks that do not trigger OAuth or output credential content:

dsh plugin --profile web exec dsh-codex-connect status --json
dsh plugin --profile web exec dsh-codex-connect doctor --json

status --json only reports signed-in or signed-out. The exit code is 0 when logged in, and 1 when not logged in. The latter case means you should go through the login flow again, not that the plugin is corrupted. doctor --json outputs non-sensitive JSON: package version, Node.js information, authentication file status, capability switches, conflict prompts; it omits the absolute path of the authentication file, as well as OAuth, account, and expiration time details.

UI Additions in Alpha 4.9¶

The v0.1.0-alpha.4.9 release notes (2026-08-17) added two UI capabilities: per-session Codex Fast Mode (disabled by default, GPT-only), and a weekly quota bar displayed on the Composer per model. Quota, model visibility, and backend behavior are still controlled by OpenAI and may change at any time.

Installation and Enablement¶

First confirm that you have a working dsh installation on your local machine. If you are running from the DeepSeek Harness source code directory, replace dsh in the following commands with pnpm dsh. The examples below use the web profile; please replace it with the actual profile name you are using.

Installation Command Provided by the Community Directory¶

The original text on the community directory page is:

dsh plugin add github:franksong2702/dsh-codex-connect

The directory also reminds users: Plugins run with the permissions of the current dsh process, and may execute code during installation. You should inspect the source code repository and license before installing; for reproducible installations, pin the commit hash:

dsh plugin add github:franksong2702/dsh-codex-connect#commit

Replace #commit with the real commit hash, do not use this placeholder verbatim.

The Recommended Installation Method from the Current Repository¶

The README lists the npm pre-release channel as the main path for a five-minute quick start:

dsh plugin --profile web add dsh-codex-connect@alpha

To exactly replicate the version verified in this article:

dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.9

If the GitHub prerelease exists but the npm package is unavailable, use:

dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.9'

A local checkout can be installed as link:/absolute/path/to/dsh-codex-connect.

After installation, start the service:

dsh web

Confirm that exactly one llm-openai-codex entry loading this plugin exists in the configuration, and that the default model and search routing have not been altered:

dsh --profile web --dump-config

This output may include unrelated profile settings and should only be viewed locally.

Updates and uninstallation:

dsh plugin --profile web update dsh-codex-connect@alpha
dsh plugin --profile web remove dsh-codex-connect

Typical Usage¶

Log In and Select a Model Once¶

1. Open Settings → Plugins → Plugin Configuration → Codex Connect.
2. Click “Log in with ChatGPT” and complete the approval flow in your browser.
3. After the account area changes to “Logged in”, open the model selector and choose an openai-codex model.
4. Run the status --json command locally again to confirm you are signed-in.

For headless or remote hosts, INSTALL.md allows using login or login --device-code after the user explicitly requests login. OAuth approval must be completed by the user manually; do not use automated scripts to click through the flow.

Change Default Model and Search Routing Only When You Explicitly Request It¶

To set Codex as the default model for new agents, you need to add another Harness configuration entry; the plugin will not do this automatically:

- id: agent-default-model
  config:
    provider: openai-codex
    model: gpt-5.6-sol

Setting Codex as the global search requires a second explicit modification: first enable enableSearch, then change web.searchProvider.

- id: llm-openai-codex
  config:
    enableSearch: true
    searchMode: live
    searchContextSize: medium

- id: web
  config:
    searchProvider: openai-codex

Access the Web UI from Another Device¶

The default OAuth route only accepts loopback browser requests. When DSH is running on device A and you open the Web UI from another device on the local network, you need to add the full origin (including protocol and port) from the browser’s address bar to the trust list on the machine running DSH:

dsh plugin --profile web exec dsh-codex-connect trust-origin http://192.168.1.20:3080
dsh plugin --profile web exec dsh-codex-connect trusted-origins
dsh plugin --profile web exec dsh-codex-connect untrust-origin http://192.168.1.20:3080

Replace the example with the real origin from your address bar. Do not fill in the accessed device’s IP, bare hostname, path, query, or fragment. Only use this in networks you control, and do not expose this route to the public internet; use an SSH tunnel if explicit trust is not appropriate. The browser page will only display and copy this command, and will not modify the authorization list automatically.

Already Have dsh-codex Installed¶

There can only be one adapter for openai-codex. If you see a conflict on startup, check your active configuration, only remove confirmed old dsh-codex bundles or manual provider entries, do not delete the authentication file, and do not touch unrelated providers.

Refer to the repository’s MIGRATION.md for migration steps: first note your current default model, search routing, and llm-openai-codex configuration (do not read the OAuth file), uninstall dsh-codex, then install dsh-codex-connect, and confirm there is only one configuration entry loading this plugin left. Both enableSearch and enableImageTool default to false after migration; you can choose whether to enable them. You do not need to go through the OAuth flow again if status already shows you are logged in. Roll back by switching packages in reverse; do not delete or copy the standalone authentication file during the process.

Applicable Scenarios and Notes¶

These are the ideal use cases:
- You are already using the DeepSeek Harness Web UI and want to use your existing ChatGPT subscription to call Codex models.
- You do not want to “exchange” your subscription for a Platform API Key or modify DSH source code.
- You want to retain control over the default model and search routing, and only want the plugin to register the provider.
- You need local diagnostics, conflict checks, and migration from the old dsh-codex.

Important notes before use:
1. Permissions and Source. Plugins run with the permissions of the current dsh process, and may execute code during installation. Read the repository source code and Apache-2.0 license before installing, and only install sources you trust. The community directory is not an official app store.
2. Still in Alpha. The only combination currently listed in compatibility.json is: DSH Plugin API package 0.1.0-rc.6, @earendil-works/pi-ai 0.82.1, Node.js ^22.19.0 || >=24.0.0. Upgrade the DSH Plugin API package and pi-ai as a group, then run doctor --json. This compatibility guarantee does not apply to future versions. Harness itself is also in developer preview, and the official README notes that breaking changes will occur in the future.
3. Capability Boundaries Are Determined by OpenAI. Plan eligibility, model permissions, quotas, and backend behavior may change. The Codex endpoint does not enforce max_output_tokens for regular Responses; Harness compression is still available, but this upper limit cannot be enforced by the server on this route.
4. Agent Capabilities Still Come from the Current Profile. Shell access, file system, skills, MCP, subagents, approval, permissions, attachments, conversation persistence, compression, and recovery are all provided by the current profile, not this plugin.
5. Do Not Mix Multiple Codex Plugins. Old bundles, manual provider entries, or other packages that also register openai-codex will cause conflicts.
6. Installation, Build, Test, and Doctor Do Not Require Real OAuth. Only log in via the settings page when you are ready to actually call models.

Closing¶

dsh-codex-connect connects ChatGPT OAuth and Codex models to DeepSeek Harness’s standard LLM path, while leaving the default model, search routing, and optional capabilities to the user’s discretion. It solves the problem of “you already have a subscription but lack an uninstallable provider in Harness”, rather than turning ChatGPT into a universal OpenAI API.

Directory page: https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-codex-connect/

GitHub: https://github.com/franksong2702/dsh-codex-connect