codexplus

Offline npx helper for configuring Codex, Hermes, and OpenClaw to use an OpenAI-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
• Hermes: ~/.hermes/config.yaml
• OpenClaw: ~/.openclaw/openclaw.json

Windows paths are resolved from %USERPROFILE% unless an explicit path is passed.

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-sub2api.example

Interactive setup:

npx @haveagoodday1205/codexplus

The interactive setup asks for the target client, base URL, model, API key, and The interactive setup asks only for the target client and API key. It uses the default base URL and model, then automatically runs verification plus one real client smoke test after writing.

Configure one client:

npx @haveagoodday1205/codexplus --target codex
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. --smoke also launches the actual client commands and asks each client to reply to a short prompt.

PowerShell:

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

Options

--target <name>             codex, hermes, openclaw, or all. Default: codex.
--key <key>                 API key. Can also use SUB2API_API_KEY or OPENAI_API_KEY.
--base-url <url>            OpenAI-compatible base URL. Default: https://codexplus.shop.
--model <id>                Primary model. Default: gpt-5.4.
--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: OpenAI.
--hermes-provider <name>    Hermes provider name. Default: custom.
--openclaw-provider <name>  OpenClaw provider id. Default: sub2api-remote.
--codex-home <dir>          Codex home directory. Default: CODEX_HOME or ~/.codex.
--config <file>             Codex config.toml path.
--auth <file>               Codex auth.json path.
--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-sub2api-* 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.

For the interactive setup, defaults can be overridden with environment variables:

CODEXPLUS_BASE_URL=https://your-endpoint.example CODEXPLUS_MODEL=gpt-5.5 npx @haveagoodday1205/codexplus

What It Writes

Codex

config.toml:

model_provider = "OpenAI"
model = "gpt-5.4"
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.OpenAI]
name = "OpenAI"
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.

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.4"
  provider: "custom"
  base_url: "https://codexplus.shop"
  api_mode: "codex_responses"
  api_key: "sk-your-api-key"

Other Hermes settings are preserved.

OpenClaw

openclaw.json provider section:

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

It also sets agents.defaults.model.primary to sub2api-remote/<primary-model> and enables long cache retention for the configured models.

Safety

• Existing files are backed up to .bak-sub2api-YYYYMMDD-HHMMSS 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 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.
• The configured model appears in the model list.

Smoke verification:

npx @haveagoodday1205/codexplus verify --target codex --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."

Tests

npm test