byok-custom-model

🔑 BYOK — 自定义 LLM 模型

将自定义 LLM 端点注册到模型选择器中。绕过平台代理——用户提供自己的 API 密钥，代理直接访问供应商/聚合器（OpenRouter、DashScope、Anthropic 原生、NEAR AI Cloud TEE、自托管等）。

这是一个脚本模式技能——未注册任何工具。阅读此文件，然后从 bash 块中调用导出函数。

另请参阅

• config/context/references/model-onboarding.md — 更广泛的模型选择 / OAuth 上下文
• chatgpt-codex-onboarding 技能 — 用于 ChatGPT/Codex OAuth（不同机制，非 BYOK）

---

精选供应商（始终优先检查）

该技能内置了 12 个预配置的供应商。在询问任何 URL、模型名称或 API 示例之前，始终将用户的意图与此列表匹配——base_url、通信协议、思考能力等均已预填，因此匹配精选供应商可直接使用 add_template(vendor=...)。

供应商 ID	用户提及以下内容时使用
anthropic	Claude, Anthropic
openai	GPT-4o, GPT-5, OpenAI 直接
xai	Grok, xAI
qwen	Qwen, 通义千问, DashScope
deepseek	DeepSeek
kimi	Kimi, Moonshot
mimo	MiMo, 小米
gemini	Gemini
gemma	Gemma
near-ai	隐私、TEE、机密推理、“不要记录我的数据”、Web3 原生
venice	Venice（仅当用户明确提及时；请参阅下面的隐私优先层级）
meta	Meta, Meta AI, Muse, Muse Spark, Muse Spark 1.1

---

引导流程——优先使用模板

1. 检查上面的精选供应商表格。 如果用户的意图匹配其中一个，直接使用 add_template(vendor=...) 并跳转到步骤 5。不要询问 URL。
2. 仅当没有匹配的精选供应商时：要求用户粘贴其文档中的官方 API 示例（curl / requests / fetch 示例）。告诉他们不要包含真实的 API 密钥——占位符或假密钥即可。
3. 运行 parse_example 自动检测 base_url、upstream_model、通信协议（openai 与 anthropic）、思考参数以及供应商特定的请求字段。
4. 与用户一起审查草稿，然后调用 add(...)——条目将写入 custom_models.yaml。
5. 如果结果包含 need_env_input，立即调用 request_env_input 工具，传入该负载中的 env_vars 和 reason。这将弹出安全输入 UI；用户输入密钥；密钥将保存在 workspace/.env 中。此步骤是强制性的——脚本本身无法弹出 UI。

隐私优先层级： near-ai 和 venice 都针对隐私敏感用户，但 NEAR AI 集成更简洁——Venice 的 TEE 方案本身构建在 NEAR AI + Phala 之上，因此直接使用 NEAR AI 可获得更短的信任链（Intel + NVIDIA 芯片 + NEAR 的可复现飞地镜像；中间没有产品层代理）。精选的 NEAR 模型列表仅限开放权重的 TEE 保护模型——NEAR 的目录也代理 Claude / GPT-5 / Gemini Pro 的“匿名化但非 TEE 保护”模式，我们有意排除这些，因为这里的隐私价值主张完全在于硬件飞地。

只要涉及 NEAR AI，始终推荐 TEE 保护（隐私）模型——这正是用户选择 NEAR 而非 OpenAI/Anthropic 直接的原因。精选列表已经是仅 TEE 模型，因此 add_template(vendor='near-ai') 的默认设置是安全的。如果用户要求注册 NEAR 上的非 TEE 模型（例如 NEAR 的匿名化 Claude 透传），请警告这会削弱隐私保证，并建议他们要么使用精选的 TEE 模型，要么直接注册上游供应商。

NEAR AI 推理协议： NEAR 使用嵌套在 extra_body 下的 chat_template_kwargs，而不是其他供应商使用的顶层 reasoning_effort/thinking/enable_thinking。提供者通过 nearai_chat_template thinking_capability 规则自动处理此问题。每个模型的参数名称不同（GLM/Qwen3.5/Qwen3.6 使用 enable_thinking，DeepSeek-V3 使用 thinking，gpt-oss 始终开启）。完整规范：docs.near.ai/cloud/reasoning-models。默认模型 Qwen/Qwen3.6-35B-A3B-FP8 开箱即用；Qwen3.5-122B-A10B 附带 thinking_mode='disabled'，因为其隐藏思考模式会导致基线调用出现 finish=length, content=null。

---

脚本用法

python3 - <<'EOF'
import sys, json
sys.path.insert(0, "/data/workspace/skills/byok-custom-model")
from exports import (
    templates, list_models, get, parse_example,
    list_vendor_models, add, add_template, remove,
)

# 枚举 12 个精选供应商预设
print(json.dumps(templates(), indent=2))

# 一键注册精选供应商（Meta / Muse Spark 1.1）
result = add_template(vendor="meta")
print(json.dumps(result, indent=2))
EOF

---

函数

函数	必需参数	用途
templates()	—	列出 12 个精选供应商预设
list_vendor_models(vendor)	vendor	实时 /models 目录（仅当模板具有 model_discovery 时）
add_template(vendor, *, upstream_model=None, name=None)	vendor	一键注册精选供应商（推荐路径）
parse_example(api_example)	api_example	将文档 API 示例解析为安全草稿（非精选供应商）
add(upstream_model, base_url, ...)	upstream_model, base_url	使用自定义参数注册（在 parse_example 之后使用）
list_models()	—	显示所有已注册的自定义条目
get(model_id)	model_id	检查一个条目
remove(model_id)	model_id	删除一个条目

所有函数返回一个字典，成功时返回 ok: True，失败时返回 ok: False, error: "..."。

处理 need_env_input（强制两步模式）

当 API 密钥环境变量尚未设置时，add() 和 add_template() 可能会在其结果中包含 need_env_input 字段。脚本无法自行弹出安全输入 UI——它无法访问用户的开放 SSE 流。调用代理必须执行此操作：

# 在 add_template / add 返回后：
if result.get("need_env_input"):
    nei = result["need_env_input"]
    # 调用进程内工具——伪代码，实际签名在工具侧：
    request_env_input(env_vars=nei["env_vars"], reason=nei["reason"])

弹出窗口、.env 写入以及特定渠道的 UX（Web 弹窗 / TG 卡片 / 微信文本提示）均由 request_env_input 处理。不要要求用户在聊天中粘贴密钥作为后备方案——只需调用工具。

---

注册后

• 模型在选择器中以 custom/ 前缀显示。
• 用户通过 /model custom/<name>（例如 /model custom/qwen-plus-e3f4）或模型选择器 UI 切换。
• 后续调用绕过平台代理——供应商定价直接应用于用户的 BYOK 配额。

---

关键规则

• 绝不允许在聊天中粘贴 API 密钥。 如果用户粘贴了密钥，忽略它，拒绝注册，并告知安全弹窗是唯一的安全渠道。
• 如果用户未响应，不要自动重新弹出安全输入 UI——等待。
• 如果返回了 need_env_input，始终调用 request_env_input。 不要跳过，不要要求用户粘贴密钥，不要重试 add_template 希望它会弹出 UI——它不会。
• 不要手动写入 workspace/config/custom_models.yaml 或 workspace/.env。 始终通过上述导出函数操作。
• 12 个精选供应商始终使用 add_template。仅对自托管或稀有供应商使用 parse_example + add。

---

Meta 模型 API — Muse Spark 1.1（预览版）

meta 模板用于 Meta 模型 API，该 API 目前处于公开预览阶段，位于开发者门户 **https://dev.meta.ai/**。

• 在 https://dev.meta.ai/ 申请/登录——同一门户用于注册和申请“Muse”/“Meta 模型 API”访问权限。用户必须在那里完成 Meta 的申请/登录流程才能获得 API 密钥。
• 访问权限可能取决于区域/账户，因为 API 处于公开预览阶段——并非每个开发者账户都能立即获得访问权限。如果 add_template(vendor='meta') 从实时 /v1/models 探测返回非 2xx 状态，不要假设用户错了；告知他们预览访问权限可能仍在等待其账户/区域，并让他们在 dev.meta.ai 仪表板中确认状态。
• 代理必须使用 request_env_input 获取密钥——与所有其他精选供应商完全相同。绝不允许在聊天中粘贴 Meta API 密钥。 如果用户粘贴了密钥，忽略它并拒绝注册；安全输入弹窗是唯一的安全渠道。
• 直接 Meta 计费和配额适用。 调用由 Meta 根据用户自己的 Meta 账户计费——Starchild 平台积分被绕过，无加价，无平台侧配额。将来自 api.meta.ai/v1 的任何速率限制 / 429 视为 Meta 侧信号，而非 Starchild 信号。

一键注册：

python3 -c "from exports import add_template; print(add_template(vendor='meta'))"

默认模型：muse-spark-1.1。基础 URL：https://api.meta.ai/v1（兼容 OpenAI 的通信协议）。使用 need_env_input 返回的生成的 CUSTOM_KEY_... 名称；不要假设或手动创建供应商环境变量。文档：https://dev.meta.ai/docs/getting-started/overview。

---

xAI Grok — 关于订阅混淆的说明

用户经常混淆两个不相关的 xAI 产品：

• X Premium / SuperGrok 订阅（x.com 上每月 30 美元）——仅限聊天 UI 访问。不包括 API 访问。
• console.x.ai — 独立的开发者账户，单独计费。生成 API 密钥，新账户有 25 美元促销积分，然后按 token 付费。

如果用户想通过 BYOK 添加 Grok，请引导他们访问 **https://console.x.ai/**——而不是 x.com / Premium / SuperGrok。xai 模板的 homepage 字段已深度链接到正确位置。Hermes / Grok-CLI 的 OAuth 到订阅流程依赖于第一方 client_id 白名单，xAI 不将其扩展到第三方云代理，因此 BYOK API 密钥路径是托管产品的唯一可行集成方式。