Use Codex CLI and Codex App with OceanBase MaaS

This topic describes how to use Codex CLI and Codex App through the OceanBase MaaS gateway.

Configuration instructions

Codex is a coding agent developed by OpenAI and supports the following two forms:

• Codex CLI: An open-source command-line tool that can read, modify, and run code in a local terminal.
• Codex App: A ready-to-use graphical desktop application.

Codex CLI and Codex App share the ~/.codex/config.toml configuration file and related environment variables. You only need to configure them once for use with both the CLI and App.

After connecting through the OceanBase MaaS gateway, you can use GPT, Codex, and other model families without directly accessing the official OpenAI API.

Install Codex

npm install -g @openai/codex

Configuration steps

Obtain MaaS API Key

Apply for an API key in the OceanBase MaaS console or through your internal process. The API key typically follows the format sk_xxxx. Store the API key securely and never commit it to a code repository. For specific procedures, see Manage AI API Keys.

Configure shell environment variables (Recommended)

Add the API key to your shell configuration file so that Codex can read it automatically each time it starts.

1. Identify the shell you are using.

echo "$SHELL"

• If the output is /bin/zsh, open ~/.zshrc in an editor, such as by running nano ~/.zshrc or vim ~/.zshrc.
• If the output is /bin/bash, open ~/.bashrc in an editor, such as by running nano ~/.bashrc or vim ~/.bashrc.

2. Open the shell configuration file. The following example uses zsh. Append the following content to the end of the file.

# ============= OceanBase MaaS + Codex Configuration ============
export MAAS_API_KEY="sk_xxxx"   # Replace with your MaaS API Key

3. Apply the configuration.

   source ~/.zshrc   # zsh
   # Or
   source ~/.bashrc  # bash
   

Configure Codex

Edit the Codex configuration file to specify the MaaS gateway as the model provider.

1. If the ~/.codex directory does not exist, create it first.

mkdir -p ~/.codex

2. Use an editor to create or open ~/.codex/config.toml, such as by running nano ~/.codex/config.toml or vim ~/.codex/config.toml, and add the following content.

model_provider = "maas"
model = "gpt-5.3-codex"

[model_providers.maas]
name = "OceanBase MaaS"
base_url = "https://ai-api-g.oceanbase.com/api/v1"
env_key = "MAAS_API_KEY"
wire_api = "responses"

The following table describes the configuration fields.

Start Codex

source ~/.zshrc   # zsh
# Or
source ~/.bashrc  # bash

cd /path/to/your/project
codex

Supported models

To switch models, modify the model field in config.toml. No other configuration changes are required.

GPT and Codex model families (Native model names recommended)

For GPT and Codex models, we recommend using native model names, such as gpt-5.3-codex, so that Codex can correctly identify the model and enable reasoning capabilities and other dedicated features.

# Recommended: Native alias, full features
model = "gpt-5.3-codex"

# Not recommended: A complete ID with a vendor prefix may cause silent feature degradation.
model = "openai/gpt-5.3-codex"

The following table lists the GPT and Codex models currently supported by the MaaS gateway. The actual response from the /api/v1/models endpoint shall prevail.

Verify connection

After completing the configuration, verify the environment variables, gateway connectivity, and model invocation in sequence.

Check environment variables

Confirm that the API key has been added to the shell configuration file and loaded into the current terminal environment.

echo $MAAS_API_KEY

Test gateway connectivity

Send a request to the MaaS gateway to verify network connectivity and the validity of the API key.

curl -s https://ai-api-g.oceanbase.com/api/v1/models \
  -H "Authorization: Bearer $MAAS_API_KEY" | head -c 500

Test Responses API

Send a minimal Responses API request to verify the complete model invocation path.

curl -s https://ai-api-g.oceanbase.com/api/v1/responses \
  -H "Authorization: Bearer $MAAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.3-codex",
    "input": "say ok",
    "max_output_tokens": 16
  }'

If the gateway returns HTTP 200 and the response contains output text, the configuration is correct.

Troubleshooting

API Key invalid or authentication failed

1. Run echo $MAAS_API_KEY to confirm that MAAS_API_KEY is set.

2. Confirm that the API key begins with sk_ and does not contain extra spaces or newline characters.

3. Confirm that the API key is enabled in the MaaS console.

4. Reload the configuration based on your current shell.

source ~/.zshrc   # zsh
# Or
source ~/.bashrc  # bash

Connection failure

1. Check whether your network can access ai-api-g.oceanbase.com.
2. Confirm that base_url in config.toml is set to https://ai-api-g.oceanbase.com/api/v1. The URL must include /api/v1.
3. Check whether a firewall or proxy is blocking outbound connections.

Environment variables not taking effect

1. Open a new terminal, or run source ~/.zshrc / source ~/.bashrc.
2. Run echo "$SHELL" and confirm that the API key was added to the configuration file for your current shell.

Configuration file not taking effect

1. Confirm that the configuration file path is ~/.codex/config.toml.
2. Run cat ~/.codex/config.toml to view the configuration file.
3. If the directory does not exist, run mkdir -p ~/.codex first.
4. Restart Codex App after modifying the configuration.

Model unavailable

1. Call /api/v1/models endpoint and confirm that the response contains the target model.
2. Confirm that the value of the model field exactly matches the id in the model list.
3. For GPT and Codex models, use native model names whenever possible, such as gpt-5.3-codex.
4. max_output_tokens in a Responses API request must be greater than or equal to 16.