Model providers

OpenWiki supports the following providers:

Credentials and defaults are stored in ~/.openwiki/.env. Process environment values take priority over file values.

You can set the active provider and model with:

OPENWIKI_PROVIDER=openai
OPENWIKI_MODEL_ID=gpt-5.6-terra

Provider retries

Override retries after the first provider request:

OPENWIKI_PROVIDER_RETRY_ATTEMPTS=3

The value must be a positive integer. If unset, OpenWiki defaults to 3 retries, or 5 when OPENWIKI_PAGE_CONCURRENCY is above 1.

Output token limits

OPENWIKI_MAX_OUTPUT_TOKENS is an optional override for the per-request output budget. When set, it must be a positive integer. OpenWiki maps it to the active provider's request shape:

• maxOutputTokens: gemini
• maxTokens: anthropic, openai, openai-compatible, openrouter, bedrock, Gemini Enterprise non-Google surfaces, openai-chatgpt, and copilot

When unset, OpenWiki preserves each provider's SDK default except for these built-in ceilings:

• Anthropic: modern Claude 4 and 5 models default to 16384 tokens because older LangChain metadata otherwise caps newer Claude aliases at 4096
• Bedrock: defaults to 16000 tokens. Override with OPENWIKI_BEDROCK_MAX_TOKENS when a model supports a lower ceiling

To set one limit across whichever of those providers is active, set:

OPENWIKI_MAX_OUTPUT_TOKENS=16384

By default OpenRouter sends no max_tokens, so credit pre-checks budget for the model's full advertised output ceiling and low balances can fail with 402 errors. OPENWIKI_OPENROUTER_MAX_TOKENS takes precedence over OPENWIKI_MAX_OUTPUT_TOKENS on OpenRouter runs, you can set token limits with:

OPENWIKI_OPENROUTER_MAX_TOKENS=8192

Using a limit means that instead of 402 failures, you get possible truncation on long generations, so prefer the largest value your balance allows.

Reasoning effort

OPENWIKI_REASONING_EFFORT is an optional global setting for models that advertise reasoning support.

OPENWIKI_REASONING_EFFORT=high

Leave it unset to preserve the provider default. Invalid provider, model, or effort combinations fail before a request is sent. An inherited value also fails when the active provider and model do not support it.

All other provider and model combinations, including OpenRouter, do not offer reasoning effort selection.

For openai-compatible, reasoning effort stays off until you opt in:

OPENWIKI_OPENAI_COMPATIBLE_REASONING_EFFORT_SUPPORTED=true

When that flag is set, OpenWiki maps OPENWIKI_REASONING_EFFORT through the Responses API if OPENWIKI_OPENAI_COMPATIBLE_USE_RESPONSES_API=true, and through Chat Completions reasoning_effort otherwise.

In interactive chat, use /effort to choose an available value or /effort default to restore the provider default.

IBM Bob

IBM Bob is an API-key provider with a fixed model ID of premium, so OpenWiki skips the model picker:

OPENWIKI_PROVIDER=bob
BOB_API_KEY=your-bob-api-key

Optional BOB_BASE_URL overrides the default inference endpoint (https://api.us-east.bob.ibm.com/inference/v1). Streaming is always on for this provider.

To run OpenWiki inside IBM Bob / Bob Shell instead of configuring Bob as the standalone provider, see Coding-agent integrations.

GitHub Copilot

To use GitHub Copilot:

1. Select GitHub Copilot during openwiki --init. If you have an active GitHub CLI session, OpenWiki can reuse it. Otherwise, run gh auth login from the credential prompt.
2. Choose a model (for example gpt-5.5).

OpenWiki leaves the GitHub CLI token in the GitHub CLI credential store. It does not copy that token into ~/.openwiki/.env. For CI or headless environments without a GitHub CLI session, set COPILOT_API_KEY to a GitHub OAuth token. Personal Access Tokens (classic or fine-grained) are rejected by the Copilot API for third-party integrations.

OPENWIKI_PROVIDER=copilot
OPENWIKI_MODEL_ID=gpt-5.5

Microsoft Entra auth

OpenWiki supports Microsoft Entra ID (formerly Azure Active Directory) as a token provider for OpenAI-compatible endpoints that require Entra bearer tokens instead of static API keys.

To configure Entra auth interactively, run openwiki --init, select OpenAI-compatible, then select Microsoft Entra ID. Enter the HTTPS API root, the token scope your gateway accepts, and the model ID. OpenWiki saves these settings for later --update runs. It does not ask for or store an access token.

For non-interactive runs, set the same values as environment variables:

OPENWIKI_PROVIDER=openai-compatible
OPENAI_COMPATIBLE_AUTH=entra-id
OPENAI_COMPATIBLE_BASE_URL=https://gateway.example.com/openai/v1
OPENAI_COMPATIBLE_ENTRA_SCOPE=api://gateway-application-id/.default
OPENWIKI_MODEL_ID=your-gateway-model

• OPENAI_COMPATIBLE_AUTH: Set to entra-id to enable Entra auth. The default is api-key. In Entra mode, OPENAI_COMPATIBLE_API_KEY is not required.
• OPENAI_COMPATIBLE_BASE_URL: Must use HTTPS and cannot contain embedded credentials.
• OPENAI_COMPATIBLE_ENTRA_SCOPE: Optional. Defaults to https://cognitiveservices.azure.com/.default, the Azure OpenAI scope. Custom gateways may require a different scope.

OpenWiki obtains tokens through Azure Identity, which caches them and refreshes them before expiry. Configure an Azure Identity credential separately in each environment that runs OpenWiki:

• Workload identity federation: Set AZURE_CLIENT_ID, AZURE_TENANT_ID, and AZURE_FEDERATED_TOKEN_FILE. When AZURE_FEDERATED_TOKEN_FILE is set, OpenWiki uses WorkloadIdentityCredential. Point the file variable at the runner-provided token file. Do not commit the file.
• Other environments: OpenWiki uses DefaultAzureCredential, which accepts credentials such as az login, a managed identity, or environment credentials.

Generated CI workflows keep the auth mode and scope, but you still need to configure an unattended Azure Identity credential in CI.

OpenAI (ChatGPT login)

The openai-chatgpt provider calls OpenAI's Codex backend using your ChatGPT subscription instead of a metered API key:

OPENWIKI_PROVIDER=openai-chatgpt openwiki code --init

The wizard opens the OpenAI auth page in your browser (and prints the URL for headless use). After sign-in, OpenWiki stores managed OAuth tokens in ~/.openwiki/.env and refreshes the access token automatically. Treat the refresh token like a password.

Gemini Enterprise Agent Platform

The gemini-enterprise provider uses Google Application Default Credentials. No API key is required:

OPENWIKI_PROVIDER=gemini-enterprise
GOOGLE_CLOUD_PROJECT=your-gcp-project
GOOGLE_CLOUD_LOCATION=global

The credentials need Gemini Enterprise Agent Platform access (roles/aiplatform.user), and the models you use must be enabled in Model Garden. Partner/open-weight (MaaS) models are region-specific, so set GOOGLE_CLOUD_LOCATION explicitly when using them.

AWS Bedrock

OPENWIKI_PROVIDER=bedrock
BEDROCK_AWS_ACCESS_KEY_ID=your-access-key-id
BEDROCK_AWS_SECRET_ACCESS_KEY=your-secret-access-key
BEDROCK_AWS_REGION=us-east-1
OPENWIKI_MODEL_ID=anthropic.claude-sonnet-5

When explicit Bedrock credentials are not set, OpenWiki uses the AWS SDK default credential provider chain. Paste the Bedrock model ID directly. Some newer models require a cross-region inference profile ID (for example us.anthropic.claude-sonnet-5) instead of the bare model ID.

Bedrock defaults to a 16000-token output ceiling when neither OPENWIKI_MAX_OUTPUT_TOKENS nor OPENWIKI_BEDROCK_MAX_TOKENS is set. Without an explicit limit, the Converse API caps output at 4096 tokens and can truncate long wiki pages.

For Bedrock stream idle timeout, set OPENWIKI_STREAM_IDLE_TIMEOUT in milliseconds (an integer from 0 to 2147483647). Set 0 to disable the watchdog. If unset, OpenWiki preserves the @langchain/aws provider default.

OpenAI-compatible endpoints

Use the openai-compatible provider for gateways or local servers that expose OpenAI-compatible chat completions:

OPENWIKI_PROVIDER=openai-compatible
OPENAI_COMPATIBLE_API_KEY=your-gateway-key
OPENAI_COMPATIBLE_BASE_URL=https://your-gateway.example.com/v1
OPENWIKI_MODEL_ID=your-gateway-model-name

Local examples such as Ollama (http://localhost:11434/v1) and LM Studio (http://localhost:1234/v1) use the same pattern. OpenWiki still requires OPENAI_COMPATIBLE_API_KEY even when the local server ignores the key value.

OpenWiki sends non-streaming requests internally, even when you are not watching live output in the terminal. Some gateways accept only streaming requests, where the model returns output in chunks over an open connection. When OpenWiki hits one of those gateways with a non-streaming request, the gateway may reject the call or return HTTP 200 with empty content. A blank wiki with no error usually means you need to enable streaming.

Enable streaming for the openai-compatible provider when your gateway requires it:

OPENWIKI_OPENAI_COMPATIBLE_STREAMING=true

Streaming stays off by default because this provider can point at arbitrary third-party endpoints, where streaming is not guaranteed to work through proxies and load balancers. Enabling it also makes the client report estimated rather than server-reported token counts.

To opt the openai-compatible provider into the Responses API instead of chat completions:

OPENWIKI_OPENAI_COMPATIBLE_USE_RESPONSES_API=true

OpenRouter provider pinning

When OpenRouter serves a model through multiple upstream providers, restrict routing:

OPENWIKI_PROVIDER=openrouter
OPENROUTER_API_KEY=your-key
OPENWIKI_OPENROUTER_PROVIDER_ONLY=Novita

See also

• Quickstart
• CLI reference
• Customize OpenWiki