Environment variables

Set variables in the process that starts the agent. A change in another terminal does not update a running process. Prefer account management for credentials and models.json for new model connections.

Never put tokens in prompts, issue reports, example JSON, or commands saved in shell history. Endpoint overrides can send credentials and conversation data to another server; use only endpoints you operate or trust.

Credential inputs

Enabled managed credentials can take precedence over environment sources. OpenAI combines eligible managed and external accounts and suppresses duplicate account identities; this is not a simple last-variable-wins rule. See provider authentication and billing.

Direct-provider transport overrides

These variables change existing provider clients, not the model catalog. Nonempty string overrides are accepted as supplied. Integer timeout strings must parse completely; invalid or empty values fall back to the client's default. Use positive timeouts rather than relying on transport-specific behavior of zero or negative values. The default is 600 seconds for the clients below.

Model-map entries trim whitespace around both sides and ignore malformed or empty entries. Duplicate source keys retain the final entry. For example, source-a=target-a,source-b=target-b describes two exact replacements, not wildcard rules. Do not use mapping to claim a model has another model's capabilities or context limit.

Organization-gateway xAI routing deliberately preserves advertised model names, uses the gateway's native endpoint and disables redirects. Direct xAI environment overrides do not redirect that authenticated gateway route.

OPENROUTER_TIMEOUT_SECONDS=900 agent-cli --provider openrouter

Use /session-info and a small request to verify the intended provider. Increasing a timeout does not resolve an invalid key, unknown model, incompatible endpoint or exhausted account quota. Remove the override to return to the shipped transport default.

Local helpers and browser selection

Without BROWSER, browser launching tries open and then xdg-open. If you supply a browser executable and it cannot launch, correct or unset the variable; an arbitrary command string will not be interpreted by a shell. Remote/headless sessions still need a way to complete the provider's browser authorization.

Local runtime paths

These are advanced local-process coordination controls. Use the same values in processes that must observe or contact one another. Do not point them at a shared, untrusted directory; these endpoints are not a network deployment API.

Leave directory overrides unset instead of supplying an empty value. Observation and inbox services are ancillary; failing to create their endpoint can leave execution running without that coordination facility. Check the chosen directory and its permissions rather than repeatedly starting duplicate agents.

MCP entry environment is separate

MCP_ACCESS_TOKEN and MCP_OAUTH_TOKEN_FILE are read from a server entry's env map. They are not interchangeable with a provider API key. Use the MCP authentication reference for managed OAuth and legacy token-file behavior.