dsh-codex

一句话定位

给 DeepSeek Harness 接入 ChatGPT 订阅背后的 OpenAI Codex 后端：通过 OAuth 完成 ChatGPT 登录，免 API Key 即可在 DSH 模型选择器里使用 Codex 模型，并由 DSH 提供流式响应、工具调用、联网搜索、图片理解与生图。

核心能力

• 完整 ChatGPT OAuth 登录与自动 token 刷新，支持浏览器设置面板与独立 CLI 两种方式
• 把 Codex 模型目录（含视觉模型时声明图片输入能力）注入 DSH 模型选择器，账号中可见的模型自动出现
• 把 dsh 原生 web_search 工具接到 Codex 独立搜索协议，搜索结果以普通文本和 HTTP(S) 引用返回，可被后续轮次与压缩复用
• 扩展 Harness 现有 read_image 工具，新增 HTTP(S) URL 输入，并对重定向次数、字节数、内嵌凭据、私网目标做安全校验
• 提供 imagegen 工具调用 gpt-image-2 生图，支持工作区参考图与会话内最近图片，自动保存为 dsh 附件与本地文件
• 提供会话级 Fast Mode 开关与每周额度指示器，登录账号后实时显示剩余百分比与重置时间

技术实现

• 语言: TypeScript（Host 端 ESM + Schemastery 配置；Client 端 React 18 + TSX）
• 关键依赖: @earendil-works/pi-ai（Codex provider 与 OAuth）、@deepseek-ai/dsh-llm-pi-ai（适配器基类）、@deepseek-ai/dsh-settings（持久化偏好）、@deepseek-ai/dsh-host-webserver（Web 路由）
• 架构模式: Cordis bundle 双端插件。Host 端以 llm-openai-codex 名字注册 LLM 适配器与独立搜索 Provider，并向 openAICodex 注入 service；通过 cordis.patch.yml 注入默认模型与搜索 Provider；Client 端 bundle 通过 dsh.client.inject 注册 React 组件到 dsh-web 设置面板与对话输入栏
• 入口文件: src/index.ts（Host 主入口）、src/client/index.tsx（Web 设置面板入口）、src/bin.ts（独立 CLI dsh-openai-codex）、src/tui.ts（/codex 命令子节点）

适用场景

持有 ChatGPT Plus/Pro 订阅、想把 Codex 系列模型（gpt-5.6-sol 等）直接装进 DSH 模型选择器、又不想掏 OpenAI Platform API Key 的用户。痛点是 DSH 自带 openai-codex 路由只认通用凭据、没有登录入口；本插件把 OAuth、自动刷新、Codex 视觉能力、独立搜索、gpt-image-2 生图一并补齐，浏览器设置面板和 CLI 都能用。同样适合在远端机器跑 DSH、需要为前端 Web origin 单独授权的场景。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:Yan-Zero/dsh-codex

安装完成后在「设置 → OpenAI Codex」点击「使用 ChatGPT 登录」完成 OAuth。Web 配置和 TUI（dsh-tui profile）共享同一份凭证文件；TUI 内可用 /codex status|login|logout|usage|config 和 /codex set <开关> <on|off> 操作。

配置项

bundle 默认会把 openai-codex / gpt-5.6-sol 设为新建 agent 的默认模型，并把 Codex 设为默认搜索 Provider；DSH 设置中已保存的模型仍然优先。所有 Schema 字段作用于 llm-openai-codex 入口。

常见问题

Q: 需要 OpenAI API Key 吗？

A: 不需要。本插件消费 ChatGPT Plus/Pro 订阅的额度，与官方 Codex CLI 走同一通道，登录走 OAuth，不接入按量计费的 OpenAI Platform API。

Q: 已经装了 Codex CLI，能复用登录态吗？

A: 不能互相复用。本插件独立存储凭证于 $DSH_HOME/.openai-codex-auth.json，绝不读取或修改 ~/.codex/auth.json，两套存储互不干扰，避免双方争抢 refresh token。

Q: 怎样在 Web 之外登录或检查状态？

A: 用插件自带的 CLI：dsh plugin --profile web exec dsh-openai-codex login（加 --device-code 走设备码），status 看登录态、logout 清凭证、doctor --json 输出脱敏诊断。

Q: 模型选择器能精简显示哪些 Codex 模型吗？

A: 可以。在「设置 → OpenAI Codex」用模型复选框选择需要展示的项，修改即时持久化并刷新 Web/TUI 的模型目录；或在 profile patch 给 llm-openai-codex 传 models 列表做初始子集。隐藏模型已保存在会话或被显式指定时仍可解析。

Q: 图片输入支持哪些来源？

A: 本地路径走 Harness 现有文件系统；HTTP(S) URL 由本插件扩展 read_image 后支持，自动拒绝内嵌凭据、本地/私网/特殊网络目标，并对每次跳转固定到已验证公网地址。Web 输入框可粘贴或拖拽图片，PNG/JPEG/WebP/GIF 均在 dsh 附件限制内可用；只有声明支持视觉的模型才会接收图片。

Q: 凭证存在哪里？浏览器能看到吗？

A: 写入 $DSH_HOME/.openai-codex-auth.json（默认 ~/.dsh），POSIX 系统强制 0o600、跨 dsh 进程加锁刷新；浏览器只能拿到脱敏账号、登录状态、过期时间和额度条，原始 token 不会下发。

Q: 卸载会删掉登录凭证吗？

A: 不会。卸载 bundle 仅移除 DSH 端集成，需在账号页面或运行 dsh-openai-codex logout 才会删除本地凭据文件。

上手难度

入门 — 仅需在设置面板点击一次「使用 ChatGPT 登录」并完成浏览器授权；进阶用户可通过 profile patch 调整模型/搜索配置或在 TUI 用 /codex set 切换实验功能，不需要修改代码。

已知问题与限制

• 搜索端点是 Codex 独立协议而非公开 OpenAI Platform API，兼容性取决于固定版本的 Codex / pi-ai 实现（README.md:141）
• Codex 端点不执行普通 Responses 的 max_output_tokens，压缩可工作但配置的摘要上限无法在服务端落实（README.md:139 / src/responses.ts:330-360）
• ChatGPT 套餐资格、模型权限、配额与后端行为由 OpenAI 控制，可能随时变化（README.md:138）
• 文件系统、shell、skills、MCP、subagents、权限、附件、压缩与 web_search 工具本体仍来自当前 DSH profile，本插件不接管这些面（README.md:140）
• WebSocket 上下文复用与原生 Responses 压缩两个开关默认关闭，开启后任一连接中断、Fork、压缩或进程重启都会自动回退到发送完整上下文（README.md:118-119）
• 远程 Web origin 需在 DSH 主机执行 trust-origin <origin> 才能完成 OAuth 回调；allowlist 按完整 origin 精确匹配（src/auth-routes.ts:43-53 / README.md:33）
• 远端主机环境下浏览器状态接口返回 remote-web-origin-not-trusted 状态，账号页面会显示需要复制执行的具体授权命令（README.md:33 / src/auth-routes.ts:53）

English | 中文

Use a ChatGPT subscription in DeepSeek Harness through OpenAI's Codex sign-in flow—no OpenAI Platform API key required and no dsh source patch required.

dsh-codex is an independent dsh bundle. It adds:

• ChatGPT OAuth from the dsh Settings panel or a standalone CLI, with automatic token refresh
• the Codex GPT catalog, including vision-capable models when the account offers them
• streaming, tool calls, reasoning replay, prompt caching, and dsh compaction through the normal LLM service
• Codex standalone web search through dsh's existing web_search tool
• optional HTTP(S) URL input added to Harness's existing read_image tool
• an imagegen tool backed by gpt-image-2, with workspace or conversation reference images and automatic workspace output
• browser image input through dsh's existing paste and drop controls
• a per-conversation Fast Mode switch and compact weekly quota indicator in the Web composer

ChatGPT subscription authentication and usage-based OpenAI API access are different products. This plugin uses the ChatGPT Codex backend only; it does not turn a subscription into a general-purpose OpenAI API credential.

Install

Install the prebuilt bundle from npm into the selected dsh profile:

dsh plugin --profile web add dsh-codex
dsh web

From a DeepSeek Harness source checkout, use pnpm dsh plugin --profile web add dsh-codex. A local plugin checkout can still be installed with link:/absolute/path/to/dsh-codex for development.

Open Settings → OpenAI Codex → Sign in with ChatGPT. The plugin opens OpenAI's authorization page and completes the localhost callback. The account page shows live Codex quota bars and exact remaining percentages; exact credit balances or workspace limits appear only when the account API supplies them.

Loopback Web pages are trusted automatically. If dsh runs on another machine, the account page shows the exact origin command that must be approved on the dsh host, for example dsh plugin --profile web exec dsh-openai-codex trust-origin http://host:port. The allowlist is exact-origin, stored separately from OAuth credentials, and can be inspected or revoked with trusted-origins and untrust-origin.

The CLI remains available for terminal and headless installations:

dsh plugin --profile web exec dsh-openai-codex login
dsh plugin --profile web exec dsh-openai-codex login --device-code
dsh plugin --profile web exec dsh-openai-codex status
dsh plugin --profile web exec dsh-openai-codex doctor --json
dsh plugin --profile web exec dsh-openai-codex logout

For dsh-tui, install the bundle into the same profile:

dsh plugin --profile dsh-tui add dsh-codex

After restarting the TUI, /model lists the openai-codex catalog. With no explicit route or saved selection, the TUI adopts the bundle's gpt-5.6-sol default. Use /codex status|login|logout|usage|config for the account and live settings; the four boolean settings can be changed with /codex set <read-image|imagegen-other-models|websocket-context|native-compaction> <on|off>. Browser login shares the same dsh credential file used by the Web profile.

Codex, Claude Code, and other automation agents should follow INSTALL.md. It is a complete, idempotent runbook and does not require reading this repository's source or design notes.

The bundle selects openai-codex / gpt-5.6-sol for new agents and selects the Codex search provider. A model already saved in dsh settings still takes precedence; the model picker can select any other Codex model visible to the signed-in account.

Model catalog

By default, the model picker advertises the complete openai-codex catalog. Open Settings → OpenAI Codex and use the model checkboxes to choose which entries remain visible. The selection is live and durable; dsh refreshes the Web and TUI model directories after it changes.

The same initial subset can be seeded through models on the llm-openai-codex entry while preserving provider order:

- id: llm-openai-codex
  config:
    models:
      - gpt-5.6-luna
      - gpt-5.6-sol
      - gpt-5.6-terra

The checkboxes and models setting control discovery only. A hidden model already stored in an existing session or supplied explicitly remains resolvable, so narrowing the picker does not invalidate older records. Omit models to start with the full catalog; an empty list advertises no models.

Images

Image support uses dsh's durable attachment path:

• paste an image into the Web composer with Ctrl+V, or drag and drop it;
• on Windows, paste a clipboard image with Ctrl+V in the adapted dsh-tui, or enter @relative/image.png; clipboard images go straight to the attachment store, while path images use the active workspace filesystem;
• ask the model to call read_image with either file_path for a workspace image or url for an HTTP(S) image;
• PNG, JPEG, WebP, and GIF are accepted within the active dsh attachment limits;
• only a model that explicitly advertises image input may receive an image.

imagegen is available to any vision-capable conversation model. The current model writes an ordinary prompt and may select either referenced_image_paths or num_last_images_to_include; the plugin reads the bytes from ctx.fs or the attachment store and sends them to gpt-image-2. The model never emits base64. Every result is shown inline, saved as a durable attachment, and written to the active workspace. output_path chooses the destination; omitting it creates a unique generated-<timestamp>-<id>.png file. Local saving is included in this plugin, while dsh-remote-ssh supplies the remote AHP write path when that plugin owns the workspace.

The Settings page has separate Enhance read_image and Image generation for other models toggles. Both default on. Turning off the first removes the plugin's agent-scoped override and restores Harness's original local-only read_image schema. Turning off the second keeps imagegen available to Codex vision models and rejects calls from other model providers at execution time.

read_image stores validated bytes as a dsh attachment before returning the actual image block. Local paths are delegated unchanged to Harness, including its configured filesystem and sandbox behavior. The URL extension bounds redirects and bytes, rejects credentials embedded in URLs, rejects local/private/special network targets, and pins each validated public address across the corresponding HTTP hop.

For an eligible Codex GPT conversation, the Web composer also exposes a session-local Fast Mode switch. Enabling it adds the provider's priority service tier only to that conversation; it does not change saved model settings. A neighboring quota bar shows the applicable weekly limit and provider-declared reset time.

Search

The provider connects dsh's web_search tool to the standalone search protocol used by Codex. It returns ordinary dsh text and HTTP(S) citations, so later turns and compaction retain the tool history.

Configure the llm-openai-codex row in a profile patch:

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

Each resolved, secret-free auxiliary request is recorded before dispatch as the dedicated web/openai-codex-search-llm-request session event. The event is owned and registered by this plugin; no generic search event or dsh fork is required.

Responses API experiments

The Settings page provides two Codex-only switches. Both are off by default:

• WebSocket context reuse keeps store: false and selects pi-ai's Codex WebSocket continuation transport. While the same session keeps a reusable connection and the next request is an exact extension, it sends previous_response_id with only the new input. History edits, compaction, Fork, connection loss, and process restarts fall back to a full request. With the switch off, ordinary turns use SSE and always send the full Harness context.
• Native Responses compaction follows Codex's current V2 flow: it sends the existing history plus a compaction_trigger item through codex/responses, retains recent client messages with the returned encrypted compaction item inside the Harness checkpoint, and restores those native items on later requests. Existing checkpoints remain readable after the switch is disabled. If V2 compaction is unavailable or fails, the same call falls back to the existing Harness model summary.

The switches are independent. Every ordinary Codex request keeps store: false; the default uses SSE with the text-summary path from dsh-compaction-basic.

Credentials and privacy

dsh keeps this login separate from Codex CLI/Desktop:

• credentials are stored at $DSH_HOME/.openai-codex-auth.json (~/.dsh by default);
• writes are atomic and token refresh is locked across local dsh processes;
• browser status and diagnostics never return token values;
• ~/.codex/auth.json is never copied or modified.

Keeping the stores separate prevents two clients from racing the same rotating refresh token. Removing the bundle does not delete the credential; use the account page or logout command when the local account should be removed.

Compatibility notes

• This branch targets the DSH 0.1.0-rc.7 plugin surfaces and @earendil-works/pi-ai 0.82.1. The adapter migrates the earlier pi-ai replay envelope while reading history so existing reasoning/tool metadata remains usable after the rc.7 upgrade.
• The plugin runs on released dsh plugin surfaces and does not require a modified Harness checkout. It can generate attachments and save local output when installed alone.
• 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. Compaction works, but its configured summary cap cannot be imposed server-side on this route.
• Filesystem, shell, skills, MCP, subagents, permissions, attachments, compaction, and the web_search tool itself still come from the active dsh profile.
• The standalone search endpoint is not a public OpenAI Platform API. Compatibility follows the pinned Codex/pi-ai implementation.

See the design document for protocol, persistence, and lifecycle details.

Development

pnpm install
pnpm run check

The check performs strict Host and browser TypeScript checking, focused tests, and both runtime bundles.

License

Apache-2.0