BYOK · 自帶 LLM Key

BYOK（Bring Your Own Key）是 Braidrun 對待 LLM Token 賬單的核心理念：你在 OpenAI / Anthropic / DeepSeek / Kimi / OpenRouter 等家拿到的 API Key 自己保管，Braidrun 幫你代調不加價。

為什麼 BYOK

• 賬單透明 — Token 消耗直接記在你自己的 LLM 賬戶裡，Braidrun 不中轉、不加價。
• 模型自由 — 你可以用自己賬號的 Claude Opus、GPT-5、任何 OpenRouter 路由的小模型 —— 不受平臺統一套餐限制。
• 額度與限流由你掌握 — 需要更高 TPM？去 OpenAI 升 Tier 即可。不需要跟平臺打交道。
• 安全可控 — Key 隨時可在 OpenAI 控制檯 revoke，整個鏈路你說了算。

支援的 Provider

• OpenAI — GPT-4.1 / 4.1-mini / GPT-5 / o1 / o3
• Anthropic — Claude Opus 4 / Sonnet 4 / Haiku 4
• Claude Code — Anthropic API Key 或 Claude 訂閱 Token（憑證 provider=claude_code_oauth）
• Codex — OpenAI API Key 或 Codex 訂閱 auth.json（憑證 provider=codex_subscription）
• DeepSeek — DeepSeek-V3.5 / DeepSeek-Reasoning
• Kimi — Kimi K2 / 128K context
• OpenRouter — 通過 OpenRouter 路由到任何其支持的模型（Mistral / Llama / Gemini 等）
• 內部 LLM（企業版可接入 self-hosted vLLM / TGI / Ollama endpoint）

第一步：去 Provider 拿 Key

第二步：存到憑據中心

1. 左側「憑據管理」→「新建憑據」。
2. 命名建議：
   • openai_main / openai_prod / openai_test
   • anthropic_team_budget / anthropic_personal
   • deepseek_production
3. 類型：api_key；值：粘貼 Provider 給你的 key；命名空間：個人 or 團隊（看你是單人用還是多人共享）。
4. 保存。平臺加密落庫。

第三步：Agent 裡綁 provider

agents:
  writer:
    preset: writer
    overrides:
      model: claude-opus-4-7
      provider: anthropic_team_budget    # ← 凭据中心的凭据名

AI 助手：配置當前賬號

站內 AI 助手不再依賴管理員統一配置。進入「帳號設定 → AI 助手」，選擇模型 provider，或在 Claude Code / Codex 區域選擇 API Key / 訂閱額度模式。儲存後只影響目前帳號。

第四步（可選）：配置 Provider 細節

某些 Provider 需要更多配置 —— api_base、organization id、custom headers。在「憑據管理 → Provider 配置」裡展開：

# 凭据中心 → Provider 配置
# 类型: OpenAI
api_base: https://api.openai.com/v1   # 或你的代理 / Azure endpoint
organization: org_xxxxx                 # 分账 organization
default_headers:
  OpenAI-Beta: assistants=v2

多 Key 分賬

場景：你想按部門記賬，或有開發 / 生產兩套 Key。

1. 在憑據中心每個 Key 起獨立名字（openai_marketing / openai_engineering）。
2. 不同工作流的 Agent 綁不同 provider。
3. 在 OpenAI 側分 project 追 token 消耗，每個 project 的賬單自然分開。

成本追蹤

即使賬單在 Provider 側，Braidrun 仍然追蹤 token 與按模型現價換算的預估成本：

• 每次 execution 頂部摘要顯示 tokens + 估算 cost
• 「數據看板」頁按日 / 周 / 月聚合
• 可以設"單次 execution cost 超 X 時報警"

注意 Braidrun 的估算是基於公開的 Provider 價目表 —— 如果你享受折扣（OpenAI Enterprise / DeepSeek 季度合同），真實賬單會低於估算。

限流與重試

你的 Key 有 TPM（Tokens Per Minute）上限。平臺做了三層保護：

1. Provider 限流（Provider 側硬性，超過會 429）
2. Braidrun 內部 TPM 軟限制（避免一次性打爆）
3. step 級 retry.backoff（transient 429 自動退避重試）

Key 輪換

1. 在 Provider 側創建一把新 Key（不 revoke 舊的）。
2. Braidrun 憑據中心 → 找到對應憑據 → 「更新值」粘貼新 Key。
3. 等 1 小時（讓正在跑的 execution 用舊 Key 跑完）。
4. 確認一切正常，到 Provider 側 revoke 舊 Key。

故障切換 / Fallback

Provider 偶發抖動時，可以在 Agent 裡配 fallback：

agents:
  writer:
    preset: writer
    overrides:
      model: claude-opus-4-7
      provider: anthropic_main
      fallback:
        model: gpt-4.1
        provider: openai_main

主 Provider 返回 5xx / rate limit 時自動切 fallback。

常見問題

Braidrun 能看到我的 Key 值嗎？

執行時間平台服務需要用明文 Key 調 Provider —— 這個瞬間是技術上可見的。但：

• 落庫時 AES-256-GCM 加密，DB dump 裡看不到明文；
• 運行時解密只在單個 step 的 context 生效，不進日誌、不寫快照、不流出到其它 step；
• Enterprise 版支持 HSM / KMS 集成，密鑰解密在託管 KMS 裡做。

能不能混用平臺額度 + BYOK？

可以。Agent 沒配 provider 時走平臺統一 Key（吃平臺額度）；配了 provider 就走你的 Key。在同一條工作流裡不同 step 可以混。

下一步

• 憑據管理 — 憑據中心更多細節
• Agent 配置詳解 — 哪些 overrides 字段跟 provider 配合用