Documentation v0.4.0
Home GitHub

Configuration

Configure provider credentials, model routing names, compatibility endpoints, OAuth providers, and test-server environment variables.

router.Config

router.New accepts a router.Config. The router reads Name to pick a factory, then passes the provider-specific fields to it.

Field Required Used by Description
Name Yes All providers Routing key in provider@model form
APIKey Conditional API-key providers Provider API key
Token Conditional copilot, codex, grok-oauth OAuth token object
BaseURL Conditional compat Base URL of an OpenAI-compatible endpoint
AccountID Conditional cloudflare Cloudflare account identifier
GatewayID Conditional cloudflare Cloudflare AI Gateway identifier

The provider-level core.Config carries the same credential fields plus Model, the model portion after routing, and the capability hints Thinking, Efforts, and Endpoints.

Routing names

Format Meaning Example
<provider>@<model> Standard router key openai@gpt-5.4
<provider>[<tag>]@<model> The bracket tag is ignored while selecting the provider claude[eu]@claude-opus-4-8
compat@<model> Custom OpenAI-compatible endpoint; also requires BaseURL compat@my-local-model 
router.Config{Name: "openai@gpt-5.4", APIKey: apiKey}
router.Config{Name: "gemini@gemini-2.5-pro", APIKey: apiKey}
router.Config{Name: "claude@claude-opus-5", APIKey: apiKey}

For compat, the model is the text after @ and BaseURL is passed to the OpenAI-compatible client:

agent, err := router.New(router.Config{
    Name:    "compat@my-local-model",
    APIKey:  "optional-key",
    BaseURL: "http://127.0.0.1:8080/v1",
})

Provider keys

Key Credential / special fields Package
claude APIKey core/claude
openai APIKey core/openai
gemini APIKey core/gemini
grok APIKey core/grok
deepseek APIKey core/deepseek
nvidia APIKey core/nvidia
openrouter APIKey core/openRouter
cloudflare APIKey, AccountID, GatewayID core/cloudflare
compat APIKey, BaseURL core/compat
copilot Token core/copilot
codex Token core/openaiCodex
grok-oauth Token core/grokOauth

Unknown keys return an error from router.New.

API keys and OAuth tokens

API-key providers receive APIKey directly in router.Config. OAuth providers receive the matching token type:

Tokens are stored as JSON in the operating-system keychain rather than in repository configuration files:

Package Keychain key Operations
core/oauth/copilot COPILOT_OAUTH_TOKEN LoginWithCallback, Load, HasToken, ClearToken, EnsureFreshSession
core/oauth/codex CODEX_OAUTH_TOKEN LoginWithCallback, Load, HasToken, ClearToken, EnsureFresh
core/oauth/grok GROK_OAUTH_TOKEN LoginWithCallback, Load, HasToken, ClearToken, EnsureFresh

Load returns nil, nil when no token is stored. EnsureFresh treats a token as expired within a 60-second safety buffer, then refreshes and writes the replacement back to the keychain.

token, err := oauthCopilot.Load()
if err != nil {
    return err
}
if token == nil {
    token, err = oauthCopilot.LoginWithCallback(ctx, func(code *oauthCopilot.DeviceCode) {
        fmt.Println(code.VerificationURI, code.UserCode)
    })
    if err != nil {
        return err
    }
}

agent, err := router.New(router.Config{
    Name:  "copilot@gpt-5",
    Token: token,
})

Test-server environment variables

cmd/test resolves credentials from environment variables on every request.

Provider prefix Required environment variables
claude ANTHROPIC_API_KEY
openai OPENAI_API_KEY
gemini GEMINI_API_KEY
grok XAI_API_KEY
deepseek DEEPSEEK_API_KEY
nvidia NVIDIA_API_KEY
openrouter OPENROUTER_API_KEY
cloudflare CLOUDFLARE_API_KEY, CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_GATEWAY_ID
compat COMPAT_API_KEY, COMPAT_BASE_URL
copilot COPILOT_TOKEN

COPILOT_TOKEN accepts a raw access token or the JSON produced by the Copilot OAuth flow. The test server does not wire the codex and grok-oauth routes. PORT overrides the default 8787.

Request fields

Body of POST /v1/chat/completions:

Field Type Description
model string provider@model routing key; required
messages array core.Message values
tools array Optional core.Tool definitions
reasoning string none, low, medium, high, xhigh, max, or the aliases minimal, extra, ultra
mode string default or fast
stream bool Returns SSE when true

An unparsable reasoning or mode value returns HTTP 400; omitting either uses the default.

Model capability helpers

core exposes the capability checks used by adapters:

Function Purpose
SupportFast(provider, model) Whether the pair has a fast tier
SupportTemperature(provider, model) Whether the model accepts temperature
ResponsesAPI(provider, model) Whether the OpenAI Responses path is selected
OpenAIEffortRange(model) Reasoning bounds for OpenAI-family models
IsTextModel(id) Whether the model is text-only

Client timeout

core.NewHTTPClient creates the default HTTP client with a ten-minute timeout. OAuth helper clients use the same long timeout plus a shorter response-header timeout.

中文