Codex Connect 的可选图片能力：让模型调用 GPT Image 生成图片，并提供 view_image 工具读取本地与公网图片。
- 语言
- TypeScript
- License
- Apache-2.0
- 分支
- main
安装
$ dsh plugin --profile web add github:franksong2702/dsh-codex-connect/packages/images在终端中运行以上命令，通过 dsh CLI 安装此插件。可在右上角切换 Profile。 第一次用 dsh？看这篇新手教程
一句话定位
Codex Connect 在原有的 ChatGPT OAuth 与 Codex 模型之外，额外提供两项可选图片能力：让对话模型用自然语言 prompt 调用 GPT Image 生成图片，并提供 view_image 工具读取本地或公网图片。
核心能力
- 按 prompt 生成图片：把文字描述直接发送给 Codex 图片端点，生成结果以 DSH 附件形式落库并在对话里直接预览
- 读取本地图片文件：
view_image通过 Harness 文件系统读取绝对或相对路径图片，并把像素与媒体类型送给视觉模型 - 读取公网图片 URL：远程
view_image仅允许公开 HTTP(S) 目标，并校验 DNS、阻止私网与云元数据 - 与 Codex OAuth 共享同一套登录：图片生成直接复用插件已有的 ChatGPT 凭据，不引入第二套认证
- 关闭能力后历史图片仍可回放：浏览器侧的图片结果视图与开关解耦，旧会话里的生成结果照常显示
- 出现 OAuth 失效、配额耗尽、网络中断等失败时，工具会返回固定、脱敏的文案，不会泄露响应正文
技术实现
- 语言: TypeScript（Node.js 22+）
- 关键依赖:
@deepseek-ai/cordis、@deepseek-ai/dsh-tools、@deepseek-ai/dsh-attachment、@earendil-works/pi-ai - 架构模式: 在主插件 fiber 里注册 Cordis 服务
openaiCodexTransport，图片生成工具通过ctx.reflect.get拿到 transport 服务后再发起请求；view_image工具与图片生成工具分别由独立的子 fiber 注入，关闭能力即 dispose 对应 fiber - 入口文件:
src/index.ts（Host）、src/client/index.tsx（Web 设置与图片工具视图）
适用场景
想让 Codex 订阅下的对话模型既能读图又能生成图片的普通用户，不需要去申请额外的 OpenAI Platform API Key。场景举例：让 Agent 看一份本地的设计稿 PDF 后生成配图，或在公网调研阶段先 view_image 看截图、再用 prompt 直接产出配图。
前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| Node.js | ^22.19.0 或 >=24.0.0 | 由 package.json#engines 与 compatibility.json 共同声明 |
| DSH 插件 API 包 | 0.1.0-rc.7 | 包含 dsh-agent、dsh-llm、dsh-tools 等 13 个包，必须整体对齐升级 |
@earendil-works/pi-ai | 0.82.1 | 与 DSH 插件 API 包作为一个组合一起升级 |
| 平台 | 跨平台 | 插件未声明平台限制 |
安装方式
dsh plugin --profile web add github:franksong2702/dsh-codex-connect/packages/images
配置项
| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
enableImageTool | boolean | 是否注册 view_image 工具，允许模型从已审批的本地路径或公网 URL 读取图片 | false |
enableImageGeneration | boolean | 是否注册 codex_connect_image_generate 工具，让模型按文字描述生成图片并保存为 DSH 附件 | false |
enableSearch | boolean | 是否同时启用 Codex 独立搜索 provider（与图片能力并列的另一可选能力） | false |
searchModel | string | 独立搜索使用的模型 id | gpt-5.6-sol |
searchMode | enum | 搜索模式：cached、indexed、live | cached |
searchContextSize | enum | 搜索上下文规模：low、medium、high | medium |
searchMaxOutputTokens | number | 独立搜索响应允许的最大 token 数 | 10000 |
常见问题
Q: 需要先在设置页做什么才能用图片能力？
A: 先在 Codex Connect 卡片里点 Sign in with ChatGPT 完成 OAuth，然后在同一张卡里打开 启用图片生成（enableImageGeneration）与 启用 view_image（enableImageTool），点击 保存更改。能力关闭不会影响历史图片继续预览。
Q: 一次能生成几张图？能控制尺寸吗？
A: 一次 prompt 最多生成 4 张图，且受 DSH attachmentLimits 控制（单张字节、整批字节、像素上限）。插件不接受尺寸、质量、背景、张数或模型参数；输出大小与风格由服务端决定。
Q: view_image 能读取本地任意路径吗？
A: 可以，但读取路径要走 Harness 文件系统的审批流程，等同于普通文件读取工具；插件不会绕过权限。远程 source 必须是公网 HTTP(S) URL，且 DNS 与重定向都经过私网/元数据地址拦截。
Q: 图片生成失败时报错会暴露账户信息吗？
A: 不会。工具层把所有 transport 错误码映射为固定的本地化文案，不回显 OAuth、账户 id、响应正文或服务端日志；常见文案包括"重新登录""刷新授权""临时不可用，请稍后再试"等。
Q: 关闭 enableImageGeneration 后，旧的图片结果会消失吗？
A: 不会。工具会被注销、新调用会被拒绝，但图片本身以 DSH 附件形式保留在历史会话里，浏览器侧通过独立的工具视图 slot 继续渲染与下载。
Q: 安装时 github:franksong2702/dsh-codex-connect/packages/images 这个路径有问题吗？
A: 源码没有 packages/images 子目录；该路径按 DSH 插件市场约定用于指向"主包里的图片能力切片"，npm 与 GitHub 安装的实际包仍是根 package.json 中的 dsh-codex-connect，因此 dsh plugin ... add github:.../packages/images 实质等价于安装主包。
上手难度
入门 — 安装只需一行命令、设置页勾选两个开关即可启用，不需要写代码或自定义 endpoint。
已知问题与限制
- 单次 prompt 字符上限为 32000，超长或空白 prompt 直接拒绝
- 单张图片大小、总批次字节、单张像素上限都由 DSH attachmentLimits 决定，超过任意一项即整体失败，不返回部分结果
- 远程
view_image不支持 localhost、私网、link-local 与云元数据地址；任何 DNS 重定向都会被拦截并拒绝连接 - 图片生成请求 120 秒未返回即视为超时；取消时服务器侧仍可能继续处理，工具会附上"The request may still be processing"提示
- 图片生成在模型调用层以 exclusive 模式运行，一次模型回复内不会并行触发多次生成
- 图片生成结果强依赖 ChatGPT 订阅是否包含 GPT Image 能力，订阅变更或配额耗尽都会让
enableImageGeneration在运行时失效 - 关闭能力不影响历史图片回放，但开启与关闭切换依赖 DSH 0.1.0-rc.7 的 settings 生命周期；DSH rc.6 用户请留在 Alpha 4.9，否则配置 slot 可能不匹配
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-sparkmodel, 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: trueregisters Codex as an available search provider. It does not select the profile's global search route.enableImageTool: trueenablesview_imagefor approved local reads and public-network image fetches on vision-capable models.enableImageGeneration: trueenables 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
- Turn on Enable GPT Image generation in the Codex Connect card and select Save changes.
- Choose an
openai-codexGPT model for the conversation. - Describe the image you want in ordinary language. The agent can expand that request into the prompt sent to GPT Image.
- 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
| Field | Default | Values |
|---|---|---|
enableSearch | false | boolean |
enableImageTool | false | boolean |
enableImageGeneration | false | boolean |
searchModel | gpt-5.6-sol | Codex model id |
searchMode | cached | cached, indexed, live |
searchContextSize | medium | low, medium, high |
searchMaxOutputTokens | 10000 | positive integer |
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
logoutjust to renew a session. -
doctorreads process and filesystem metadata only.doctor --jsonemits 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 --jsonemits only signed-in or signed-out state with package metadata.status --jsonreads 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-requestevent can rundsh-codex-connect migrate-history --json, stop DSH, then apply the reported repair withmigrate-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(~/.dshby default).~/.codex/auth.jsonis 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:3080Replace 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-codexcollision, an olddsh-codexbundle 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
logoutonly 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-ai0.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-aias one group, then rundsh-codex-connect doctor --jsonand 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_tokensfield. 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_imageURLs 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