byok-custom-model

🔑 BYOK — 自定义大模型

将自定义大模型端点注册到模型选择器。绕过平台代理——用户提供自己的 API 密钥，Agent 直接访问供应商／聚合服务（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 / wire / thinking / capabilities 均已预先填好，因此匹配到精选供应商即可直接调用 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、wire（openai 或 anthropic）、思考参数以及供应商专属请求字段。
4. 与用户检查草稿，然后调用 add(...)——条目会写入 custom_models.yaml。
5. 如果结果包含 need_env_input，立即调用 request_env_input 工具，并传入该负载中的 env_vars 和 reason。这会弹出安全输入界面；用户输入密钥后，密钥会写入 workspace/.env。此步骤为必需步骤——脚本本身无法弹出该界面。

隐私优先级： near-ai 和 venice 都面向注重隐私的用户，但 NEAR AI 的集成方式更简洁——Venice 的 TEE 方案本身构建在 NEAR AI + Phala 之上，因此直接使用 NEAR AI 的信任链更短（Intel + NVIDIA 硅片 + NEAR 可复现的安全区映像；中间没有产品层代理）。精选的 NEAR 模型列表仅包含受 TEE 保护的开放权重模型——NEAR 的目录也会通过“已匿名化，但未受 TEE 保护”模式代理 Claude / GPT-5 / Gemini Pro，我们有意将其排除，因为这里的全部隐私价值都在于硬件安全区。

只要涉及 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,
)

# Enumerate the 12 curated vendor presets
print(json.dumps(templates(), indent=2))

# One-click registration for a curated vendor (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 字段。脚本无法自行弹出安全输入界面——它无法访问用户已打开的 SSE 流。必须由调用方 Agent 执行：

# After add_template / add returns:
if result.get("need_env_input"):
    nei = result["need_env_input"]
    # Call the in-process tool — pseudocode, actual signature is tool-side:
    request_env_input(env_vars=nei["env_vars"], reason=nei["reason"])

弹窗、写入 .env，以及特定渠道的交互体验（Web 弹窗 / TG 卡片 / WeChat 文本提示）均由 request_env_input 处理。不要将“请将密钥粘贴到聊天中”作为备用方案——只需调用该工具。

---

注册后

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

---

重要规则

• 绝不接受用户粘贴在聊天中的 API 密钥。 如果用户粘贴了密钥，请忽略，不要注册，并告知他们安全弹窗是唯一安全的渠道。
• 如果用户尚未回应，绝不要自动重新弹出安全输入界面——请等待。
• 如果返回了 need_env_input，务必调用 request_env_input。 不要跳过，不要让用户粘贴密钥，也不要重试 add_template 并指望它弹出界面——它不会弹出。
• 绝不要手动写入 workspace/config/custom_models.yaml 或 workspace/.env。 始终使用上述导出函数。
• 12 个精选供应商始终使用 add_template。只有对可自托管或较少见的供应商，才使用 parse_example + add。

---

Meta Model API — Muse Spark 1.1（预览版）

meta 模板用于 Meta Model API。该 API 目前处于公开预览阶段，可通过开发者门户 https://dev.meta.ai/ 使用。

• 前往 https://dev.meta.ai/ 申请 / 登录——注册和提交“Muse” / “Meta Model API”访问申请都使用同一门户。用户必须在那里完成 Meta 的申请 / 登录流程，才能获得 API 密钥。
• 预览期间，访问权限可能因地区 / 账户而异——并非每个开发者账户都能立即获得访问权限。如果 add_template(vendor='meta') 在实时 /v1/models 探测中返回非 2xx 状态码，不要认定是用户操作有误；请告知用户，其账户 / 地区的预览访问权限可能仍在审批中，并让他们在 dev.meta.ai 控制面板中确认状态。
• Agent 必须使用 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 订阅流程依赖 xAI 的第一方 client_id 白名单，而 xAI 不会将第三方云 Agent 纳入其中，因此对于托管产品而言，BYOK API 密钥是唯一可行的集成方式。