DeepSeek Harness (DSH) is a plugin-based system designed to extend its functionality through external Bundles. The dsh-embedded-codex plugin provides the ability to integrate the official Codex App Server into DSH Web Sessions.

Plugin Overview

The plugin adds an Agent preset named “Codex Mode” to DSH. It allows a DSH Web Session to connect directly to and use the Agent Runtime of the official Codex App Server, while reusing the login state of ChatGPT Codex on the current machine.

In terms of runtime logic, the plugin implements a separation of responsibilities: Codex handles the Agent model loop, native tool calls, sandboxed environments, approval workflows, history hiding, and compression; while DSH continues to handle Session management, Web/API interfaces, conversation trajectory display, and persistent storage. Other existing DSH Agent presets are unaffected by this plugin.

Environment and Installation

Before installing, make sure the environment meets the following requirements:

  • Node.js: ^22.19.0 or >=24.0.0
  • pnpm: 11.7.0
  • Git: Installed and submodule initialized
  • ChatGPT Codex: An account with the required permissions that is logged in

The installation process is as follows:

  1. Generate the package
    First run the packaging command in the plugin directory to generate a .tgz file.
    pnpm pack
  1. Install the plugin
    Use the DSH CLI to install the generated tarball into the Web Profile.
    dsh plugin --profile web add .\dsh-embedded-codex-0.1.0.tgz
  1. Start Web
    After installation is complete, start DeepSeek Harness Web.
    dsh web

Feature Description

  1. Agent Mode Switching
    Open a new DSH Session and switch to “Codex Mode” in the mode selector. This mode does not require configuring DEEPSEEK_API_KEY; instead, it directly uses Codex credentials.

  2. Pinned Dependency Version
    The plugin internally enforces the use of @openai/codex@0.149.1 and does not invoke other versions of the Codex CLI from the system PATH.

  3. Separation of Responsibilities

    • Codex is responsible for: model loop, native tools, sandbox, approvals, history hiding, and compression.
    • DSH is responsible for: Session management, Web/API, conversation trajectory, and persistent storage.

  4. Compatibility Implementation
    The plugin provides compatible alternative implementations for four Host providers and two permission UI owners to ensure integration with existing DSH environments.

Permission Modes

In Codex Mode, the DSH permission selector switches to Codex’s three stable modes. The permission selection is recorded in the Session and takes effect on the next turn/start.

UI Mode App Server Setting Behavior
Ask for approval workspaceWrite + on-request + user Execute directly within the workspace; request user approval when network access or boundary crossing is needed
Approve for me workspaceWrite + on-request + auto_review Sandbox boundary unchanged; qualifying out-of-bound requests are sent to automatic review
Full access dangerFullAccess + never Do not use Codex file and network sandbox; do not show approval prompts

Configuration

Behavior can be customized by overriding the embedded-codex entry in the Profile patch. The default configuration is as follows:

- id: embedded-codex
  config:
    requireChatgptLogin: true
    providerName: codex
    providerDisplayName: Codex
    defaultModelAlias: default
    env: {}
    processCwd: 当前进程目录
    approvalPolicy: on-request
    sandbox: workspace-write
    disposeGraceMs: 3000
    stderrMaxBytes: 65536

Development and Debugging

If you are a developer, you can use the following commands for local development:

  • pnpm dev: Build, ensure the local development link, and start an isolated DSH Web. This command creates a stable local link; subsequent plugin code changes only trigger rebuilding, not reinstallation of Codex.
  • pnpm dev:install: Build, pack, and perform a one-time real tarball installation to verify release boundaries.
  • pnpm dev:web: Start an already installed isolated Web without rebuilding.
  • pnpm dev:remove: Remove the development plugin from the isolated Web Profile.
  • pnpm pack: Generate an installable .tgz file.

If you need to run tests separately, you can use:

pnpm exec vitest run tests/runtime.spec.ts

Summary

The dsh-embedded-codex plugin solves the integration challenge of directly using the official Codex App Server in DeepSeek Harness. Through a clear division of responsibilities and compatibility implementations, it allows developers to leverage the Codex Agent Runtime for development and testing without modifying DSH core code.