codex-multiprovider-onboard

name	codex-multiprovider-onboard
description	Install, configure, validate, repair, or remove codex-multiprovider for a new macOS user from a repository checkout without exposing credentials or mutating external accounts.

Agent-run onboarding

Use this skill when the owner asks you to onboard this tool. Read AGENTS.md and this file completely before changing anything. The observable outcome is: doctor passes for the configured routes, the restarted Codex app lists the requested models, and one harmless visible task per requested route completes.

Authority and secrets

Read-only inspection and reversible local installation are in scope when the owner asks to install. Ask before changing an account, subscription, billing, repository, remote, security setting, or other external system. Do not create provider accounts or buy inference automatically.

Never ask the owner to paste an API key into chat. Never echo a key, include it in a prompt, commit it, or persist shell output containing it. Prefer the one-time credential-command import. The local config is owner-only mode 0600.

1. Inspect before mutation

Run these from the repository root:

uname -s
python3 --version
git status --short
test -f pyproject.toml

Require macOS and Python 3.11 or newer. Preserve a dirty checkout. Discover the real Codex executable; do not point real-codex at this tool's wrapper:

command -v codex
test -x "/Applications/ChatGPT.app/Contents/Resources/codex"

Prefer the signed desktop binary at /Applications/ChatGPT.app/Contents/Resources/codex when present. If Codex Desktop is already routed through the wrapper, obtain the real path from the existing public config with codex-multiprovider config show or from that application path. Stop if the path cannot be distinguished safely.

2. Install the local bridge

python3 -m venv .venv
.venv/bin/pip install .
.venv/bin/codex-multiprovider config set real-codex /absolute/path/to/real/codex

Configure only the routes the owner wants.

For DeepSeek or Kimi, import an OpenRouter credential without printing it:

.venv/bin/codex-multiprovider config set openrouter-credential-command "op read op://vault/item/credential"
.venv/bin/codex-multiprovider credentials import-openrouter

Replace the example command with the owner's approved secret-manager command. If no safe command exists, stop and ask the owner to run the documented local config set openrouter-api-key command themselves in a private terminal.

For Claude, use paths from an already installed, owner-controlled Claude Code setup:

.venv/bin/codex-multiprovider config set claude-cli /absolute/path/to/claude
.venv/bin/codex-multiprovider config set claude-config-dir /absolute/path/to/claude-profile

Then install and inspect the result:

.venv/bin/codex-multiprovider install
.venv/bin/codex-multiprovider doctor

Do not describe an on-disk pass as live app proof. The installer prints the wrapper path; set it for the current login session, fully quit Codex, and reopen it only when the owner has authorized restarting the app:

launchctl setenv CODEX_CLI_PATH "$HOME/.codex-multiprovider/install/codex-multiprovider-codex"

Run doctor again after restart. A stale desktop runtime means the old app process is still alive; fully quit every Codex/ChatGPT process and reopen once.

3. Visible canaries

Read the app-native create_thread catalog after restart. For DeepSeek, require the exact deepseek/deepseek-v4-flash row with max effort. For Opus, require claude-opus-5 with xhigh. Do not infer availability from a hidden subagent list or the model picker alone.

Create a projectless visible task with no private context and the prompt:

Reply with exactly: ROUTE_OK
Ownership: no files and no external systems.
Check: the final response equals ROUTE_OK.
Stop: immediately after that response.

Follow the app task lifecycle and verify the final response. The signed app-server has hardcoded 10-second shutdown bounds: use an immediate snapshot (timeoutMs: 0) or bounded sub-8-second waits, yielding between polls. Never make a blocking app-native call of 8 seconds or longer. A created task, picker row, or network request alone is not success. Run one canary per requested route. Delete nothing and do not use a real project as the canary.

4. Recovery and removal

If a model is absent: run doctor, confirm the OpenRouter or Claude route, confirm the wrapper path, fully restart the app once, then read the catalog again. After the same failure twice, stop and report the exact failed layer. Never swap to another model silently.

To remove the bridge, first restore the app's default CLI route and restart:

launchctl unsetenv CODEX_CLI_PATH
.venv/bin/codex-multiprovider uninstall

Uninstall removes only receipt-owned local links/runtime. It preserves account profiles. Report separately: source install, doctor, restarted app catalog, and completed canary evidence.