franksong2702/dsh-codex-connect

English | 中文

通过 OAuth 将你的 ChatGPT 订阅连接到 DeepSeek Harness，同时保留用户自主默认项、Harness 原生审批、非敏感诊断和可靠的会话恢复。

dsh-codex-connect 提供 openai-codex 模型目录和独立的 ChatGPT OAuth 登录。模型仍走 Harness 标准 LLM 服务，因此流式输出、工具调用、reasoning replay、压缩、文件系统控制、权限门禁和审批提示仍由 Harness 负责。ChatGPT 订阅不会因此变成 OpenAI Platform API 凭据。

安装是增量的：bundle 不会替换当前主模型或搜索路由；独立搜索提供方和 view_image 工具也默认关闭，必须显式开启。

本中文指南中的 UI 截图均来自中文本地化的 Harness 界面；English 版 使用同一状态的英文截图。模型与提供方标识保留其规范拼写，不随界面语言翻译。

五分钟快速开始

本指南使用 web profile。请把 web 替换成你已经在用的 Harness profile 名称。你需要先有可用的 dsh 安装；如果在 DeepSeek Harness 源码 checkout 中运行，请在命令前加 pnpm。

1. 将插件装入一个 profile

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

预期结果：包被加入该 profile。这个动作不会更改 profile 的默认模型或全局搜索路由。

如需精确复现这个版本，使用 dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.10。对应 GitHub prerelease 已创建但 npm 不可用时，可使用 dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.10'。本地 checkout 可安装为 link:/absolute/path/to/dsh-codex-connect。

2. 启动 Harness

dsh web

预期结果：所选 profile 的 Harness Web UI 打开。

3. 找到 Codex Connect 卡片

打开 设置 → 插件 → 插件配置 → Codex Connect。

预期结果：新安装时账户区显示 尚未登录，并出现 使用 ChatGPT 登录 按钮。之后管理可选能力也在同一张卡片中完成。

4. 使用 ChatGPT 登录

点击 使用 ChatGPT 登录，并自行完成浏览器审批。不要把授权 URL、授权码、token 或账户标识复制到 Issue、日志或配置文件中。

预期结果：账户区变为 已登录。下图展示的是完成本步骤后的成功状态，不是开始登录前的页面。

5. 选择模型并做一次安全检查

打开 Harness 原生模型选择器，为当前正在使用的 agent 或会话选择一个 openai-codex 模型。这个选择与写入 profile 的默认模型或全局搜索路由是两件事。

选择器会把可用项归在 OpenAI Codex 下。GPT-5.6 Luna 一类模型标识是规范名称，因此会保留原样，不翻译。

如需在本机确认插件配置行，运行：

dsh --profile web --dump-config

预期结果：配置中恰好有一条 llm-openai-codex。请只在本机查看这份配置输出，它可能包含无关的 profile 设置。

如需不启动 OAuth 的非敏感状态和诊断输出，运行：

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

预期结果：status --json 报告 signed-in 并以 0 退出，doctor --json 只输出一条非敏感 JSON。尚未登录时 status --json 会以 1 退出；回到第 4 步登录即可，不要把它当作插件故障。

可选能力（默认关闭）

安装后的 bundle 只注册模型提供方，默认不额外启用任何能力：

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

打开 设置 → 插件 → 插件配置 → Codex Connect，即可在同一张卡片中管理账户和这些选项。保存更改只影响本插件的能力配置并即时生效，绝不会选择默认模型或全局搜索路由。

只开启你准备使用的能力

• enableSearch: true 会把 Codex 注册为可选择的搜索提供方，不会把它选为 profile 的全局搜索路由。
• enableImageTool: true 会为具备视觉能力的模型启用 view_image，用于审批后的本地读取和公网图片获取。

下图是有人显式开启能力之后的配置示例，不是新安装的默认状态。本中文指南使用中文本地化截图；English 版展示同一状态的英文截图。

单独更改默认模型或全局搜索路由

如需把 Codex 模型设为新 agent 的默认模型，需要自行添加或修改独立的 Harness 配置项：

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

如需把 Codex 选为 profile 的全局搜索路由，还需要另做一次显式配置：

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

- id: web
  config:
    searchProvider: openai-codex

重新登录、诊断与冲突

• 卡片显示 重新登录，或服务端要求重新认证时，点击该操作并完成同一套安全的浏览器流程。它会保留本插件的能力配置，不会偷偷改动默认模型或全局搜索路由。不要为了刷新会话而运行 logout。

• doctor 只读取进程与文件系统元数据。doctor --json 只输出一条可解析的非敏感 JSON，包含 schema version 1、包/版本/Node 信息、认证文件状态与安全 mode、能力、冲突状态和提示；它省略认证文件绝对路径以及 OAuth、账户和过期时间信息。

• status --json 只输出 signed-in 或 signed-out 状态及包元数据。它只为判断登录态读取认证文件，但不会输出认证文件内容或启动 OAuth。

• OAuth 单独存储于 $DSH_HOME/.openai-codex-auth.json（默认 ~/.dsh）。~/.codex/auth.json 不会被复制或修改。支持的平台上，父目录与文件使用仅所有者可访问权限；写入采用原子替换，刷新写入使用跨进程文件锁。

• 默认情况下，OAuth 路由只接受 loopback 浏览器请求。当 DSH 在一台设备运行，而你从可信网络中的另一台设备打开 DSH 时，请在运行 DSH 的设备上显式批准浏览器地址栏中的 origin：

  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
  

  将示例替换为浏览器地址栏中的精确 origin，包括协议和端口；不要填写当前访问设备的 IP、裸主机、路径、query 或 fragment。只在你信任的网络中使用，不要把该路由暴露到公网；不适合显式信任网络时，请使用 SSH tunnel。浏览器页面只会显示并复制这条命令，不会自行修改授权列表。

• 启动报告 openai-codex 冲突时，旧 dsh-codex bundle 或手动 provider 配置可能已占用该 adapter。先检查有效配置，只移除已确认的冲突所有者。不要删除认证文件或无关 provider。

• 移除包不会删除 OAuth 状态；只有确实需要删除凭据时才运行 logout。

兼容性与安全边界

• 当前唯一已验证的兼容组合是 DSH 插件 API packages 0.1.0-rc.7、@earendil-works/pi-ai 0.82.1 和 Node.js ^22.19.0 || >=24.0.0；详见 compatibility.json。Alpha 4.10 使用 rc.7 的 keyed 插件配置 slot；DSH rc.6 用户应继续使用 Alpha 4.9。
• 升级时请将 DSH 插件 API packages 与 @earendil-works/pi-ai 作为一组升级，再运行 dsh-codex-connect doctor --json 和兼容性检查。本契约不对未来版本作判断。
• ChatGPT 套餐资格、模型权限、额度和后端行为由 OpenAI 控制，可能变化。
• Codex 端点不会强制普通 Responses 的 max_output_tokens 字段。Harness 压缩仍可工作，但这个摘要上限不能由服务端在该路由上强制。
• shell、文件系统、skills、MCP、subagents、审批、权限、附件、会话持久化、压缩与恢复继续由当前 Harness profile 提供。
• 远程 view_image 只允许公共 HTTP(S) 目标；每一次 DNS 结果与重定向都会重新检查，并将连接固定到已验证地址，从而阻止 localhost、私网、link-local 服务和云元数据地址。
• 安装、构建、测试、doctor 和包内容验证均不需要真实 OAuth。

详见 安装运行手册、Alpha 发布清单、MIGRATION.md 与 架构说明。

开发

pnpm install --frozen-lockfile
pnpm run check

发布

维护者通过手动 OIDC 发布 workflow发布 Alpha；latest 的独立短期提升步骤见 Alpha 发布清单。

法律与致谢

Codex Connect 的修改与新增工作 Copyright 2026 Frank Song。本项目包含派生自 Yan-Zero/dsh-codex 的软件；上游内容继续保留 Copyright 2026 Yan-Zero。两部分均按 Apache-2.0 发布，详情见 NOTICE。本项目与 OpenAI、ChatGPT、Codex、DeepSeek 或 DeepSeek Harness 不存在隶属关系，也未获得其背书。

许可证

Apache-2.0