Skip to main content
Codex CLI is OpenAI’s terminal coding agent. It talks to the OpenAI Responses API, and NEAR AI Cloud serves a stateless Responses API at the same base URL as its other endpoints, so you can add NEAR AI Cloud to Codex as a custom model provider. Through NEAR AI Cloud, Codex can use open models such as z-ai/glm-5.3-flash and OpenAI models such as openai/gpt-5.4. See Available Models for each model’s privacy tier. If you normally sign in to Codex with a ChatGPT account, you can keep doing that. The setup below adds NEAR AI Cloud as a separate profile, so plain codex keeps using your ChatGPT sign-in and codex --profile nearai uses NEAR AI Cloud.

Prerequisites

  • Codex CLI installed (checked with 0.167.0).
  • A NEAR AI Cloud account with credits.
  • A NEAR AI Cloud API key. In the NEAR AI Cloud Dashboard, open API Keys and create a key.

1. Store your API key

Codex reads the key from an environment variable. Add this line to your shell profile (~/.zshrc, ~/.bashrc, or similar) so every new terminal has it:
Open a new terminal, or run source ~/.zshrc, before starting Codex.
Do not paste the key into a Codex config file or commit it to a repository. Keep it in the environment variable.

2. Add a NEAR AI Cloud profile

Create ~/.codex/nearai.config.toml with:
~/.codex/nearai.config.toml
Codex loads ~/.codex/config.toml first and then applies ~/.codex/<name>.config.toml when you pass --profile <name>.

3. Start Codex

The session header shows provider: nearai and the model you set. For a one-off command:
To try another model without editing the file, pass -m:

Use NEAR AI Cloud by default

If you want plain codex to use NEAR AI Cloud, put the same lines in ~/.codex/config.toml instead of the profile file. To go back to your ChatGPT sign-in, remove model_provider and model from that file.

Choose a model

List the models your key can use:
Codex needs tool calling, so pick a model whose supported_features in /v1/models include tools. See Model Discovery and Refresh for more on reading model metadata. Codex ships metadata only for the models it currently knows. For other model IDs, such as z-ai/glm-5.3-flash or openai/gpt-5.4, it prints a Model metadata ... not found warning and uses default limits. To make Codex compact the conversation at the right point, add model_context_window near the top of the file, above the [model_providers.nearai] table, using context_length from /v1/models:
~/.codex/nearai.config.toml
Codex includes a web search tool in its requests by default. For open models such as z-ai/glm-5.3-flash, NEAR AI Cloud runs the search and bills it per request on top of token usage. For openai/ models, OpenAI runs the search. To turn off web search, add this near the top of the profile file:
~/.codex/nearai.config.toml

Quick test

If Codex fails, test the key and model directly against the Responses API first:
A successful response contains near-ai-ok in its output and confirms that your key works with this model. If Codex still fails, check its error against the troubleshooting table below.

Troubleshooting

Sources Checked

Sources checked on 2026-11-16, against Codex CLI 0.167.0. A Codex session that writes a file and runs a shell command was run against NEAR AI Cloud with z-ai/glm-5.3-flash and openai/gpt-5.4.