Codex

Codex CLI connects to MAG through a model provider in its configuration file.

warning

Codex usage with frontier models can be expensive. Frontier models cost more per token. A high reasoning effort uses more tokens. Usage counts against the allocation of your project.

To reduce cost, use a smaller model for routine tasks, set a lower reasoning effort, and keep the compaction limit low. Check your spend on the MAG Dashboard.

1. Configure Codex

Make sure the environment variable AMSC_TOKEN contains your PAT, as shown in Step 4.

Add the following to the file ~/.codex/config.toml:

model = "gpt-6-luna"
model_reasoning_effort = "high"
model_context_window = 272000
model_auto_compact_token_limit = 200000
model_provider = "mag"

[model_providers.mag]
name = "AmSC MAG"
base_url = "https://mag.genesis.americansciencecloud.org/v1"
env_key = "AMSC_TOKEN"
wire_api = "responses"
supports_websockets = false
http_headers = { "X-AmSC-MAG-Provider" = "openai" }  # or "microsoft"

The setting model_auto_compact_token_limit sets the point at which Codex compacts the conversation. A lower value reduces cost. The setting model_reasoning_effort sets the reasoning effort.

The value of env_key is the name of the environment variable. It is not the PAT. Do not write the PAT in this file.

The header X-AmSC-MAG-Provider selects the provider that serves the model. Codex uses the Responses API. Codex is confirmed to work with both the openai and microsoft providers. Set the header value to one of them:

Value	Provider
openai	OpenAI
microsoft	Microsoft Azure

2. Start Codex

Start Codex in your project directory:

cd my-project
codex

note

Codex runs a background server process that keeps the environment from when it first started. If you set or changed AMSC_TOKEN after that, Codex fails with the error "AMSC_TOKEN" environment variable not found. Terminate the process, then start Codex again:

pkill -f "codex app-server"

The shell function method does not need this restart.

Use a shell function

To use MAG without a configuration file, put the settings in a shell function. Add this to ~/.zshrc or ~/.bashrc:

codex-amsc() {
  command codex \
    -c 'model_provider="amsc"' \
    -c 'model_providers.amsc.name="AmSC MAG"' \
    -c 'model_providers.amsc.base_url="https://mag.genesis.americansciencecloud.org/v1"' \
    -c 'model_providers.amsc.env_key="AMSC_TOKEN"' \
    -c 'model_providers.amsc.wire_api="responses"' \
    -c 'model_providers.amsc.http_headers={ "X-AmSC-MAG-Provider" = "openai" }' \
    "$@"
}

To use Microsoft Azure, change the header line to:

    -c 'model_providers.amsc.http_headers={ "X-AmSC-MAG-Provider" = "microsoft" }' \

Start Codex with codex-amsc. Add options as usual, for example codex-amsc --model gpt-6-luna.

3. Select a model

The setting model in the configuration file sets the default model. To use a different model for one session, use the --model option:

codex --model gpt-6.1-sol

For more information, see the OpenAI Codex CLI repository.