Codex CLI

Configure Codex CLI to use BullSequana AI models through the Responses API.

Agentic Friendly

Codex CLI connects to BullSequana AI through the OpenAI Responses API on the BSQAI API. Codex runs its tools on your machine; the platform serves the model turns with a model your organization lets you use.

What to use

  • API type: OpenAI Responses API (wire_api = "responses")
  • base URL: https://api.<platform-domain>/v1
  • token: sk-bsq-... API key, read from an environment variable

Do not configure Codex against an internal model endpoint, such as KServe's.

1. Install Codex CLI

npm install -g @openai/codex
codex --version

2. Get a BSQAI API key

Create one under API Keys in the Portal's account menu. The full secret is shown only once.

Give the key chat.message.create to generate answers, and tenant.read to list models in step 4. If you belong to a group in the tenant, also choose the Team the key's usage counts for. It cannot be changed later, and that team's monthly BCU cap applies to the key. See Create and use an API key.

Export the key in the shell that runs Codex:

export BSQ_API_KEY="sk-bsq-v1-..."

3. Configure the provider

Create or edit ~/.codex/config.toml:

model = "<model-name-from-/v1/models>"
model_provider = "bsqai"
model_context_window = <context-window>

[model_providers.bsqai]
name = "BullSequana AI"
base_url = "https://api.<platform-domain>/v1"
env_key = "BSQ_API_KEY"
wire_api = "responses"
  • env_key names the variable Codex reads the key from, so the key is never written into the file. Codex sends it as Authorization: Bearer.
  • wire_api = "responses" makes Codex call /v1/responses.
  • model_context_window tells Codex the model's context window, which Codex does not read from the BSQAI API. Codex uses it to compact a long session before it reaches the model's limit. Use the model's context_length from /v1/models, or the value the deployment was started with.

The Portal generates this file with the model id, the base URL and the model's context window already filled in. Open the model in Studio → Available models, go to Use model, and pick Codex CLI under Use with a coding agent. See Studio — Use model.

4. Check model availability

The model value must be a name from the model list of your environment:

curl "https://api.<platform-domain>/v1/models" \
  -H "Authorization: Bearer $BSQ_API_KEY"

The list holds only the models you may use. Pick a model deployed with tool calling: Codex reads files and runs commands through tool calls, and a model without them can only answer. See A coding agent needs tool calling.

5. Run Codex

codex

Ask a short question that needs a tool, such as listing the files in the current directory, to check that the model calls tools.

Troubleshooting

SymptomCause and fix
401BSQ_API_KEY is not exported in the shell that runs Codex, or the key was deleted.
404 with model_not_foundThe model name is wrong, or no allow rule lets you use the model. Check the name against /v1/models, or ask for Can use on the model.
400 with reasoning_effort_unsupportedThe model rules out the reasoning effort Codex sent. Set model_reasoning_effort in config.toml to a value the model accepts.
429 with usage_cap_reachedYour monthly BCU cap, or the cap of the key's team, is reached. Waiting does not help; a tenant administrator can raise it. See What a refused call looks like.
The model answers but never runs a commandThe model was deployed without tool calling. Use another model, or redeploy it with tool calling enabled.

On this page