codexplus

Offline npx helper for configuring Codex, Claude Code, Claude Desktop, Hermes, and OpenClaw to use a compatible endpoint.

The tool only edits local configuration files. It does not send network requests, validate keys with a server, or upload anything.

Supported Clients

• Codex: ~/.codex/config.toml and ~/.codex/auth.json
• Claude Code: ~/.claude/settings.json
• Claude Desktop: macOS/Windows Claude app config plus Claude-3p/configLibrary profile files
• Hermes: ~/.hermes/config.yaml
• OpenClaw: ~/.openclaw/openclaw.json

Platform paths are resolved from the current user's home directory unless an explicit path is passed. Claude Desktop 3P config writing is supported on macOS and Windows. Linux/Ubuntu has Claude Code support via ~/.claude/settings.json, but there is no official Claude Desktop 3P local config target for the tool to write.

Usage

From this folder:

npx .

If npx is not available on Windows, use the included PowerShell wrapper:

.\codexplus.ps1 --target codex --dry-run
.\codexplus.ps1 verify --target codex

After publishing to npm:

npx @haveagoodday1205/codexplus

Configure every supported client:

npx @haveagoodday1205/codexplus --target all --key sk-your-api-key --base-url https://your-endpoint.example

Interactive setup:

npx @haveagoodday1205/codexplus

The interactive setup first asks for the client family:

• Codex family: Codex, Hermes, OpenClaw
• Claude family: Claude Code and Claude Desktop

It then probes the recommended base URLs below with /v1/models and shows the round-trip time in milliseconds before you choose one:

• https://codexplus.shop
• https://api.codexplus.shop

It then asks for the model, API key, and whether to run verification or a real client smoke test after writing.

Configure one client:

npx @haveagoodday1205/codexplus --target codex
npx @haveagoodday1205/codexplus --target claude --model claude-opus-4-6
npx @haveagoodday1205/codexplus --target claude-desktop --model claude-opus-4-6
npx @haveagoodday1205/codexplus --target claude-group --model claude-opus-4-6
npx @haveagoodday1205/codexplus --target codex-group
npx @haveagoodday1205/codexplus --target hermes --model gpt-5.5
npx @haveagoodday1205/codexplus --target openclaw --model gpt-5.5

Dry-run before writing:

npx @haveagoodday1205/codexplus --target all --dry-run

Verify after writing:

npx @haveagoodday1205/codexplus verify --target all

Run real client smoke tests:

npx @haveagoodday1205/codexplus verify --target all --smoke

verify checks local config files, stored API keys, and the configured /v1/models endpoint, prints every returned model id, and prints the observed latency in milliseconds. --smoke also launches the actual client commands and asks each client to reply to a short prompt.

For Hermes, the default remains api_mode: codex_responses so it matches Codex/OpenClaw. If a proxy has a Responses SSE incompatibility, you can temporarily fall back with --hermes-api-mode chat_completions.

PowerShell:

$env:CODEXPLUS_API_KEY = "sk-your-api-key"
npx @haveagoodday1205/codexplus --target all --base-url "https://your-endpoint.example"

Options

--target <name>             codex, claude, claude-desktop, hermes, openclaw, codex-group, claude-group, or all. Default: codex.
--key <key>                 API key. Can also use CODEXPLUS_API_KEY, OPENAI_API_KEY, or ANTHROPIC_AUTH_TOKEN.
--base-url <url>            OpenAI-compatible base URL. Default: https://codexplus.shop.
--model <id>                Primary model. Default: gpt-5.5, or claude-opus-4-6 for --target claude.
--review-model <id>         Optional Codex review model / secondary model.
--reasoning-effort <value>  Codex reasoning effort. Default: xhigh.
--provider <name>           Provider name for all targets.
--codex-provider <name>     Codex provider name. Default: codexplus.
--hermes-provider <name>    Hermes provider name. Default: codexplus.
--hermes-api-mode <mode>    Hermes API mode: codex_responses or chat_completions.
--openclaw-provider <name>  OpenClaw provider id. Default: codexplus.
--codex-home <dir>          Codex home directory. Default: CODEX_HOME or ~/.codex.
--config <file>             Codex config.toml path.
--auth <file>               Codex auth.json path.
--claude-config <file>      Claude Code settings.json path. Default: ~/.claude/settings.json.
--claude-desktop-dir <dir>  Claude Desktop 3P config directory. Default: platform local Claude-3p dir.
--hermes-config <file>      Hermes config.yaml path. Default: ~/.hermes/config.yaml.
--openclaw-config <file>    OpenClaw JSON path. Default: ~/.openclaw/openclaw.json.
--clean-codex-inline-tokens Remove experimental_bearer_token lines from Codex TOML.
--no-backup                 Do not create .bak-codexplus-* files before writing.
--dry-run                   Print planned changes without writing files.
--verify-after              After writing, run verify for the same target.
--smoke                     In verify mode, run real client prompts.
--prompt <text>             Smoke-test prompt. Default: Reply OK only.
--timeout <seconds>         Verify command/network timeout. Default: 120.
--insecure                  In verify mode, ignore TLS certificate errors.
--show-secrets              Do not redact keys in output.

If --key is omitted, the tool first checks existing client config for a saved key. If no key exists, it asks for one interactively.

What It Writes

Codex

config.toml:

model_provider = "codexplus"
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
disable_response_storage = true
network_access = "enabled"
windows_wsl_setup_acknowledged = true
model_context_window = 1000000
model_auto_compact_token_limit = 900000

[model_providers.codexplus]
name = "codexplus"
base_url = "https://codexplus.shop"
wire_api = "responses"
requires_openai_auth = true

auth.json:

{
  "OPENAI_API_KEY": "sk-your-api-key"
}

The tool intentionally avoids writing experimental_bearer_token into Codex TOML. The key belongs in auth.json.

review_model is optional. The tool does not create or change it unless you pass --review-model.

When updating an existing Codex config, the tool replaces only the targeted root keys and provider-table keys, preserving unrelated settings in the file.

To remove old inline Codex tokens from existing TOML, pass:

npx @haveagoodday1205/codexplus --target codex --clean-codex-inline-tokens

Hermes

config.yaml:

model:
  default: "gpt-5.5"
  provider: "codexplus"
  base_url: "https://codexplus.shop"
  api_mode: "codex_responses"
  api_key: "sk-your-api-key"

Other Hermes settings are preserved.

codex_responses is the default because it best matches Codex/OpenClaw. Use --hermes-api-mode chat_completions only as a compatibility fallback for endpoints whose Responses streaming format is not fully Hermes-compatible. The tool updates only the targeted keys inside the model: section and keeps other YAML settings intact.

Claude Code

settings.json:

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-your-api-key",
    "ANTHROPIC_BASE_URL": "https://codexplus.shop",
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "0",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  },
  "model": "claude-opus-4-6"
}

The tool writes Claude Code in the same shape as CC-Switch: provider env plus the selected top-level model. It also tries to preserve the existing JSON indentation and newline style.

Claude Desktop

Claude Desktop does not use the Claude Code settings.json format. The tool writes a direct gateway 3P profile, matching CC-Switch's Claude Desktop direct mode:

• macOS app root: ~/Library/Application Support/Claude/claude_desktop_config.json
• macOS 3P root: ~/Library/Application Support/Claude-3p/claude_desktop_config.json
• Windows app root: %LOCALAPPDATA%\Claude\claude_desktop_config.json
• Windows 3P root: %LOCALAPPDATA%\Claude-3p\claude_desktop_config.json
• Linux/Ubuntu: skipped for Claude Desktop; use Claude Code ~/.claude/settings.json

claude_desktop_config.json:

{
  "deploymentMode": "3p"
}

configLibrary/_meta.json:

{
  "appliedId": "00000000-0000-4000-8000-000000157210",
  "entries": [
    {
      "id": "00000000-0000-4000-8000-000000157210",
      "name": "CodexPlus",
      "provider": "gateway"
    }
  ]
}

configLibrary/00000000-0000-4000-8000-000000157210.json:

{
  "inferenceProvider": "gateway",
  "inferenceGatewayBaseUrl": "https://codexplus.shop",
  "inferenceGatewayApiKey": "sk-your-api-key",
  "inferenceGatewayAuthScheme": "bearer",
  "inferenceModels": [
    "claude-opus-4-6"
  ],
  "disableDeploymentModeChooser": true
}

This is direct gateway mode only. It does not start or require a local routing proxy. Restart Claude Desktop after writing so it reloads the 3P profile.

OpenClaw

openclaw.json provider section:

{
  "models": {
    "mode": "merge",
    "providers": {
      "codexplus": {
        "baseUrl": "https://codexplus.shop",
        "apiKey": "sk-your-api-key",
        "authHeader": true,
        "api": "openai-responses",
        "timeoutSeconds": 900,
        "models": [
          {
            "id": "gpt-5.5",
            "reasoning": true,
            "contextWindow": 1000000,
            "contextTokens": 900000
          }
        ]
      }
    }
  }
}

It also sets agents.defaults.model.primary to codexplus/<primary-model> and enables long cache retention for the configured models. It tries to preserve the existing JSON indentation and newline style while updating only the relevant provider and agent fields.

Safety

• If a target file already exists, the first write preserves an original copy at .bak-codexplus-original.
• Existing files are also backed up to .bak-codexplus-YYYYMMDD-HHMMSS before each changed write by default.
• Output redacts API keys unless --show-secrets is passed.
• Configure mode makes no network request.
• Verify mode calls the configured /v1/models endpoint.
• Use --dry-run to inspect planned changes first.

Verification

Basic verification:

npx @haveagoodday1205/codexplus verify --target codex
npx @haveagoodday1205/codexplus verify --target claude
npx @haveagoodday1205/codexplus verify --target claude-desktop
npx @haveagoodday1205/codexplus verify --target claude-group
npx @haveagoodday1205/codexplus verify --target codex-group
npx @haveagoodday1205/codexplus verify --target hermes
npx @haveagoodday1205/codexplus verify --target openclaw

Expected result:

• Config file exists.
• API key exists.
• Provider and base URL are present.
• /v1/models returns HTTP 200.
• Every returned /v1/models model id is printed under the model count.
• The configured model appears in the model list.

Note: /v1/models success does not guarantee full Responses streaming compatibility. --smoke is still the fastest end-to-end check for Hermes and OpenClaw.

Smoke verification:

npx @haveagoodday1205/codexplus verify --target codex --smoke
npx @haveagoodday1205/codexplus verify --target codex-group --smoke
npx @haveagoodday1205/codexplus verify --target hermes --smoke
npx @haveagoodday1205/codexplus verify --target openclaw --smoke

Smoke mode runs:

codex exec --color never -c model_reasoning_effort=low --dangerously-bypass-approvals-and-sandbox "Reply OK only."
hermes -z "Reply OK only."
openclaw agent --agent main --json --message "Reply OK only."

If a long-running gateway was already running, restart it after configuration so the updated files are reloaded:

hermes gateway restart
openclaw gateway restart

If you started either gateway manually in the foreground instead of as a service, stop that process and run it again:

hermes gateway run
openclaw gateway run

In an interactive terminal, codexplus now also asks whether it should run the gateway restart commands for you after writing changed Hermes/OpenClaw config.

Tests

npm test