# Codex CLI

# Codex CLI

[Codex CLI](https://developers.openai.com/codex) talks to models over the
**OpenAI Responses API**. Hyphen serves it at `/v1/responses`, so Codex works
against any Hyphen model with one provider block.

## 1. Get a key

[app.hyphen-solution.com](https://app.hyphen-solution.com) → sign in →
**Dashboard → API Keys → Create**. Copy the `sk-hy-...` key.

## 2. Configure — one copy-paste block

Add this to **`~/.codex/config.toml`** (create it if it doesn't exist):

```toml
# ~/.codex/config.toml

model = "m3"
model_provider = "hyphen"

[model_providers.hyphen]
name = "Hyphen"
base_url = "https://api.hyphen-solution.com/v1"
env_key = "HYPHEN_API_KEY"
wire_api = "responses"
```

Then provide the key in the environment variable Codex reads (`env_key`):

```bash
export HYPHEN_API_KEY="sk-hy-YOUR_KEY"
```

That's it. Run Codex from a shell that has `HYPHEN_API_KEY` set.

## The Responses ⇄ Chat bridge

Codex only POSTs to `/responses` — since **February 2026, `wire_api =
"responses"` is the only value it supports**. But most upstream models speak
**Chat Completions**, not Responses. The Hyphen gateway sits in the middle and
**translates Responses ⇄ Chat Completions** for you:

```
Codex ──(Responses API)──▶  Hyphen gateway ──(translates)──▶  upstream model
```

That translation is the whole point: Codex gets the Responses shape it requires,
even for upstreams that never implemented it. You don't configure anything for
this — it's automatic.

Key fields in the block above:

- `base_url` — the OpenAI-compatible root, **ending in `/v1`** (no trailing
  slash). Codex appends `/responses`.
- `env_key` — the environment variable Codex reads your key from at runtime.
  Never hard-code the key in TOML.
- `wire_api = "responses"` — required (the only supported value since Feb 2026).
- `model` / `model_provider` — select the Hyphen provider and `m3` (strongest)
  by default.

## 3. Verify

```bash
codex "Reply with the single word: connected"
```

If Codex replies `connected`, you're wired to the gateway. Override the model
per-invocation when you want something cheaper:

```bash
codex -m m2.5 "quick one-off edit"
```

## Troubleshooting

- **Auth errors** — confirm `HYPHEN_API_KEY` is set in the shell you launched
  Codex from (`echo $HYPHEN_API_KEY`).
- **404 / wrong path** — `base_url` must end in `/v1`, with no trailing slash.
- **`429`** — monthly budget spent; see [Rate limits & caps](/rate-limits).
- **Config keys moved?** Codex's provider schema has shifted across releases.
  Confirm the current shape for your version at
  [developers.openai.com/codex/config-reference](https://developers.openai.com/codex/config-reference)
  or with `codex --help`.