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 配合用