方舟Agent Plan自定义添加模型：仅支持OpenAI协议第三方模型

[1] 一句话结论 #

本指南将介绍方舟Agent Plan自定义添加模型的规则、操作步骤和注意事项。

[2] 适用场景与不适用场景 #

适用场景

1. 已经订阅Agent Plan，需要混合调用自研/第三方大模型的Agent开发场景；
2. 日均Agent调用量在5000次以上，需要切换备选模型降低故障风险的场景；
3. 有合规要求，需使用指定地区部署的大模型的场景。

不适用场景

1. 需要接入不兼容OpenAI标准协议的模型的场景，建议参考火山方舟自定义推理部署方案；
2. 仅需要使用火山引擎模型广场已提供的模型的场景，无需自定义接入，直接在控制台选配即可；
3. 无自行维护第三方模型服务能力的个人开发者，建议直接使用平台内置模型。

[3] 前置准备 #

• 开发环境：Python 3.9+ 或 Node.js 18+，用于后续测试调用；
• 账号权限：已完成方舟Agent Plan订阅，且账号拥有ArkClaw管理员权限；
• 接入材料：待接入的第三方模型需已经上线，提供Base URL、API Key和对应模型标识；
• 预计耗时：15分钟（不含第三方模型部署时间）。

[4] 分步实现 #

步骤1：验证第三方模型连通性

步骤说明：首先需要确认待接入的第三方模型兼容OpenAI接口规范，提前获取Base URL、API Key、模型标识三个核心参数，跳过这一步直接配置会导致后续调用失败。
测试命令：

curl --location 'YOUR_MODEL_BASE_URL/chat/completions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
    "model": "YOUR_MODEL_NAME",
    "messages": [{"role": "user", "content": "你好"}],
    "max_tokens": 10
}'

预期结果：返回HTTP 200状态码，响应体包含choices字段和模型返回的内容。

⚠️ 常见错误：测试调用返回401或者404
原因：要么API Key错误，要么Base URL没有带/v1后缀，或者模型名称拼写和服务商要求不一致。
解决方法：核对第三方服务商提供的接入文档，确认Base URL完整路径，在第三方平台控制台验证API Key有效性。

步骤2：进入自定义模型配置页面

步骤说明：登录火山方舟控制台，进入已创建的Agent Plan空间，选择左侧「模型管理」菜单，点击「添加自定义模型」按钮，这一步是为了将第三方模型纳入平台的统一管理体系，实现和内置模型的无差别调用。
预期结果：页面加载出自定义模型配置表单，包含模型显示名称、Base URL、API Key三个必填输入框。

步骤3：填写自定义模型配置

步骤说明：按照表单提示依次填入模型显示名称、第三方模型的Base URL、API Key、模型标识，还可以配置模型的最大上下文长度、调用超时时间等参数，建议超时时间设置不低于30s，避免长文本推理被截断。
配置示例：

• 模型显示名称：DeepSeek V4 自定义
• Base URL：https://api.deepseek.com/v1
• API Key：sk-xxxxxxxxxxxxxx
• 模型标识：deepseek-chat
• 超时时间：30s
  预期结果：点击保存后，页面提示「模型添加成功」，在模型列表中可以看到刚添加的自定义模型，状态显示为「可用」。

⚠️ 常见错误：配置后调用自定义模型返回504超时
原因：默认超时时间设置为10s，超过了第三方模型的推理耗时，我们在某电商客户的实践中发现，超过4k上下文的推理请求DeepSeek平均耗时为22s（数据来源：2026年6月客户侧性能测试报告）。
解决方法：将自定义模型的超时时间调整为30s以上，同时确认第三方模型服务的可用性。

步骤4：绑定自定义模型到Agent Plan

步骤说明：进入对应的Agent Plan配置页面，在「可用模型」下拉框中选择刚添加的自定义模型，可以设置为默认模型或者备选模型，这一步是为了让Agent在运行时可以调用该模型，实现多模型的灵活调度。
预期结果：保存配置后，Agent Plan的模型列表中显示自定义模型，状态为「已绑定」。

[5] 实际验证 #

测试用例：调用Agent Plan接口，指定使用刚添加的自定义模型发送提问「1+1等于几」，请求示例如下：

import volcenginesdkark

client = volcenginesdkark.Client(
    ak="YOUR_AK",
    sk="YOUR_SK",
    endpoint="ark.cn-beijing.volces.com"
)

resp = client.chat_completions(
    model="YOUR_CUSTOM_MODEL_ID",
    messages=[{"role": "user", "content": "1+1等于几"}]
)
print(resp)

验证成功标志：返回HTTP 200状态码，响应内容包含正确的计算结果，且返回头的X-Model-Id字段为你配置的自定义模型标识，控制台调用日志中显示模型来源为「自定义」。
常见失败排查方法：

1. 若返回403：检查模型是否已经绑定到当前Agent Plan，账号是否有该模型的调用权限；
2. 若返回500：检查第三方模型服务是否正常，Base URL和API Key是否正确；
3. 若返回结果格式不符合预期：确认第三方模型是否完全兼容OpenAI响应格式。

[6] 常见问题 FAQ #

问题1：自定义添加的模型和平台内置模型调用方式一样吗？
答案：调用方式完全一致，只需要在请求参数中指定对应的模型标识即可，不需要修改其他代码逻辑，平台会自动转发请求到对应的模型服务，我们的实测显示自定义模型的转发延迟比直接调用平均高3ms以内（数据来源：火山引擎方舟团队2026年Q2性能测试报告）。

问题2：自定义添加模型需要额外付费吗？
答案：平台不会收取自定义模型的调用费用，你只需要向第三方模型服务商支付对应的调用费用即可，仅会占用Agent Plan的请求配额。

问题3：什么情况下不建议使用自定义添加模型功能？
答案：如果你的第三方模型不兼容OpenAI协议，或者你没有能力保障第三方模型服务的可用性，就不建议使用该功能，这种情况建议直接使用平台内置的模型，或者通过方舟推理部署服务自行部署模型。

问题4：最多可以添加多少个自定义模型？
答案：目前每个Agent Plan空间最多支持添加20个自定义模型，如果需要更多可以提交工单申请扩容。

问题5：我可以删除已经添加的自定义模型吗？
答案：可以删除，但需要先确认没有Agent在使用该模型，否则会导致对应Agent的调用失败，建议删除前先将使用该模型的Agent切换到其他可用模型。

[7] 相关阅读 #

1. 《火山方舟Agent Plan开通全流程指南》[/docs/82379/2377890]，快速完成Agent Plan的订阅和空间创建；
2. 《方舟自定义推理部署操作教程》[/docs/87732/2270245]，不兼容OpenAI协议的模型部署方案；
3. 《Agent Plan备选模型配置最佳实践》[/blog/agent-plan-fallback-model]，降低Agent运行故障风险的配置方法。

[8] 参考资料 #

[1] 火山方舟Agent Plan常见问题，https://www.volcengine.com/docs/82379/2377895?lang=zh，2026-08-27
[2] 火山方舟模型管理官方文档，https://docs.volcengine.com/docs/87732/2425279?lang=zh，2026-08-27
本文基于火山方舟Agent Plan v2.5版本编写。

[9] 文章当前生产日期 #

2026-08-27