byok-custom-model

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

🔑 BYOK — Custom LLM Models

🔑 BYOK — 自定义LLM模型

Add a custom LLM endpoint to the model selector. Bypasses the platform proxy — you supply your own API key, the agent hits the vendor / aggregator directly (OpenRouter, DashScope, Anthropic native, self-hosted, etc.).

The

custom_models

tool stays built-in. This SKILL.md is the reference doc + onboarding flow.

在模型选择器中添加自定义LLM端点。绕过平台代理——您提供自己的API密钥，Agent直接对接供应商/聚合器（OpenRouter、DashScope、Anthropic原生接口、自部署服务等）。

custom_models

工具为内置工具。本文档SKILL.md是参考文档及接入流程说明。

Onboarding flow — API-example first

接入流程 — 优先使用API示例

When a user wants to add a custom model, the first move is NOT to ask for
base_url
or
upstream_model
. Instead:

Ask the user to paste the provider's official API example from their docs (curl / requests sample). Tell them not to include a real API key — placeholders or fake keys are fine.

Run

custom_models(action="parse_example", api_example="<pasted>")

. It auto-detects:

```
base_url
```
```
upstream_model
```
```
wire
```
(openai vs anthropic)
```
thinking_mode
```
vendor-specific
```
request_params
```
```
capabilities
```

Review the parsed draft with the user (1 sentence summary), then call
```
add
```
with the detected fields.
The
```
add
```
call dispatches a secure input popup to collect the API key. The key goes straight to
```
workspace/.env
```
, never to chat history or tool results.
After success, the model appears in the selector as
```
custom/<short-name>
```
. User switches with
```
/model custom/<name>
```
.

Only ask for
base_url
/
upstream_model
directly if the user refuses to paste an example or already supplied them.

当用户想要添加自定义模型时，第一步不要直接询问
base_url
或
upstream_model
。正确步骤如下：

请用户粘贴供应商官方文档中的API示例（curl/请求示例）。提醒不要包含真实API密钥——使用占位符或假密钥即可。

执行

custom_models(action="parse_example", api_example="<粘贴的内容>")

。该工具会自动识别：

```
base_url
```
```
upstream_model
```
```
wire
```
（openai或anthropic协议类型）
```
thinking_mode
```
供应商特定的
```
request_params
```
```
capabilities
```

向用户展示解析后的草稿总结（一句话概括），然后调用
```
add
```
接口传入识别出的字段。
```
add
```
调用会触发一个安全输入弹窗来收集API密钥。密钥将直接存入
```
workspace/.env
```
，绝不会进入聊天记录或工具结果中。
成功后，模型会以
```
custom/<简称>
```
的形式出现在选择器中。用户可通过
```
/model custom/<名称>
```
切换模型。

仅当用户拒绝粘贴示例或已自行提供
base_url
/
upstream_model
时，才直接询问这些参数。

Curated vendors —

add_template

shortcut

精选供应商 —

add_template

快捷方式

For these 9 vendors, skip

parse_example

entirely. Call

add_template(vendor="<id>")

— all fields auto-filled, the user only provides the API key via the secure popup.

vendor id	notes
`anthropic`	Anthropic native API (Claude direct, not via Bedrock/Vertex)
`openai`	OpenAI API direct
`qwen`	Alibaba DashScope
`deepseek`	DeepSeek API
`kimi`	Moonshot
`mimo`	Xiaomi MiMo
`gemini`	Google AI Studio (NOT Vertex)
`gemma`	Google Gemma
`venice`	Venice AI (privacy-first)

Optional

upstream_model

overrides the curated default — accepts any model id from

list_vendor_models

for vendors with dynamic discovery.

对于以下9个供应商，可完全跳过

parse_example

步骤。调用

add_template(vendor="<id>")

——所有字段会自动填充，用户仅需通过安全弹窗提供API密钥即可。

供应商ID	说明
`anthropic`	Anthropic原生API（直接对接Claude，而非通过Bedrock/Vertex）
`openai`	OpenAI直接API
`qwen`	阿里云DashScope
`deepseek`	DeepSeek API
`kimi`	Moonshot（月之暗面）
`mimo`	小米MiMo
`gemini`	Google AI Studio（非Vertex）
`gemma`	Google Gemma
`venice`	Venice AI（隐私优先）

可选参数

upstream_model

可覆盖精选默认值——支持从

list_vendor_models

获取的任何模型ID（针对支持动态发现的供应商）。

Dynamic vendor catalogs —

list_vendor_models

动态供应商模型目录 —

list_vendor_models

Some vendors ship new models often. Use

list_vendor_models(vendor="<id>")

to fetch the live

/models

catalog with capabilities (vision, tools, reasoning, privacy tier), pricing, and context length.

Required when:

User wants the latest model not in curated defaults
User asks for a specific capability ("which Venice model supports vision?")
User wants pricing comparison

Only works for vendors with

supports_dynamic_models: true

templates

部分供应商会频繁发布新模型。使用

list_vendor_models(vendor="<id>")

可获取实时

/models

目录，包含模型能力（视觉、工具调用、推理、隐私等级）、定价及上下文长度信息。

在以下场景中需使用该工具：

用户需要最新的非默认精选模型
用户询问特定能力（如“哪个Venice模型支持视觉功能？”）
用户需要对比定价

仅对

templates

中标记

supports_dynamic_models: true

的供应商生效。

Actions reference

操作参考

action	required	purpose
`templates`	—	List curated vendor presets
`list_vendor_models`	`vendor`	Live `/models` catalog (requires `supports_dynamic_models` )
`add_template`	`vendor`	One-click registration for curated vendor (recommended path for 9 known vendors)
`parse_example`	`api_example`	Parse docs API example into a safe draft (non-curated vendors)
`add`	`upstream_model` , `base_url` , `wire`	Register from custom args (use after `parse_example` )
`list`	—	Show all registered custom entries
`get`	`model_id`	Inspect one entry
`remove`	`model_id`	Delete an entry

操作	必填参数	用途
`templates`	—	列出精选供应商预设
`list_vendor_models`	`vendor`	获取实时 `/models` 目录（需供应商支持动态模型）
`add_template`	`vendor`	一键注册精选供应商（推荐用于9个已知供应商的接入路径）
`parse_example`	`api_example`	将文档中的API示例解析为安全草稿（适用于非精选供应商）
`add`	`upstream_model` , `base_url` , `wire`	通过自定义参数注册模型（需在 `parse_example` 后使用）
`list`	—	展示所有已注册的自定义模型条目
`get`	`model_id`	查看单个模型条目详情
`remove`	`model_id`	删除模型条目

After registration

注册完成后

Model appears in the selector prefixed with
```
custom/
```
.
User switches via
```
/model custom/<name>
```
(e.g.
```
/model custom/qwen-plus-e3f4
```
) or via the model picker UI.
Subsequent calls bypass the platform proxy — the vendor's pricing applies directly to the user's BYOK quota.

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

Critical rules

重要规则

Never accept an API key pasted in chat. If the user pastes one, ignore it, refuse to register, and explain that the secure popup is the only way.
Never re-issue the secure-input popup automatically if the user hasn't responded — wait.
Don't manually edit
workspace/config/custom_models.yaml
or
workspace/.env
. Always go through this tool.
The 9 curated vendors always use
```
add_template
```
. Only use
```
parse_example
```
+
```
add
```
for self-hosted or rare providers.

绝不接受在聊天框中粘贴的API密钥。若用户粘贴密钥，需忽略并拒绝注册，同时说明安全弹窗是唯一合法的方式。
不要自动重复触发安全输入弹窗——需等待用户响应后再操作。
不要手动编辑
workspace/config/custom_models.yaml
或
workspace/.env
。所有操作必须通过本工具完成。
9个精选供应商必须使用
```
add_template
```
。仅对自部署或罕见供应商使用
```
parse_example
```
+
```
add
```
流程。

byok-custom-model

Original

Translation

🔑 BYOK — Custom LLM Models

🔑 BYOK — 自定义LLM模型

See also

相关文档

Onboarding flow — API-example first

接入流程 — 优先使用API示例

Curated vendors —
`add_template`
shortcut

精选供应商 —
`add_template`
快捷方式

Dynamic vendor catalogs —
`list_vendor_models`

动态供应商模型目录 —
`list_vendor_models`

Actions reference

操作参考

After registration

注册完成后

Critical rules

重要规则

byok-custom-model

Original

Translation

🔑 BYOK — Custom LLM Models

🔑 BYOK — 自定义LLM模型

See also

相关文档

Onboarding flow — API-example first

接入流程 — 优先使用API示例

Curated vendors — add_template shortcut

精选供应商 — add_template快捷方式

Dynamic vendor catalogs — list_vendor_models

动态供应商模型目录 — list_vendor_models

Actions reference

操作参考

After registration

注册完成后

Critical rules

重要规则

Curated vendors —
`add_template`
shortcut

精选供应商 —
`add_template`
快捷方式

Dynamic vendor catalogs —
`list_vendor_models`

动态供应商模型目录 —
`list_vendor_models`