前言¶
DSH 的理念是「一切皆插件」，主 agent 可以通過 subagent 機制把任務拆給子 agent。但普通的 subagent 跑在 DSH 內部，和主對話用的是同一套環境；如果你想讓某塊工作交給 OpenAI Codex 完成——用 Codex 自己的模型和工具鏈、在與主對話隔離的進程裏跑——手動切終端、執行、再把結果貼回會話，流程很割裂。
dsh-subagent-codex 補的就是這一環。下面介紹它的定位、實現方式和用法。
這是什麼¶
dsh-subagent-codex（當前版本 0.1.1）由 mjylfz 維護，採用 MIT 許可證。安裝後，DSH 會話裏會註冊一個 subagent_codex 工具：你或主 agent 把任務描述交給它，插件在本機啓動一次獨立的 Codex CLI 任務去執行，結束後把最終輸出帶回主對話。任務在 Codex 的環境裏完成，與 DSH 主對話完全隔離——概括地說，DSH 負責統籌，Codex 負責幹活。
實現上，插件遵循 DSH 的 SubagentProvider 接口（@deepseek-ai/dsh-subagent 的 out-of-process 契約），註冊名爲 codex 的 provider。
工作機制¶
一次調用對應一次獨立任務¶
subagent_codex 是 one-shot 工具，每次調用都會 spawn 一次：
codex exec -- --skip-git-repo-check <prompt>
插件解析 Codex 輸出的 JSONL 事件流，取最後一條 agent_message 的文本作爲最終輸出，返回給委派方。
結果永遠返回終態¶
插件支持取消（AbortSignal 觸發時對進程發 SIGKILL）、超時和輸出截斷。無論正常結束、被中止還是執行失敗，結果都會解析爲終態返回，不會把異常拋進主對話。主 agent 拿到的是可處理的返回值，而不是一次中斷。
每次運行都有完整記錄¶
插件啓動 Codex 時不帶 --ephemeral，每次調用都會把完整會話寫入磁盤：
~/.codex/sessions/<YYYY>/<MM>/<DD>/rollout-<timestamp>-<session-id>.jsonl
文件裏是這次任務的完整對話：輸入、Codex 的中間過程、最終輸出。事後可以用 codex resume 找回該會話繼續，或用 codex archive 歸檔。
配置¶
provider 行支持的配置項如下：
- id: subagent-codex
name: 'dsh-subagent-codex'
config:
command: codex # codex CLI 可執行文件（PATH 名或絕對路徑）
cwd: /path/to/workdir # 可選，子任務工作目錄（缺省繼承父會話 workspace）
model: o3 # 可選，指定模型（codex exec -m）
sandbox: workspace-write # 可選：read-only | workspace-write | danger-full-access
timeoutMs: 600000 # 單次任務超時（毫秒），默認 600000
maxOutputChars: 40000 # 返回給委派方的輸出上限，默認 40000
其中 command 和 sandbox 值得多看一眼：command 決定插件去哪裏找 codex 可執行文件；sandbox 控制 Codex 執行任務時的文件系統權限級別。
安裝與啓用¶
先確認三個前提：
- Node >= 20；
- 已安裝 DeepSeek Harness；
- 已安裝 Codex CLI 並登錄（
~/.codex/auth.json存在）。不需要安裝 Codex 桌面 app，插件直接調用codexCLI。
然後執行安裝命令：
dsh plugin --profile web add dsh-subagent-codex
也可以用本地 tgz 安裝：
dsh plugin --profile web add file:/path/to/dsh-subagent-codex-0.1.1.tgz
插件通過 dsh.bundle 聲明（cordis.patch.yml）自動把自己加進 bundle 棧。裝好後重啓 DSH，新開一個會話即可使用，工具名是 subagent_codex。
典型用法¶
直接在會話裏說，例如：
讓 codex 調研一下大語言模型推理加速的最新論文進展，整理成一篇帶對比的綜述
或者「讓 codex 子 agent 做 XX」。幾個典型場景：
- 競品調研：讓 codex 對比 3 款主流筆記軟件的定價、功能、優缺點，給出選型建議和彙報材料；
- 學習：讓 codex 把「什麼是區塊鏈」拆成 5 個遞進小問題，多來源交叉驗證，輸出帶 FAQ 的學習文檔；
- 內容策劃：讓 codex 策劃小紅書爆款筆記，給出 3 個選題方向、標題、開頭鉤子、正文大綱和 5 條支撐素材；
- 開發改造：讓 codex 把用戶認證從 JWT 遷移到 OAuth2，改鑑權中間件、補遷移腳本、寫單測和集成測試，並整理提交說明。
這類任務的共同點是成塊交付、一次調用拿回成品，適合丟給 Codex 獨立完成。
適用場景與注意事項¶
適合：一次性、可獨立完成的任務（調研、綜述、方案、一次完整改造），且你希望借 Codex 的模型與工具鏈來幹。
不適合：需要在 DSH 內部完成的任務——比如要調用 DSH 的記憶、會話歷史或其他 DSH 工具。這類活兒交給普通 subagent。
使用前注意幾點：
- 外部進程的能力邊界。provider 不聲明任何 start 能力（
NO_START_CAPABILITIES），外部 CLI 無法強制執行outputSchema/maxDepth/toolFilter/persona。 - DSH 側邊欄看不到 codex 子 agent 的運行記錄。外部進程 provider 不創建 DSH 會話，要查看運行過程，去
~/.codex/sessions/目錄。 - 額度消耗。每次調用都用
~/.codex登錄的賬號跑 Codex，消耗對應的 OpenAI/Codex token 額度。 - 找不到 codex 命令（spawn ENOENT）。先執行
codex --version確認安裝；如果裝在非默認位置，把配置裏的command指向絕對路徑，如command: /path/to/codex。
最後，和所有 DSH 插件一樣，插件以當前 dsh 進程的權限運行。安裝前建議先閱讀源碼與許可證（本項目爲 MIT），確認符合自己的安全要求。
小結¶
dsh-subagent-codex 做的事情很單一：把 DSH 會話裏的任務委派給本機 Codex CLI，再把結果可靠地帶回來。one-shot 語義、終態返回、磁盤上的完整會話記錄，讓主 agent 可以放心把成塊的工作外包出去。
- GitHub：https://github.com/mjylfz/dsh-subagent-codex
- 社區插件目錄：https://www.skillhub.cn/plugins/mjylfz/dsh-subagent-codex
