add-codex

name	add-codex
description	Add OpenAI/Codex as a backend. Guides through API key setup, service backend configuration, optional CLI setup, and verification. Can run alongside Claude (default) or replace it.
disable-model-invocation	true

Add OpenAI/Codex Backend

This skill configures OpenAI/Codex as a backend for Deus. Two independent modes:

• Service backend (DEUS_AGENT_BACKEND=openai) — container agents use the OpenAI Responses API for background message handling
• CLI sessions (deus codex) — foreground interactive sessions using the codex CLI binary

You can enable one or both. The Claude backend remains the default until explicitly switched.

IMPORTANT: This skill writes environment variables to .env and syncs them to data/env/env at runtime. It does not modify source code or require a rebuild.

Phase 1: Pre-flight

Check if already configured

Check if OpenAI/Codex is already set up:

grep -q 'OPENAI_API_KEY=.' .env 2>/dev/null && echo "API key found" || echo "No API key"
deus backend

If both show valid config, skip to Phase 5 (Verify).

Ask scope

AskUserQuestion: How do you want to use OpenAI/Codex?

1. Service backend — container agents use OpenAI for message handling (replaces Claude as default backend)
2. CLI only — use deus codex for interactive sessions (Claude stays as service backend)
3. Both — service backend + CLI sessions

Recovery: If you're unsure, start with CLI only (option 2). You can switch the service backend later with deus backend set codex.

Phase 2: API Key

Check for existing key

grep 'OPENAI_API_KEY' .env 2>/dev/null

If a key is already set and valid, skip to Phase 3.

Collect the API key

AskUserQuestion: Do you have an OpenAI API key? If not, create one at https://platform.openai.com/api-keys — you need a key with API access (not just ChatGPT Plus).

Wait for the user to provide their key.

Write to .env

Append or update OPENAI_API_KEY in .env:

# Update or append OPENAI_API_KEY:
if grep -q '^OPENAI_API_KEY=' .env; then
  tmpf=$(mktemp) && sed 's/^OPENAI_API_KEY=.*/OPENAI_API_KEY=<their-key>/' .env > "$tmpf" && mv "$tmpf" .env
else
  echo 'OPENAI_API_KEY=<their-key>' >> .env
fi

Sync to container environment

mkdir -p data/env && cp .env data/env/env

The container reads environment from data/env/env, not .env directly.

Recovery: If you see hasApiCredentials() failed in logs after setup, the key wasn't synced. Re-run the cp command above.

Phase 3: Backend Configuration

Skip this phase if the user chose CLI only (option 2) in Phase 1.

Set as default backend

deus backend set codex

This writes agent_backend: openai to ~/.config/deus/config.json and updates .env.

Model selection

AskUserQuestion: Which model do you want to use? Common options:

• gpt-4o (default, recommended)
• gpt-4o-mini (faster, cheaper)
• o3 (reasoning)
• Or any model available on your OpenAI account

deus backend model <their-choice>

Parity warnings

Surface these warnings to the user before proceeding:

Backend parity notice: OpenAI/Codex is functional but not yet at full parity with the Claude default. Current gaps:

Feature	Claude	OpenAI/Codex
Tool streaming	Live output	Batch response (no streaming)
Session protocol	Claude Code SDK	OpenAI Responses API
MCP tools	Native	Bridged via tool-broker
Live container verification	Yes	Not yet
Sessions	Not portable — a session started on one backend cannot be resumed on the other

These gaps are tracked and being closed. The system behavior (routing, tools, container environment) is identical regardless of backend — only the LLM interface differs.

To switch back to Claude at any time: deus backend set claude

Recovery: If messages stop being handled after switching backends, verify the key is valid and the model is available on your account. Revert with deus backend set claude.

Phase 4: CLI Setup (Optional)

Skip this phase if the user chose service backend only (option 1) in Phase 1.

The codex CLI binary is entirely separate from the service backend. Users who only want DEUS_AGENT_BACKEND=openai do not need the codex binary installed. The service backend uses the OpenAI Responses API directly.

Check if codex CLI is installed

command -v codex && codex --version || echo "codex CLI not found"

Install if needed

If not installed, tell the user:

The codex CLI is an OpenAI tool for interactive coding sessions. Install it:

npm install -g @openai/codex

After installation, verify: codex --version

Configure CLI model (optional)

If the user wants a different model for CLI sessions than the service backend:

# Set CLI-specific model (overrides DEUS_OPENAI_MODEL for deus codex only)
# Update or append DEUS_CODEX_MODEL:
if grep -q '^DEUS_CODEX_MODEL=' .env; then
  tmpf=$(mktemp) && sed 's/^DEUS_CODEX_MODEL=.*/DEUS_CODEX_MODEL=<model>/' .env > "$tmpf" && mv "$tmpf" .env
else
  echo 'DEUS_CODEX_MODEL=<model>' >> .env
fi

Sync: mkdir -p data/env && cp .env data/env/env

Test CLI

deus codex

This should launch an interactive Codex session. Exit with Ctrl+C.

Recovery: If deus codex says "codex CLI not found", the binary isn't in PATH. Check which codex or reinstall.

Register Deus memory MCP

For direct Codex CLI sessions outside the deus launcher, register the memory MCP through the repo launcher. Do not point Codex at python3 directly; the launcher selects a Python environment that has the mcp package installed and prints setup commands if dependencies are missing.

codex mcp add deus-memory -- "$(pwd)/scripts/deus-memory-mcp"
codex mcp get deus-memory

Phase 5: Verify

Restart the service

If the service backend was changed (options 1 or 3):

• macOS: launchctl kickstart -k gui/$(id -u)/com.deus
• Linux: systemctl --user restart deus
• Windows: nssm restart deus or servy-cli restart --name=deus

Confirm configuration

deus backend

Expected output should show the selected backend and model.

Check logs

tail -20 logs/deus.log

Look for:

• Backend: openai or similar initialization line
• No hasApiCredentials() failed errors
• No model-not-found errors

Test message (service backend only)

If the service backend was set to OpenAI, send a test message via a registered channel (WhatsApp, Telegram, etc.) and verify the agent responds.

Troubleshooting

hasApiCredentials() failed at startup

The OPENAI_API_KEY is missing or not synced to the container:

grep OPENAI_API_KEY .env          # Check .env
grep OPENAI_API_KEY data/env/env  # Check container env

If missing from data/env/env: mkdir -p data/env && cp .env data/env/env

codex CLI not found

The codex binary is not installed or not in PATH:

npm install -g @openai/codex
# Or check if it's installed elsewhere:
npm list -g @openai/codex

Model not available

OpenAI returned a model-not-found error. Check available models on your account:

curl -s -H "Authorization: Bearer $(grep OPENAI_API_KEY .env | cut -d= -f2)" \
  https://api.openai.com/v1/models | jq '.data[].id' | grep -i gpt

Set a valid model: deus backend model <valid-model>

Revert to Claude

deus backend set claude
launchctl kickstart -k gui/$(id -u)/com.deus  # macOS
# systemctl --user restart deus                # Linux
# nssm restart deus                            # Windows

Removal

To fully remove the OpenAI/Codex backend:

1. Switch back to Claude: deus backend set claude
2. Remove or clear the API key from .env: set OPENAI_API_KEY=
3. Clear CLI-specific vars if set: DEUS_CODEX_MODEL=, DEUS_CLI_AGENT=
4. Sync: mkdir -p data/env && cp .env data/env/env
5. Restart the service
6. Optionally uninstall the CLI: npm uninstall -g @openai/codex