設定

設定供應商憑證、模型路由名稱、相容 endpoint、OAuth 供應商與測試伺服器環境變數。

`router.Config`

router.New 接受 router.Config。router 先讀 Name 選出工廠，再把供應商專屬欄位傳入。

欄位	是否必要	使用者	說明
`Name`	是	所有供應商	`provider@model` 形式的路由鍵
`APIKey`	條件式	API key 供應商	供應商 API key
`Token`	條件式	`copilot`、`codex`、`grok-oauth`	OAuth token 物件
`BaseURL`	條件式	`compat`	OpenAI 相容 endpoint 的 base URL
`AccountID`	條件式	`cloudflare`	Cloudflare 帳戶識別碼
`GatewayID`	條件式	`cloudflare`	Cloudflare AI Gateway 識別碼

供應商層的 core.Config 含相同憑證欄位，另加路由解析後的 Model，以及 Cloudflare 專用的能力提示欄位 Thinking、Efforts、Endpoints。

路由名稱

格式	意義	範例
`<provider>@<model>`	標準路由鍵	`openai@gpt-5.4`
`<provider>[<tag>]@<model>`	選擇供應商時忽略方括號標籤	`claude[eu]@claude-opus-4-8`
`compat@<model>`	自訂 OpenAI 相容 endpoint，另需 `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}

compat 的模型名取 @ 之後的字串，BaseURL 傳給 OpenAI 相容 client：

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

供應商鍵值

鍵值	憑證／特殊欄位	套件
`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`

未知鍵值由 router.New 回傳錯誤。

API key 與 OAuth token

API key 供應商直接在 router.Config 帶 APIKey；OAuth 供應商帶對應的 token 型別：

copilot 使用 *core.CopilotToken
codex 使用 *core.CodexToken
grok-oauth 使用 *core.GrokToken

Token 以 JSON 形式存在作業系統 keychain，不寫進儲存庫設定檔：

套件	Keychain 鍵值	提供的操作
`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 在沒有既存 token 時回傳 nil, nil。EnsureFresh 以 60 秒安全緩衝判斷過期，必要時換發並寫回 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,
})

測試伺服器環境變數

cmd/test 每次請求都從環境變數取憑證。

供應商前綴	必要環境變數
`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 接受原始 access token，或 Copilot OAuth 流程產生的 JSON。測試伺服器未接上 codex 與 grok-oauth 路由。PORT 覆寫預設的 8787。

請求欄位

POST /v1/chat/completions 的請求主體：

欄位	型別	說明
`model`	string	`provider@model` 路由鍵，必填
`messages`	array	`core.Message` 陣列
`tools`	array	可選的 `core.Tool` 定義
`reasoning`	string	`none`、`low`、`medium`、`high`、`xhigh`、`max`，或別名 `minimal`、`extra`、`ultra`
`mode`	string	`default` 或 `fast`
`stream`	bool	`true` 時回傳 SSE

reasoning 或 mode 給出無法解析的值時，伺服器回 400；留空則採預設值。

模型能力輔助函式

core 提供適配器共用的能力判斷：

函式	用途
`SupportFast(provider, model)`	該組合是否有加速層
`SupportTemperature(provider, model)`	該模型是否接受 temperature
`ResponsesAPI(provider, model)`	是否走 OpenAI Responses API 路徑
`OpenAIEffortRange(model)`	OpenAI 系列模型的推理上下限
`IsTextModel(id)`	是否為純文字模型

Client timeout

core.NewHTTPClient 建立預設 HTTP client，逾時十分鐘。OAuth 輔助 client 使用同樣的長逾時，並額外設定較短的 response header 逾時。

設定

router.Config