Skip to content
RunAPI Developer Docs
EN 中文
Developer Resources
Developer Resources

Codex App

Use RunAPI as the model provider in Codex App, choose a Responses-compatible model, and verify the connection.

View Markdown

Overview

Codex is available in the ChatGPT desktop app for Windows and macOS. This guide points the local Codex App at RunAPI’s OpenAI-compatible Responses endpoint, selects a RunAPI model, and verifies the connection.

This changes the model provider used to generate responses and code. It does not add RunAPI tools. Hosted MCP is a separate integration with its own client and authentication requirements.

Before you begin

  • Install the current ChatGPT desktop app, sign in, and open Codex at least once.
  • Create a dedicated standard RunAPI API key by following the Authentication Guide. Do not commit the key to a repository.
  • From the Model Catalog, copy the exact identifier of a model that supports the Responses API.

These steps configure local Codex clients that read your user-level configuration. They do not configure hosted Codex cloud tasks.

Save the API key

Desktop apps may not inherit environment variables from your shell. Create or edit ~/.codex/.env and add the key on its own line:

DOTENV 
export RUNAPI_API_KEY=YOUR_RUNAPI_API_KEY

Keep this file outside your repositories. On macOS and Linux, restrict it to your user account:

SHELL 
chmod 600 ~/.codex/.env

Configure RunAPI

Open the user-level ~/.codex/config.toml. Merge the following values into the existing file; do not replace unrelated settings or add a second copy of an existing top-level key:

TOML 
model = "YOUR_RUNAPI_MODEL_ID"
model_provider = "runapi"

[model_providers.runapi]
name = "RunAPI"
base_url = "https://runapi.ai/v1"
env_key = "RUNAPI_API_KEY"
wire_api = "responses"

Provider and authentication settings must be user-level. Codex ignores model_provider and model_providers in a project’s .codex/config.toml. The TOML stores only the environment variable name; the API key remains in ~/.codex/.env.

The base_url is the API root, not an operation URL. With wire_api = "responses", Codex sends POST /v1/responses. See OpenAI’s custom model provider configuration for the provider contract.

Choose a model

Replace YOUR_RUNAPI_MODEL_ID with the exact identifier copied from the Model Catalog. Select a model that exposes the Responses API; support for Chat Completions alone is not sufficient for this configuration.

When you change model, completely restart the app and start a new task. An existing task may retain the model and provider with which it started.

Restart and verify

  1. Completely quit and reopen the ChatGPT desktop app.
  2. Open Codex and start a new task in a repository.
  3. Send a short prompt such as Describe this repository in one sentence.
  4. Confirm that Codex returns a normal response and that RunAPI records a POST /v1/responses request for the selected model.

The first verification should stay short so configuration errors are easy to separate from task-specific behavior.

Add RunAPI tools

The model provider above routes Codex inference through RunAPI. MCP is separate: it can let supported clients call RunAPI tools for model discovery, account information, and supported task workflows.

The Hosted MCP guide documents the currently supported client and authentication requirements. Codex-specific Hosted MCP authentication has not been verified, so this page does not provide Codex MCP setup steps. Do not replace the model-provider configuration with an MCP server entry; the two integrations serve different purposes.

Troubleshoot

  • Codex still uses the previous provider: confirm the file is ~/.codex/config.toml, remove duplicate model or model_provider keys, completely restart the app, and start a new task.
  • RUNAPI_API_KEY is missing: confirm the key is in ~/.codex/.env, not only in a terminal profile, then restart the app.
  • Authentication fails: create or rotate a standard key through the Authentication Guide. Do not paste the key into config.toml or support logs.
  • The request returns 404: set base_url to https://runapi.ai/v1, not https://runapi.ai/v1/responses.
  • The model is unavailable or rejects a field: copy the exact identifier again and confirm that the model supports the Responses API and the requested capability.
  • Codex selects a different model: check trusted project .codex/config.toml files for a model override. Project config can select a model even though it cannot replace the user-level provider.
  • The CLI works but the app fails: check ~/.codex/.env, then fully restart the app. GUI applications may not read variables exported only by your shell.
  • A cloud task does not use RunAPI: this local configuration applies to local Codex clients; hosted cloud tasks do not read files from your computer.

Remove RunAPI

  1. Remove the RunAPI model, model_provider, and [model_providers.runapi] values from ~/.codex/config.toml, or restore the provider values you used previously.
  2. Remove RUNAPI_API_KEY from ~/.codex/.env if no other local tool uses it.
  3. Completely restart the app and start a new task.
  4. Revoke the dedicated key in RunAPI when it is no longer needed.

Next steps

Use the LLM API Quickstart for shared protocol behavior and the Responses API Reference for exact request and response fields. Continue with the Model Catalog, Authentication Guide, or Hosted MCP as needed.