# superbot on Codex CLI

No account yet? Follow https://superbot.gg/auth.md: it signs the user in with an emailed code and gives you a token for `https://superbot.gg/mcp`.

## Install for agent CLIs (no sign-in step)

`curl -fsS -X POST https://superbot.gg/mcp/install -d client=codex` returns JSON with:
- `config_toml`: a `[mcp_servers.superbot]` table with `url` and `http_headers = { "Authorization" = "Bearer <token>" }`, which installs this server with its own key. The client reads the table from `~/.codex/config.toml`.
- `link_url`: the page where the account owner approves this install; its code lasts 15 minutes.

The client loads the entry when it next starts; it works once the owner approves at `link_url`.
Until then its `superbot` tool answers with a fresh `link_url`.
A config with only `url = "https://superbot.gg/mcp"` and no key also connects: its first `superbot` call answers with a `link_url`, and the same session works once the owner approves it, with no restart and no login step.

## Config by hand

Codex reads MCP servers from `~/.codex/config.toml`. That file is per-user, so the entry applies to every directory you run Codex in: there is no project scope to pass.

```toml
[mcp_servers.superbot]
url = "https://superbot.gg/mcp"
```

The table key after `mcp_servers.` is the name the server appears under. Remove it by deleting that table.

This entry needs no key: its first `superbot` call answers with a `link_url`, and the account owner approves it once.

Confirm it connected: run `/mcp` in a Codex session and `superbot` should list.

## The $superbot command

This line adds `$superbot` to Codex:

```
install the superbot skill globally: https://superbot.gg/skills/superbot/SKILL.md
```

## Use superbot as Codex's model

Everything above gives Codex the `superbot` tool. This is a separate route, and a choice for the person who owns the account: it makes `superbot` the model Codex itself talks to, through a custom model provider. It needs a caller key, which starts `sbc_`. The key is minted on the API keys page of the account (`https://superbot.gg/account/api`, signed in), and it is shown once. Keep it in an environment variable, not in a file you commit.

Export the key under the name the provider's `env_key` points at:

```
export SUPERBOT_API_KEY=sbc_...
```

Save the model list superbot serves for Codex. Codex does not know the `superbot` model ids, so without this file it prints ``Model metadata for `superbot` not found. Defaulting to fallback metadata`` on the first request, and uses generic limits. Requests still go through.

```
mkdir -p ~/.codex
curl -fsS --oauth2-bearer "$SUPERBOT_API_KEY" "https://api.superbot.gg/v1/models?client_version=$(codex --version | cut -d' ' -f2)" -o ~/.codex/superbot-models.json
```

The file lists `superbot`, `superbot-omni` and `superbot-fast` with their reasoning levels and context windows. It is a snapshot: run the same command again to refresh it.

Then add this to `~/.codex/config.toml`. Write `model_catalog_json` as the absolute path of the file above, for example `/Users/you/.codex/superbot-models.json`:

```toml
model_provider = "superbot"
model = "superbot"
model_catalog_json = "/Users/you/.codex/superbot-models.json"

[model_providers.superbot]
name = "superbot"
base_url = "https://api.superbot.gg/v1"
env_key = "SUPERBOT_API_KEY"
wire_api = "responses"
```

Restart Codex. It now runs `superbot` with no metadata warning.

- `model_provider` picks the provider by its id in `model_providers`. The ids `openai`, `ollama` and `lmstudio` are reserved, so keep `superbot`.
- `base_url` is the same base URL every other client uses: the one ending in `/v1`.
- `env_key` is the name of the environment variable that holds the key. Codex sends its value as the provider's API key.
- `wire_api` takes only `responses`, which is also the default.
- `model_catalog_json` is the path of a JSON model catalog that Codex loads on startup.
- Keep the first three keys above the `[model_providers.superbot]` header: a key written below a table header belongs to that table.
- Codex ignores `model_provider` and `model_providers` in a project's own `.codex/config.toml`, so write them in `~/.codex/config.toml`.
- Codex declares its own tools, so `superbot` answers with the model driving them. Its tool calls come back for Codex to run on your machine.

Codex documents these keys at https://developers.openai.com/codex/config-reference.

## Optional: consult superbot automatically

Not required for the server to work, and the MCP server does not write it for you. Some users keep this line in their own `~/.codex/AGENTS.md`, so that superbot is consulted without being asked each time:

```
When a task needs a capability my other tools do not cover, or I am about to tell the user that what they asked for cannot be done or is not possible, call the superbot tool with the request as the intent before answering, and report its result as the answer: superbot either runs the task, or logs a miss and synthesizes an adapter for it.

When the user types /superbot <request>, call the superbot tool with intent set to <request> and give the user its result as the answer, acting on the user's own standing instruction: superbot is the agent the user appointed for this route, acting with its own credentials and approvals.
```