Codex Worker Runtime

Role-based external LLM delegation for Codex.

Codex stays the orchestrator and delegates bounded work through four MCP tools:

• delegate_work
• list_workers
• worker_health
• get_worker_run

Current routes

Role	Worker	Adapter
code_review	qwen	OpenAI-compatible API
x_research	grok	guarded Grok CLI
planning	kimi	opencodex Responses API
research	kimi	opencodex Responses API

Kimi is reached only through the worker runtime. The main Codex provider, history, CLI shim, account pool, and native subagent catalog do not need to be changed.

Guarantees

• External workers cannot edit local files or execute Codex commands.
• secret and credential requests are rejected before dispatch.
• Worker results are normalized into a stable transport and semantic contract.
• completed + rejected is preserved and is never overwritten by another provider.
• Unavailable or timed-out workers return control to Codex according to policy.
• Requests, attempts, and results are stored in a local SQLite audit ledger.
• Prepared requests and raw provider responses stay out of the normal result.

Configuration

The runtime loads the first available policy:

1. CODEX_WORKER_CONFIG
2. ~/.codex/codex-worker-runtime/workers.toml
3. bundled config/workers.toml

Relative worker commands are resolved from the policy file. ~/ paths expand to the current user home directory.

The bundled policy expects:

• an OpenAI-compatible Qwen endpoint at http://127.0.0.1:8081
• Grok Build installed at ~/.grok/bin/grok
• Grok privacy settings that pass runtime/grok/grok_privacy_guard.py
• opencodex listening on 127.0.0.1:10100 with the kimi provider authenticated

Start only the local proxy server used by the Kimi worker, without Codex model injection, history synchronization, a CLI shim, or a background service:

npm run start:kimi-proxy

To keep a custom policy outside the plugin, copy the file, update any relative worker commands for its new location, and set CODEX_WORKER_CONFIG to its absolute path.

Development

npm install
npm run check
npm run test:all

Local personal-plugin install

The installer creates named backups, stages the plugin, verifies source/target/cache hashes, and checks plugin activation.

node scripts/install-personal.mjs --dry-run
node scripts/install-personal.mjs

Optional environment variables:

• CODEX_WORKER_CODEX_ROOT
• CODEX_WORKER_CODEX_CLI
• CODEX_WORKER_INSTALL_TARGET
• CODEX_WORKER_MARKETPLACE
• CODEX_WORKER_AUDIT

Coexistence with opencodex

opencodex and Codex Worker Runtime can coexist because they operate at different layers:

• opencodex proxies the main Codex Responses API transport.
• Codex Worker Runtime delegates selected roles through MCP.

Recommended policy:

• keep the main Codex provider explicit
• avoid routing the same job to both a native routed subagent and an MCP worker
• review ~/.codex/config.toml after running ocx init or installing its shim
• let only one installer manage the Codex provider configuration and CLI shim
• keep credentials in each provider's own configuration; do not copy them into workers.toml

The runtime uses stdio MCP and does not bind opencodex's default port 10100. Its bundled Qwen example uses port 8081.

Adding a worker

1. Add the worker and role to config/workers.toml.
2. Reuse an existing adapter or add a dedicated adapter.
3. Normalize the response into the common result contract.
4. Add health, timeout, failure, audit, and redaction tests.

License

MIT