Skip to content

Environment variables

The module reads the variables below, and only under the conditions given. Everything else in chat.Config is set in code, because the module owns no config system. A host maps its own configuration into chat.Config and passes it in.

The variables

Variable Constant Read when Effect
AI_PROVIDER chat.EnvAIProvider Config.Provider is empty names the provider; an unregistered name is then fatal with unsupported provider: <name>
ANTHROPIC_API_KEY chatanthropic.EnvClaudeKey Config.Token and Config.Credentials resolved nothing, on ProviderClaude supplies the API key
OPENAI_API_KEY chatopenai.EnvOpenAIKey Config.Token and Config.Credentials resolved nothing, on ProviderOpenAI supplies the API key
GEMINI_API_KEY chatgemini.EnvGeminiKey Config.Token and Config.Credentials resolved nothing, on ProviderGemini supplies the API key

Two providers authenticate by something other than an API key, so they read a different set. Neither takes a Config.Token, and supplying one is an error rather than an alternative.

Variable Read when Effect
GOOGLE_CLOUD_PROJECT Config.Project is empty, on ProviderGeminiVertex names the GCP project
GOOGLE_CLOUD_LOCATION Config.Location is empty, on ProviderGeminiVertex names the region
GOOGLE_GENAI_USE_VERTEXAI always, on ProviderGemini refuses construction. The SDK reads it and would switch backend silently, so a client configured for the Gemini API fails rather than being moved somewhere it cannot report
AWS_REGION, AWS_DEFAULT_REGION Config.Location is empty, on ProviderBedrock names the region, through the standard AWS chain
the AWS credential chain always, on ProviderBedrock supplies credentials: environment, profile, instance role, SSO, or a web identity token. chat-bedrock resolves it through awsclient rather than reading any of these directly
none ProviderAzureOpenAI reads no environment variable at all, including OPENAI_API_KEY. Everything comes from Config, or from a credential passed to chatopenaiazure.WithTokenCredential. See below

Azure reads nothing from the environment, and that is worth stating because the SDK underneath would. openai-go falls back to OPENAI_API_KEY by default; the Azure request options disable that fallback, so an OpenAI key exported in the shell cannot reach an Azure deployment. It would also be refused if it did, because the SDK will not send an Authorization header alongside an Azure credential.

For ambient Azure credential discovery, resolve it yourself with azureclient and pass the result to WithTokenCredential. chat-openai-azure takes a credential rather than resolving one, so it depends on azcore and not on azidentity.

Plus any variable you name: Config.Credentials.Env holds the name of an environment variable to read the key from, which is how a host keeps the secret out of its config file while keeping the reference in it.

Where each sits in the credential cascade

This applies to the API-key providers. The three well-known key variables are the last step, not the first. In order, the first non-empty source wins:

  1. Config.Token
  2. the variable named by Config.Credentials.Env
  3. the keychain reference in Config.Credentials.Keychain
  4. the literal in Config.Credentials.Key
  5. the provider's well-known variable from the table above

Every value is whitespace-trimmed and an empty result falls through, so a variable that exists but is blank cannot mask a working source below it.

ProviderGeminiVertex and ProviderBedrock do not use this cascade at all. They authenticate through their cloud's own credential chain, which is a resolution order rather than a value, and neither accepts a Config.Token.

Why AI_PROVIDER has no prefix

AI_PROVIDER is deliberately unprefixed and deliberately narrow. It is an ecosystem-wide default (the same variable across tools built on this module) and it is consulted only when Config.Provider is empty, so it can never override a provider a caller actually set. There is no AI_MODEL, AI_BASE_URL or CHAT_* equivalent: everything else is host configuration, and inventing a parallel environment schema here would fight whatever the host already has.

Variables used only when running this module's own tests

Variable Effect
INT_TEST=1 runs every integration test
INT_TEST_CHAT=1 runs the integration tests tagged chat

Integration tests are gated by environment variable rather than build tag, so they stay compiled and discoverable in an IDE. Without one of these set they skip.