HopBase DocsCodex App
Point OpenAI's Codex desktop app at HopBase to use GPT models.
Codex App is OpenAI's Codex desktop app. It reads the same user config as Codex CLI, ~/.codex/config.toml. Set up that config and a key, reopen the app, and it runs on HopBase.
| Item | Value |
|---|---|
| Config files | ~/.codex/config.toml and ~/.codex/auth.json |
| Base URL | https://api.hop-base.com/v1 |
| Protocol | wire_api = "responses" |
| Key | A key from the Codex Plus or Codex Pro group |
Recommended: one-click setup or CC Switch
Both write config.toml and auth.json for you, and Codex App picks them up as is.
Write the config
On the console's API Keys page, find a Codex group key and pick one route: click One-click setup, choose Codex CLI, and run the command in a terminal; or follow the CC Switch guide, click Import CCS, and also choose Codex CLI.
Quit Codex App completely and reopen it
Quit the whole app, then open it again; on macOS press Cmd+Q. Closing only the window does not make the app reload its config.
Start a task to verify
Start a new task and ask for a one-word reply. When it succeeds, the request shows up in the console's Usage page.
Manual setup
Codex App starts from the desktop, so it may not see environment variables set in your terminal. For manual setup, store the key in auth.json instead of using env_key.
| System | Config directory |
|---|---|
| macOS / Linux | ~/.codex/ |
| Windows | C:\Users\<your-username>\.codex\ |
Create the files if they do not exist.
config.toml:
model_provider = "hopbase"
model = "gpt-6-astra"
model_reasoning_effort = "high"
[model_providers.hopbase]
name = "HopBase"
base_url = "https://api.hop-base.com/v1"
wire_api = "responses"
requires_openai_auth = trueauth.json:
{
"OPENAI_API_KEY": "sk-your-key"
}Use either requires_openai_auth = true with auth.json, or env_key with an environment variable. With both in one config, Codex 0.153 was observed sending no key, and the gateway returns 401 missing_api_key.
Switch models
Edit model and model_reasoning_effort in config.toml, quit and reopen Codex App, then start a new task. Existing tasks may keep the model they were created with.
For the model IDs and reasoning levels in the Codex groups, see Codex CLI. The list returned by GET /v1/models for your key is authoritative.
More details
- Codex App and Codex CLI edit the same file. A model or provider change made in one applies to the other after a restart.
- Codex App also writes its own settings into
config.toml. One-click setup rewrites the whole file and first backs up the original asconfig.toml.bak.<timestamp>.
Web search calls /v1/alpha/search and remote context compaction calls /v1/responses/compact. Neither endpoint is supported yet, so both return 404. Regular chat and code edits are not affected.
- The app still uses the ChatGPT account: check that
model_providerpoints tohopbase, then quit and reopen the app. - 401: check the key in
auth.jsonand make sure it belongs to a Codex group. For other errors, see Troubleshooting.
Next steps
- Codex CLI: use the same config in a terminal
- CC Switch: switch between several keys
- Troubleshooting: look up an error by its message