# Codex Multi-Model Workers

[Chinese documentation](README.zh-CN.md)

A distributable Codex plugin that connects Codex to local and cloud language models through a controlled MCP worker boundary.

Supported providers:

- MoE4All local GGUF servers
- GLM official cloud API and custom compatible endpoints
- DeepSeek official cloud API and custom compatible endpoints
- Generic OpenAI-compatible Chat Completions endpoints

Codex remains the controller. Workers return analysis, implementation proposals, or patch text and never receive direct write authority over the main working tree.

## Requirements

- A Codex build with plugin marketplace support
- Node.js 20 or newer available as `node`
- Provider credentials in environment variables when cloud APIs are used
- MoE4All and a GGUF model already downloaded when local inference is used

The committed MCP bundle is self-contained. End users do not run `npm install`.

## Install

Add this Git repository as a Codex marketplace:

```powershell
codex plugin marketplace add aaa17001/codex-multi-model-workers
```

Install the plugin:

```powershell
codex plugin add codex-multi-model-workers@multi-model-workers
```

Start a new Codex task so the Skill and MCP tools are discovered. Invoke the Skill as `$multi-model-workers` in CLI/IDE environments or `@multi-model-workers` where the Codex app exposes Skills with `@`.

## Secrets

Set API keys in the environment that launches Codex. Do not put key values in provider JSON, prompts, repository files, or VS Code configuration.

PowerShell current session:

```powershell
$env:GLM_API_KEY = 'your-key'
$env:DEEPSEEK_API_KEY = 'your-key'
$env:MOE4ALL_API_KEY = 'your-optional-local-key'
```

Bash current session:

```bash
export GLM_API_KEY='your-key'
export DEEPSEEK_API_KEY='your-key'
export MOE4ALL_API_KEY='your-optional-local-key'
```

GLM also recognizes `ZAI_API_KEY` when the configured name is `GLM_API_KEY` and that variable is absent.

The plugin MCP explicitly forwards these variable names from Codex: `GLM_API_KEY`, `ZAI_API_KEY`,
`DEEPSEEK_API_KEY`, `MOE4ALL_API_KEY`, `OPENAI_API_KEY`, `TEAM_GLM_API_KEY`,
`TEAM_DEEPSEEK_API_KEY`, and `TEAM_MODEL_API_KEY`. Set `apiKeyEnv` to one of these names. Values are
never stored in the plugin manifest.

## Configure Providers

Ask the Skill to configure only the provider you need:

```text
Use $multi-model-workers to configure the official DeepSeek API with model deepseek-chat.
```

```text
Use $multi-model-workers to configure a custom GLM-compatible endpoint at https://gateway.example.com/glm/v1.
```

Configuration tools accept `apiKeyEnv`, which is an environment variable name. They reject literal `apiKey`, `token`, `secret`, and `password` fields.

Default non-secret configuration locations:

- Windows: `%APPDATA%\codex-multi-model-workers\config.json`
- macOS/Linux: `${XDG_CONFIG_HOME:-~/.config}/codex-multi-model-workers/config.json`
- Override: `CODEX_MULTI_MODEL_CONFIG`

See [`providers.example.json`](plugins/codex-multi-model-workers/config/providers.example.json) and the [Provider reference](plugins/codex-multi-model-workers/skills/multi-model-workers/references/providers.md).

## MoE4All

MoE4All paths are machine-specific and are never hard-coded by the plugin. Configure absolute paths, loopback host, port, and the model id exposed by the server:

```text
Use $multi-model-workers to configure MoE4All with infr.exe at D:\Tools\MoE4All\infr.exe and model D:\Models\model.gguf. Bind 127.0.0.1:8080 and enable --think.
```

Then ask the Skill to start the configured provider. The plugin:

- refuses non-loopback managed launches
- passes arguments without a shell
- keeps the API key out of process arguments
- records the owned PID only after `/health` succeeds
- refuses to stop a PID whose command line no longer matches both configured paths

The plugin does not download MoE4All or GGUF files.

## Route And Ask Workers

```text
Use $multi-model-workers to recommend a worker for scanning this repository.
```

`route_task` is advisory and sends no task content. After reviewing the recommendation, ask the selected worker explicitly:

```text
Use $multi-model-workers to ask local-moe to analyze this log. Do not modify files.
```

High-risk, architecture, security, cross-module, and final-review work remains with Codex.

## VS Code

After configuring providers:

```text
Use $multi-model-workers to add local-moe, glm, and deepseek to my VS Code language models.
```

The plugin merges provider groups into `chatLanguageModels.json`, preserves unrelated groups, and creates a timestamped backup. Generated entries use explicit Chat Completions URLs and VS Code `${input:...}` secret references.

VS Code is only an API client. Its model configuration does not start `infr.exe` or load a GGUF model.

## Tools

| Tool | Purpose |
| --- | --- |
| `providers_list` | List non-secret configuration and credential availability. |
| `provider_status` | Probe one provider with a bounded timeout. |
| `provider_configure` | Persist non-secret settings after confirmation. |
| `worker_chat` | Request read-only worker analysis. |
| `route_task` | Recommend a target without sending the task. |
| `moe4all_start` | Start a loopback-only local server after confirmation. |
| `moe4all_stop` | Stop a verified plugin-owned process after confirmation. |
| `vscode_configure` | Back up and merge VS Code model entries after confirmation. |

## Development

```powershell
npm ci --prefix plugins/codex-multi-model-workers/mcp
npm test
```

`npm test` rebuilds the committed self-contained MCP bundle and runs the full test suite, including a stdio acceptance test from an isolated directory with no `node_modules`.

See [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), and the [design](docs/superpowers/specs/2026-08-31-codex-multi-model-workers-design.md).

## License

MIT