Codex CLI
Configure Codex CLI to use BullSequana AI models through the Responses API.
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 --version2. 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_keynames the variable Codex reads the key from, so the key is never written into the file. Codex sends it asAuthorization: Bearer.wire_api = "responses"makes Codex call/v1/responses.model_context_windowtells 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'scontext_lengthfrom/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
codexAsk a short question that needs a tool, such as listing the files in the current directory, to check that the model calls tools.
Troubleshooting
| Symptom | Cause and fix |
|---|---|
401 | BSQ_API_KEY is not exported in the shell that runs Codex, or the key was deleted. |
404 with model_not_found | The 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_unsupported | The 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_reached | Your 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 command | The model was deployed without tool calling. Use another model, or redeploy it with tool calling enabled. |