---
name: codex-cli-fastrouter
description: "Install and configure FastRouter (https://fastrouter.ai) as a custom OpenAI-compatible model provider in OpenAI Codex CLI. Use this skill whenever the user asks to add, set up, install, configure, or register fastrouter as a provider in codex, edit ~/.codex/config.toml, export FASTROUTER_API_KEY, or wants to use FastRouter models with Codex CLI. The skill takes exactly one input: the FastRouter API key."
version: 1.0.0
author: FastRouter
license: MIT
metadata:
  codex:
    tags:
      [
        fastrouter,
        codex,
        provider,
        setup,
        configuration,
        custom-provider,
        openai-compatible,
      ]
    homepage: https://fastrouter.ai
    docs: https://docs.fastrouter.ai
---

# FastRouter Setup for Codex CLI

Configures **fastrouter** as a custom OpenAI-compatible model provider in
OpenAI Codex CLI. After setup, FastRouter models are invoked by setting
`model_provider = "fastrouter"` and `model = "<slug>"` in
`~/.codex/config.toml`, with auth flowing through the
`FASTROUTER_API_KEY` env var.

## Inputs

This skill accepts **exactly one input**: the FastRouter API key.

Everything else is hardcoded and must not be changed:

| Field         | Value                                |
| ------------- | ------------------------------------ |
| Provider key  | `fastrouter`                         |
| Base URL      | `https://api.fastrouter.ai/api/v1`   |
| Wire API      | `responses` (OpenAI Responses API)   |
| Env var       | `FASTROUTER_API_KEY`                 |
| Config file   | `~/.codex/config.toml`               |

## When to Use This Skill

Trigger this skill when the user asks any of:

- "install fastrouter for codex"
- "install fastrouter in codex with key <KEY>"
- "set up / configure / register fastrouter in codex"
- "add fastrouter as a provider in codex"
- "edit `~/.codex/config.toml` for fastrouter"
- "use fastrouter with codex cli"
- "point codex at fastrouter"

Anything similar referencing **codex** plus install / setup / configure /
add / register / provider plus **fastrouter** should trigger it.

## Extracting the API Key (single-argument rule)

Treat every invocation as a single-argument call: `setup(api_key)`.

Find the key in the user's message using these rules, in order:

1. If the message contains `key=<value>`, `--key <value>`,
   `--api-key <value>`, or `apiKey=<value>`, the value is the key.
2. Else, the **last whitespace-separated token in the message that looks
   like an API key** is the key. A token "looks like an API key" if it
   matches `^sk-v1-[A-Za-z0-9_\-]+$` (FastRouter keys always have the
   prefix `sk-v1-` followed by a random string of
   letters/digits/dashes/underscores).
3. Else, ask the user **once**: _"Please paste your FastRouter API key
   (just the key, nothing else)."_ Then treat their next message as the
   key verbatim, after stripping surrounding whitespace and quotes.

Examples of correct extraction:

| User message                                          | Extracted key     |
| ----------------------------------------------------- | ----------------- |
| `install fastrouter for codex with key sk-v1-abc123`  | `sk-v1-abc123`    |
| `setup codex with fastrouter sk-v1-abc123`            | `sk-v1-abc123`    |
| `configure codex --api-key sk-v1-XYZ789`              | `sk-v1-XYZ789`    |
| `add fastrouter to codex key=sk-v1-9aBc...`           | `sk-v1-9aBc...`   |
| `set up codex with fastrouter`                        | (prompt the user) |

Once extracted, **never modify, paraphrase, or transform the key**. Do
not strip characters you think are formatting. Do not lowercase. Do not
echo the full key back to the user - only ever show it masked
(`****` + last 4 chars) in confirmations.

## Redaction Check (do this before writing)

Some agent harnesses (Cursor, IDE extensions, CI loggers) may redact
secrets in messages before the model sees them. After extracting the
key, validate it. The key is **invalid for write** if any of:

- Equals `[REDACTED]`, `<redacted>`, `***`, `***REDACTED***`, or any
  string containing the substring `REDACTED` (case-insensitive)
- Does not start with the literal prefix `sk-v1-` (all real FastRouter
  keys begin with `sk-v1-`; anything else is either redacted, mistyped,
  or from a different provider)
- Has nothing after the `sk-v1-` prefix (i.e. the random portion is
  empty)
- Contains only `*` or `•` characters
- Is empty / whitespace-only

If the key fails validation due to redaction, **stop and tell the user**:

> "It looks like your environment is masking the API key before I can
> read it. To install fastrouter for Codex CLI, please run these in your
> terminal directly so the key never passes through the model:
>
> ```bash
> mkdir -p ~/.codex
> cat >> ~/.codex/config.toml <<'EOF'
> model_provider = "fastrouter"
> model = "openai/gpt-5.5"
>
> [model_providers.fastrouter]
> name = "fastrouter"
> base_url = "https://api.fastrouter.ai/api/v1"
> env_key = "FASTROUTER_API_KEY"
> wire_api = "responses"
> EOF
>
> export FASTROUTER_API_KEY="<YOUR_KEY>"
> echo 'export FASTROUTER_API_KEY="<YOUR_KEY>"' >> ~/.zshrc   # or ~/.bashrc
> ```

Do **not** proceed with a redacted-looking value - writing `[REDACTED]`
as the API key silently breaks the provider with 401 errors that look
unrelated to redaction.

## Procedure

Once you have a valid key, follow these steps in order.

### Step 1 - Ensure Codex CLI is installed

Run via the `terminal` tool:

```
codex --version
```

If `codex` is not found, install it first:

```
npm install -g @openai/codex
codex --version
```

### Step 2 - Ensure `~/.codex/config.toml` exists

```
mkdir -p ~/.codex
touch ~/.codex/config.toml
```

### Step 3 - Write the provider config

Codex stores configuration in TOML. Merge the following into
`~/.codex/config.toml`. **Preserve existing keys** outside this block;
do not clobber the file. If a top-level key already exists, update its
value rather than duplicating.

Top-level keys (overwrite if present):

```toml
model_provider = "fastrouter"
model_reasoning_effort = "high"
model = "openai/gpt-5.5"
```

Provider table (must exist exactly as shown):

```toml
[model_providers.fastrouter]
name = "fastrouter"
base_url = "https://api.fastrouter.ai/api/v1"
env_key = "FASTROUTER_API_KEY"
wire_api = "responses"
```

The API key is **never** written to the TOML file. It always flows
through the `FASTROUTER_API_KEY` env var, controlled by the
`env_key = "FASTROUTER_API_KEY"` line above.

### Step 4 - Export the API key

Run via the `terminal` tool, using the extracted key **exactly as-is**:

```
export FASTROUTER_API_KEY="<USER_KEY>"
```

For persistence across shells, append the same line to the user's shell
rc file:

```
echo 'export FASTROUTER_API_KEY="<USER_KEY>"' >> ~/.zshrc   # or ~/.bashrc
```

If unsure which shell rc to use, run `echo $SHELL` and pick the matching
file.

### Step 5 - Verify

```
grep -A 4 '\[model_providers.fastrouter\]' ~/.codex/config.toml
[ -n "$FASTROUTER_API_KEY" ] && echo "FASTROUTER_API_KEY is set" || echo "FASTROUTER_API_KEY is NOT set"
```

Expected: all four fields (`name`, `base_url`, `env_key`, `wire_api`)
appear under `[model_providers.fastrouter]`, and the env var prints
`set`. **Never echo the actual value** of `FASTROUTER_API_KEY`.

### Step 6 - Report success

Reply to the user with usage examples. Show the API key **only masked**.

> ✓ FastRouter is configured for Codex CLI (`****<last 4 chars>`).
>
> Start Codex from any project:
>
> ```
> cd /path/to/your/project
> codex
> ```
>
> Switch models by editing `model = "..."` in `~/.codex/config.toml`.
> Browse available slugs at https://fastrouter.ai/models.

### Step 7 - Optional model wiring

If (and only if) the user named a specific model in their request, set
it as `model` instead of the default `openai/gpt-5.5`:

```toml
model = "<that_model>"
```

Otherwise leave `model = "openai/gpt-5.5"` and `model_reasoning_effort
= "high"` untouched.

## Pitfalls

- **Don't write the API key into `~/.codex/config.toml`.** Codex reads
  keys only from env vars, controlled by `env_key =
"FASTROUTER_API_KEY"`. Storing the key in the TOML does nothing useful
  and risks committing it to git if the user version-controls dotfiles.
- **`model_provider` must match the table key exactly.**
  `model_provider = "fastrouter"` requires `[model_providers.fastrouter]`
  (same string). A mismatch produces `provider 'fastrouter' not found`.
- **`wire_api` must be `"responses"`, not `"chat"`.** FastRouter speaks
  the OpenAI Responses API. Setting `wire_api = "chat"` causes
  wire-format errors mid-stream.
- **Env var must be exported in the same shell that runs `codex`.** If
  the user starts `codex` from a fresh terminal, the var is gone unless
  persisted in `~/.zshrc` / `~/.bashrc`.
- **Config changes require restarting `codex`.** If the user is in an
  active Codex session, the new provider only becomes available after
  quitting and restarting.
- **Redacted keys silently corrupt config.** Always run the redaction
  check before writing. Writing `[REDACTED]` (or pasting a masked key
  into `export`) produces 401 errors later that look unrelated to
  redaction.
- **Never echo the full key back.** Only show it masked (last 4 chars).
  Some platforms log assistant output verbatim.

## Verification Checklist

Before reporting success, confirm:

- [ ] Exactly one key was extracted (Inputs rule)
- [ ] The key passed the redaction check (starts with `sk-v1-`, no
      `REDACTED` substring)
- [ ] `~/.codex/config.toml` exists and contains all four required
      fields under `[model_providers.fastrouter]`
- [ ] Top-level `model_provider = "fastrouter"` is set
- [ ] `FASTROUTER_API_KEY` is exported in the current shell (and
      persisted in shell rc if the user requested)
- [ ] You did NOT echo the raw API key - only masked form

## References

- Codex CLI: https://github.com/openai/codex
- FastRouter dashboard: https://dashboard.fastrouter.ai/
- FastRouter API base: `https://api.fastrouter.ai/api/v1`
- FastRouter models: https://fastrouter.ai/models
- FastRouter docs: https://docs.fastrouter.ai