dsh-workbuddy-stack
English | 简体中文
A DeepSeek Harness plugin that keeps the local WorkBuddy reverse-proxy chain alive — the model picker's provider, the gateway behind it, and the Responses bridge that OpenAI Codex CLI needs.
Three things have to line up before a WorkBuddy model can answer, and none of them installs itself as a Windows service:
| Port | Service | Role |
|---|
127.0.0.1:7863 | wb2api gateway | OpenAI-compatible /v1/chat/completions |
127.0.0.1:7864 | Responses bridge (bundled) | Responses API → chat/completions, for Codex CLI |
| — | workbuddy provider | the model-picker route, mounted from dsh-llm-workbuddy |
Both processes used to be started by hand, so a reboot silently left the model picker pointing at a dead port — the provider plugin loaded fine, listed models fine, and failed on the first request. This plugin supervises them: on load it probes each health endpoint, spawns whatever is missing, and re-checks on a timer so a crashed process comes back.
It deliberately does not reimplement the gateway, and does not fork the adapter either. The gateway is orchestrated as a process. The provider route is mounted by delegating to dsh-llm-workbuddy with ctx.plugin() — that package owns the ~2.5k-line WorkBuddy adapter, its settings section and its daily checkin scheduler, and a second copy of all that would drift the moment either side is updated. So one install covers provider + gateway + bridge.
The delegation is additive, not exclusive: if you also keep dsh-llm-workbuddy enabled standalone, whichever plugin registers the route first keeps it and the other stands down with a log line, so both layouts are safe.
Settings
Everything lives under the workbuddy-stack entry's config in the profile's cordis.yml; the shipped cordis.patch.yml has the full default set.
| Key | Default | What it does |
|---|
gatewayDir | ~/Documents/deepseek-harness/default-workspace/workbuddy2api-panel | Where the gateway keeps config.json. The api_key in it is used for both the bridge and the provider, so the port and the key are configured once. |
provider.enabled | true | Register the workbuddy route. |
provider.baseURL | (empty → gateway.baseURL) | Gateway URL for the adapter. |
provider.discovery | true | Ask the gateway's /v1/models for the live catalog. |
provider.autoCheckin | true | Claim the daily WorkBuddy checkin. |
gateway.acceptStatus | [200, 503] | The gateway answers 503 while running without a usable account — alive, not down. |
bridge.conversationId | auto | Not optional against a WorkBuddy gateway: without it the upstream answers 400 / 11-128 and the gateway disables the account. |
If dsh-llm-workbuddy is not installed at all, the plugin still supervises the gateway and the bridge and logs the one command that fixes it (dsh plugin add dsh-llm-workbuddy). Nothing throws.
Why the bridge is bundled
codex-cli 0.1xx+ dropped wire_api = "chat" and speaks only the OpenAI Responses API (POST /v1/responses, SSE). A WorkBuddy gateway implements only Chat Completions (POST /v1/chat/completions). Point Codex straight at the gateway and every request dies with:
unexpected status 404 Not Found, url: http://127.0.0.1:7863/v1/responses
There is no config flag around this — Codex rejects wire_api = "chat" at load time. A translation layer is mandatory, so this package ships one:
Codex CLI --(Responses)--> bridge :7864 --(ChatCompletions)--> gateway :7863 --> WorkBuddy
It is the same code as codex-chat-bridge, vendored at bridge/codex-chat-bridge.mjs (zero dependencies, runs on the harness's own Node) so installing this plugin is the only step — there is no second repo to clone and no path to fill in.
Install
dsh plugin add git+https://github.com/kangjiazhen/dsh-workbuddy-stack.git
Or from a local checkout:
dsh plugin add file:/path/to/dsh-workbuddy-stack
The plugin ships a cordis.patch.yml, so the profile picks up the workbuddy-stack entry automatically once the package is a profile dependency.
If the git install fails
pnpm rewrites git+https://… to git+ssh://git@… unless told otherwise, so an install on a machine without GitHub SSH keys fails with Permission denied (publickey):
npm config set git-protocol https
Behind a proxy, git also needs to be told about it, because pnpm shells out to the git binary and does not forward its own proxy settings:
git config --global http.proxy http://127.0.0.1:7890
Using it with Codex
The bridge listens on 7864 and presents a Responses API. Point Codex at it:
# ~/.codex/config.toml
model = "global:gpt-5.3-codex"
model_provider = "wb"
[model_providers.wb]
name = "workbuddy"
base_url = "http://127.0.0.1:7864/v1"
wire_api = "responses"
experimental_bearer_token = "anything"
request_max_retries = 2
stream_max_retries = 2
The bearer is not checked by the bridge — it authenticates to the gateway itself with the key it reads from the gateway's config.json. Set it to any non-empty string; Codex refuses to start without one.
Then just use Codex normally:
codex exec "list the files in this directory"
If you pick a model your account tier cannot use, the gateway answers 11158 model not allowed for user type [...]. That is an account property, not a bridge fault — see Model availability.
Two settings you must not skip
1. conversation_id — the one that can disable your account.
The WorkBuddy upstream validates three headers (X-Conversation-ID, X-Conversation-Request-ID, X-Conversation-Message-ID) and answers 400 {"code":"11-128","msg":"request illegal"} when they are missing. The gateway classifies that as an account fault and responds by disabling the account — every account it touched, in the same pass. The resulting message says re-login required, which is misleading: the credentials are usually still valid and reviving them restores service immediately.
So the bridge defaults to conversationId: auto: it derives a stable id per Codex session (from prompt_cache_key) and sends it as metadata.conversation_id. Do not blank this out. The plugin warns at startup if you do.
If you have already tripped it, revive the accounts rather than re-logging in:
# gateway panel: http://127.0.0.1:7863/panel/
curl -X POST http://127.0.0.1:7863/panel/api/accounts/<uid>/revive
2. The bearer must match the gateway's api_key.
The gateway answers 401 to every request without it. Rather than making you copy the secret, the plugin reads api_key straight out of the gateway's config.json (that is what gatewayDir is for) and hands it to the bridge. Set bridge.apiKey only to override that.
Configuration
The defaults assume the usual layout and can be overridden in the profile's cordis.yml:
- id: workbuddy-stack
name: dsh-workbuddy-stack
config:
intervalMs: 15000 # re-probe cadence
probeTimeoutMs: 2000 # per-probe timeout
gatewayDir: ~/Documents/deepseek-harness/default-workspace/workbuddy2api-panel
gateway:
enabled: true
autostart: true
baseURL: http://127.0.0.1:7863
acceptStatus: [200, 503]
command: ~/Documents/deepseek-harness/default-workspace/workbuddy2api-panel/wb2api.exe
args: [-config, config.json]
cwd: ~/Documents/deepseek-harness/default-workspace/workbuddy2api-panel
bridge:
enabled: true
autostart: true
baseURL: http://127.0.0.1:7864
acceptStatus: [200]
command: '' # empty = run the bundled bridge
upstream: '' # empty = the gateway's baseURL
apiKey: '' # empty = read gatewayDir/config.json
conversationId: auto # required — see above
modelAllowlist: [] # empty = forward every model
Paths accept ~, $VAR / ${VAR}, and Windows %VAR%, so a config file can be copied between machines without rewriting the home directory.
bridge.command is empty on purpose. Setting it switches the plugin from "run the bundled bridge" to "supervise this command instead", which is how you'd point it at a different bridge build; CCB_PORT, CCB_UPSTREAM and the rest of the environment are still derived for you.
acceptStatus matters
The gateway answers 503 on /healthz while it is running but has no usable upstream account yet (nothing signed in, or every account cooling down). That is alive, not down.
A supervisor that only accepted 2xx would read that as "not started", spawn a second copy, and lose the port race. So the gateway entry accepts [200, 503] by default, while the bridge accepts [200] only.
autostart: false
Observe without ever spawning. Use this when something else owns the lifecycle — a scheduled task, a container, a wrapper script — and you only want the health reporting.
Status tool
When the tools seam is mounted, the plugin registers workbuddy_stack_status:
gateway: up (http://127.0.0.1:7863/healthz, pid 14592)
bridge: up (http://127.0.0.1:7864/healthz)
Each line carries the live probe result, the supervised child pid, and the last spawn error if there was one — so "the model list is empty" can be told apart from "the port is dead" without reading logs.
If @deepseek-ai/dsh-tools is not importable, the tool is still registered from the raw descriptor; if the tools seam is absent, the supervisor still runs. Neither is required for the other.
Lifecycle
- The first supervision pass runs asynchronously right after
apply(), so a cold start never blocks the harness.
- The timer is
unref'd — an idle supervisor cannot hold the process open.
- On dispose the timer stops and any child this plugin spawned is terminated. A service that was already running before the plugin loaded is left alone: it is probed and reported, never adopted, so unloading the plugin does not kill a process someone else started.
Model availability
Which models answer is a property of your WorkBuddy account tier, not of this plugin or the bridge. A personal_free_user account, measured on 2026-10-21, could reach:
| Realm | Working |
|---|
global: | gpt-5.3-codex, glm-5.3, glm-5.2, kimi-k3, kimi-k2.6, hy4-preview, step-5-preview, deepseek-v4.1-flash, minimax-m3.1-flash |
cn: | deepseek-v4.1-flash, deepseek-v4-pro, glm-5.3 |
Every other GPT model (gpt-5.4, gpt-5.5, the gpt-6-* family, …) answered 11158 model not allowed for user type [personal_free_user]. That list moves with your subscription, so treat it as a snapshot, not a contract.
modelAllowlist exists to fail fast on models you know are unreachable: the bridge rejects them with a local 400 model_not_allowed instead of letting the gateway classify the refusal as an account fault and disable the pool. Leaving it empty is the honest default.
Scope and limits
- Process supervision plus a request translator. It does not start, stop, or configure the upstream provider, and it has no opinion about which models your account may use.
- No restart backoff: a child that dies instantly is respawned once per
intervalMs. If the binary is missing or the port is held by a foreign process, the logs will say so on every pass rather than spinning.
windowsHide: true is set on spawn, so a supervised console child does not flash a window on Windows.- Linux and macOS work with the same code; only the default paths in
cordis.patch.yml are Windows-specific.
- The upstream WorkBuddy project has stopped maintenance and is actively tightening anti-proxy checks. This plugin keeps the chain alive; it cannot keep the upstream channel open.
Related
- codex-chat-bridge — the bridge this plugin bundles, if you want it standalone.
- LiteLLM, one-api, new-api — full gateways, if you need routing and key management rather than local process supervision.
License
MIT
