dsh-codex-connect

一句话定位

让用户在 DeepSeek Harness 中用 ChatGPT 订阅登录，把 OpenAI Codex 模型（含独立搜索、读图、生图）作为一种 LLM 选项使用，不替换默认模型与全局搜索路由。

核心能力

• 在 Settings → Plugins → Plugin configuration → Codex Connect 卡片中用 ChatGPT OAuth 账户登录，凭据单独存到 $DSH_HOME/.openai-codex-auth.json，与 Codex CLI/Desktop 不互通
• 在模型选择器中以 OpenAI Codex 分类使用 Codex 模型，保留 Harness 原生的流式输出、工具调用、推理回放、会话压缩与权限审批
• 启用可选的独立网络搜索，将 Codex 注册为搜索提供者，但不会自动接管 profile 的全局搜索路由
• 启用可选的 view_image 工具，让支持视觉的 Codex 模型读取本地文件与公网图片（DNS 解析与跳转目标全程校验并锁定为公网地址）
• 启用可选的 codex_connect_image_generate 工具，调用 GPT Image 生成的图片直接保存为 DSH 附件并在会话内显示
• 提供 dsh-codex-connect 独立 CLI，用于登录/登出、状态、doctor、历史迁移、按需放行远端浏览器 origin

技术实现

• 语言: TypeScript (ESM，使用 tsdown 打包)
• 关键依赖: @deepseek-ai/cordis（插件注册与 fiber 注入）、@earendil-works/pi-ai@0.82.1（OpenAI Codex provider 与 OAuth 流）、@deepseek-ai/dsh-llm-pi-ai（复用通用 Adapter）、@deepseek-ai/dsh-settings（settings-section 编辑）
• 架构模式: 通过 cordis.patch.yml 注入 llm-openai-codex 行（3 个 capability 全部为 false）；Host 端 apply() 一次性注册 OAuth store、Transport、Adapter、可配置 Provider；capability 在 installSettingsSection 的 onChange 中通过 ctx.effect + reconcileXxx() 动态挂载/卸载 search / view_image / image_generate 三组功能 fiber；Browser 端通过 slots 在 settings.plugin.item 注入卡片，在 conversation.input.right 注入 Fast Mode 开关与配额指示器
• 入口文件: src/index.ts（Host 插件主体，name = "llm-openai-codex"，inject = ["llm"]）、src/client/index.tsx（Browser 端，name = "dsh-codex-connect-client"）、src/bin.ts（独立 CLI：doctor | login | logout | status | migrate-history | trust-origin 等）

适用场景

已经在为 ChatGPT Plus/Pro 付费、希望把 Codex 当作 DSH 中一种可选 LLM 的用户；既想用 Codex 模型，又不愿放弃 Harness 的会话持久化、压缩、子代理、工具审批、附件、MCP、技能等机制的人。当前的 Codex Connect 也承担从旧的 dsh-codex 平滑迁移、并保留搜索/读图/生图三组可选能力的角色。

前置依赖与兼容性

安装方式

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

配置项

常见问题

Q: 安装 Codex Connect 之后，原来配置的默认模型和搜索会被改掉吗？

A: 不会。cordis.patch.yml 只插入一行 llm-openai-codex，且 3 个 capability 默认都是 false，profile 的 agent-default-model 与 web.searchProvider 必须由你显式写入才会生效。

Q: OAuth 凭据放哪里？跟 Codex CLI/Desktop 是同一份吗？

A: 凭据存放在 $DSH_HOME/.openai-codex-auth.json（默认 ~/.dsh）。这是独立文件，不会读取或修改 ~/.codex/auth.json；想换台机器迁移账号，就在目标机器重新走一遍 ChatGPT 授权。

Q: 必须有 OpenAI Platform 的 API Key 才能用吗？

A: 不需要。Codex Connect 只用 ChatGPT 订阅的 OAuth bearer token，私有 OpenAI Platform 凭据既不读取也不代理——价格、限速、配额都以 ChatGPT 订阅为准。

Q: 哪些信息是不该贴到 issue、日志或配置文件里的？

A: 任何 OAuth 授权 URL、device code、refresh/access token、account id 都不要贴；遇到问题时贴 dsh-codex-connect doctor --json 的脱敏输出就够了。

Q: 升级 DSH 到 0.1.0-rc.7 之后，从前用 Alpha 4.10 跑出来的 Codex 搜索历史读不出来了，怎么办？

A: 先 dsh plugin --profile web exec dsh-codex-connect migrate-history --json 扫一遍；看到命中事件后停掉所有会写该 session 根目录的 DSH 进程，再带 --apply --confirm-stopped --json 真正修复；修复前会先在同目录生成 .pre-codex-search-history-migration 备份。

Q: doctor / status 命令会不会输出密钥？

A: 不会。doctor 只读取 lstat 元数据并输出 schema v1 的脱敏 JSON（包含密码文件状态、能力开关、兼容性状态、provider 冲突、提示语），不打印绝对路径或 OAuth 字段；status --json 只回报 signed-in / signed-out。

Q: 我同时还装着老的 dsh-codex 包，会发生什么？

A: 启动会因 provider id 冲突被拒（Harness 不允许两个 adapter 注册 openai-codex），并提示先卸载冲突方或删除 profile 中多余的 llm-openai-codex 行，再装 Codex Connect。

上手难度

入门 — 安装后只需进入设置卡片点一次 Sign in with ChatGPT，再到模型选择器挑一个 openai-codex 模型即可使用；capability 默认关闭，几乎不会改变现有配置。

已知问题与限制

• Codex 端点不强制 Responses 接口的 max_output_tokens，因此 Harness 压缩总结的服务端 token 上限无法在该路由施加（README.md:186）
• POSIX 平台对 OAuth 文件做严格的 owner-only 校验，模式位放宽到组/其他可读会被拒绝启动，需 chmod 600 后再试（src/store.ts:32-50）
• 历史修复命令在 Windows 上仅支持 dry-run，--apply 模式会被代码层主动拒绝（src/history-migration.ts:295-297）
• view_image 远程 URL 强制走公网校验：每个跳转目标都要重新解析并把 socket 钉到验证后的地址，否则被拒；本地回环、私网、链路本地、云元数据端点全部不可达（src/public-http.ts:59-103 / src/public-http.ts:167-173）
• 卸载本包不会自动删除 OAuth 凭据，必须显式 dsh-codex-connect logout，否则 $DSH_HOME/.openai-codex-auth.json 会保留（README.md:179）
• 独立搜索工具启用后不会在 Session 内写入 plugin 私有 required 事件，因此不能跨独立的 @deepseek-ai/dsh-session 实例保留遥测；但 Harness 自身的 web Tool 记录照常落入历史（docs/design.md:19）

English | 中文

Connect your ChatGPT subscription to DeepSeek Harness with OAuth, optional GPT Image generation, user-controlled defaults, Harness-native approvals, diagnostics, and reliable session recovery.

dsh-codex-connect adds the openai-codex model catalog and a separate ChatGPT OAuth login. Models run through Harness's normal LLM service, so streaming, tool calls, reasoning replay, compaction, filesystem controls, permission gates, and approval prompts remain Harness-owned. It does not turn a ChatGPT subscription into an OpenAI Platform API credential. When an eligible GPT Codex model is selected, the Composer also shows a conversation-scoped Fast Mode toggle and a compact weekly-quota indicator.

Installation is additive. The bundle does not replace the current default model or search route. Standalone search, view_image, and image generation remain disabled until explicitly enabled.

The setup and image-result screenshots in this English guide are captured from the English-localized Harness UI. The shared Composer crop is a language-neutral feature strip; the Chinese guide uses the same strip and Chinese captures for the other screens. Model and provider identifiers keep their canonical spelling in both languages.

Quick start (about five minutes)

This guide uses the web profile. Replace web with the name of the Harness profile you already use. You need a working dsh installation; from a DeepSeek Harness source checkout, prefix the commands with pnpm.

1. Install the plugin into one profile

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

Expected result: the package is added to that profile. This does not change the profile's default model or global search route.

To reproduce this release exactly, use dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.14. If npm is unavailable after the matching GitHub prerelease exists, use dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.14'. A local checkout can be installed as link:/absolute/path/to/dsh-codex-connect.

2. Start Harness

dsh web

Expected result: the Harness web UI opens for the selected profile.

3. Find the Codex Connect card

Open Settings → Plugins → Plugin configuration → Codex Connect.

Expected result: a fresh installation shows Not signed in and a Sign in with ChatGPT button. The card is where you later manage optional capabilities too.

4. Sign in with ChatGPT

Click Sign in with ChatGPT and complete the browser approval yourself. If an embedded WebView blocks the sign-in window, use the displayed Open ChatGPT sign-in page link to continue in your system browser. Do not copy an authorization URL, code, token, or account identifier into an issue, log, or configuration file.

Expected result: the account area changes to Signed in. The screenshot below is the successful end state after this step; it is not the initial sign-in screen.

5. Choose a model and make one safe check

Open Harness's normal model picker and select an openai-codex model for the agent or session you are using. This selection is separate from writing the profile's default model or global search route.

The picker groups the available entries under OpenAI Codex. Model identifiers such as GPT-5.6 Luna are canonical names, so they intentionally remain un-translated.

To confirm the configured plugin row locally, run:

dsh --profile web --dump-config

Expected result: the configuration has exactly one llm-openai-codex row. Keep this configuration dump local; it may include unrelated profile settings.

For secret-free status and diagnostics that do not start OAuth, run:

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

Expected result: status --json reports signed-in and exits 0, while doctor --json prints one secret-free JSON document. A signed-out status --json exits 1; return to step 4 instead of treating that as a plugin failure.

Composer controls for GPT Codex conversations

The two small controls are shown only when the current conversation is using a GPT model from the openai-codex provider. They are session controls, not profile-wide settings:

• Fast Mode (lightning icon) is off by default for each conversation. Click it to request the faster 1.5× mode; click it again to return to Standard speed. The control is bound to that conversation and does not change the selected model or other conversations. Hover or focus the icon to see the current state and its quota-consumption warning.
• Weekly quota bar is the short horizontal bar beside the model selector. Its color moves from green through yellow/orange to red as the remaining amount falls. Hover or focus it to see the exact remaining percentage and the server-provided reset time. It is hidden for non-GPT models or when usage data is unavailable.
• For the exact gpt-5.3-codex-spark model, the Composer reads the Spark weekly bucket. Other GPT Codex models read the standard Codex weekly bucket; these are separate limits.

Optional capabilities (off by default)

The installed bundle is intentionally inert beyond model-provider registration:

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

Open Settings → Plugins → Plugin configuration → Codex Connect to manage the account and these options in one card. Save changes affects only this plugin's capability section and applies live. It never selects a default model or a global search route.

Enable only the capability you intend to use

• enableSearch: true registers Codex as an available search provider. It does not select the profile's global search route.
• enableImageTool: true enables view_image for approved local reads and public-network image fetches on vision-capable models.
• enableImageGeneration: true enables the prompt-only image generation tool. Use the image generation capability included with your current GPT subscription. Generated images are saved as DSH attachments and shown in the conversation with the native image gallery.

The screenshot below is an example after someone has explicitly enabled capabilities. It does not show the fresh-install default. This English guide uses the English-localized capture; the Chinese guide shows the matching Chinese-localized state.

Generate images with GPT Image

1. Turn on Enable GPT Image generation in the Codex Connect card and select Save changes.
2. Choose an openai-codex GPT model for the conversation.
3. Describe the image you want in ordinary language. The agent can expand that request into the prompt sent to GPT Image.
4. The completed image is stored as a DSH attachment and rendered directly in the conversation. The result card lets you review and copy the full prompt, download the image, and inspect image details.

This capability uses the image generation access included with your current GPT subscription; it does not require an OpenAI Platform API key. Availability remains subject to the GPT plan and model selected for the conversation.

The detailed image prompt is authored by the selected GPT model. Codex Connect does not silently add image parameters: it validates the prompt-only request, forwards it through the ChatGPT subscription capability, and stores the returned image as a DSH attachment. On the result card you can scroll through and copy the complete prompt. Try again and Generate another send that card's own prompt again, so an older card is not accidentally regenerated from a newer conversation message. Modify this image first asks what you want to change, then continues from that card's prompt.

Usage limits in Plugin configuration

After sign-in, the Codex Connect settings card can show several server-reported windows. They are separate buckets, not three views of one number:

• Codex · Weekly is the standard Codex weekly bucket used by ordinary GPT Codex models.
• GPT-5.3-Codex-Spark · 5-hour and GPT-5.3-Codex-Spark · Weekly are the two Spark windows returned for the Spark model.

Each bar shows the remaining percentage and its local reset time. OpenAI controls the returned windows, eligibility, and reset values; missing usage data is treated as unavailable rather than guessed.

Change a default model or global search route separately

To make a Codex model the default for new agents, add or update the separate Harness row yourself:

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

Selecting Codex as the profile's global search route is another explicit change:

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

- id: web
  config:
    searchProvider: openai-codex

Reauthentication, diagnostics, and conflicts

• If the card says Sign in again or the server asks for reauthentication, click that action and complete the same safe browser flow. It preserves this plugin's capability settings and does not silently change your default model or global search route. Do not run logout just to renew a session.

• doctor reads process and filesystem metadata only. doctor --json emits exactly one secret-free JSON document with schema version 1, package/version/Node metadata, credential-file state and safe mode, capabilities, conflict status, and hints. It omits the absolute credential path and OAuth, account, and expiry data.

• status --json emits only signed-in or signed-out state with package metadata. status --json reads the credential only to determine sign-in state, but never prints credential contents or starts OAuth.

• Alpha 4.10 users whose search histories fail with an unknown web/openai-codex-search-llm-request event can run dsh-codex-connect migrate-history --json, stop DSH, then apply the reported repair with migrate-history --apply --confirm-stopped --json. The command is dry-run by default, backs up every changed compressed JSONL artifact, and is dry-run only on Windows; see MIGRATION.md.

• OAuth is stored separately at $DSH_HOME/.openai-codex-auth.json (~/.dsh by default). ~/.codex/auth.json is never copied or modified. The parent directory and file use owner-only permissions where supported, writes are atomic, and refresh writes use a cross-process file lock.

• By default, the OAuth routes accept loopback browser requests only. When DSH runs on one device and you open it from another device on a trusted network, approve the browser address-bar origin explicitly on the device that runs 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 exact origin from the browser address bar, including scheme and port; do not enter the accessing device's IP, a bare host, a path, a query, or a fragment. Trust only a network you control, never expose this route to the public Internet, and use an SSH tunnel as the fallback when explicit network trust is not appropriate. The browser page only displays and copies this command; it never changes the allowlist itself.

• If startup reports an openai-codex collision, an old dsh-codex bundle or manual provider row may already own the adapter. Inspect the effective configuration and remove only the confirmed conflicting owner. Do not delete auth files or unrelated providers.

• Removing the package does not delete OAuth state. Run logout only when credential removal is intended.

Compatibility and security boundary

• The only verified compatibility combination is DSH plugin API packages 0.1.0-rc.7, @earendil-works/pi-ai 0.82.1, and Node.js ^22.19.0 || >=24.0.0; see compatibility.json. Alpha 4.10 uses the rc.7 keyed Plugin configuration slot; DSH rc.6 users should remain on Alpha 4.9.
• Upgrade the DSH plugin API packages and @earendil-works/pi-ai as one group, then run dsh-codex-connect doctor --json and the compatibility check again. This contract does not make claims about future versions.
• ChatGPT plan eligibility, model access, quotas, and backend behavior are controlled by OpenAI and may change.
• The Codex endpoint does not enforce the ordinary Responses max_output_tokens field. Harness compaction still works, but that summary cap cannot be imposed server-side on this route.
• Shell, filesystem, skills, MCP, subagents, approvals, permissions, attachments, session persistence, compaction, and recovery continue to come from the active Harness profile.
• Remote view_image URLs are limited to public HTTP(S) destinations. Every DNS result and redirect is checked, and the connection is pinned to the validated address so localhost, private networks, link-local services, and cloud metadata endpoints remain unreachable.
• No real OAuth operation is required for installation, build, tests, doctor, or package validation.

See INSTALL.md for the idempotent agent runbook, RELEASING.md for the Alpha release checklist, MIGRATION.md for migration from dsh-codex, and docs/design.md for architecture details.

Development

pnpm install --frozen-lockfile
pnpm run check

Releases

Maintainers publish alpha versions through the manual OIDC release workflow; see the alpha release runbook for the separate, short-lived latest promotion step.

Legal / Acknowledgements

Copyright 2026 Frank Song for the modifications and additional work in Codex Connect. This project includes software derived from Yan-Zero/dsh-codex; Copyright 2026 Yan-Zero is retained for the upstream material. Both are distributed under Apache-2.0, with details in NOTICE. This project is not affiliated with or endorsed by OpenAI, ChatGPT, Codex, DeepSeek, or DeepSeek Harness.

License

Apache-2.0