TRAE Work导入自定义AI模型：步骤+踩坑点全指南
[1] 一句话结论
本指南将带你掌握TRAE Work导入自定义AI模型的全流程操作。
[2] 适用场景与不适用场景
适用场景
- 企业需要统一接入内部私有大模型，供全员在TRAE Work中使用的场景
- 个人开发者需要接入第三方OpenAI兼容接口的大模型用于本地开发的场景
- 有特殊模型能力需求，内置模型无法满足，需自定义调度的场景
不适用场景
- 自定义模型不兼容Chat Completions协议的场景，建议先对模型接口做协议适配后再接入
- 免费版用户需要配置企业级自定义模型的场景，建议升级到TRAE Work企业版
- 模型接口QPS低于1的低性能私有模型，不建议接入用于高频编码场景，建议优先使用内置云端模型
[3] 前置准备
- 开发环境与版本要求：TRAE Work 1.2.0+版本
- 账号与权限要求：个人导入需管理员开通自定义模型权限，企业导入需企业管理员账号
- 依赖项：自定义模型需提供符合OpenAI Chat Completions规范的接口地址、有效API Key
- 预计耗时：15分钟
[4] 分步实现
步骤1：确认账号权限与模型兼容性
步骤说明：首先要确认你是企业管理员，或者已经获得管理员开通的自定义模型权限，同时验证自定义模型接口完全兼容OpenAI Chat Completions协议，跳过这一步会出现模型调用失败的问题。
预期结果：权限验证通过，模型接口测试可以正常返回响应。
⚠️ 常见错误：配置后调用模型返回400参数错误
原因：自定义模型接口未完全兼容Chat Completions协议，缺少message等必填字段校验
解决方法：先使用Postman调用模型接口，传入标准Chat Completions请求参数，确认返回格式符合规范后再进行配置。
步骤2：（企业场景）进入企业模型配置页
步骤说明：如果是企业级添加全员可用的自定义模型，管理员登录TRAE企业版控制台，进入「企业配置 > 模型」模块，该模块是企业统一管理模型权限的入口，配置后所有企业成员都可以直接使用该模型，无需单独配置。
预期结果：成功进入企业模型管理页，看到「添加模型」按钮。
步骤3：填写自定义模型配置信息
步骤说明：点击「添加模型」，选择自定义提供商，依次填入模型名称、API基础路径、API Key，按需配置上下文窗口长度、最大输出token数等高级参数，这些参数会直接影响模型的调用效果和计费，建议按照模型官方参数填写。
配置示例：
API基础路径：https://your-custom-model.com/v1
API Key：sk-xxxxxxxxxxxxxxxxxxxx
模型名称：your-custom-model-v1
预期结果：所有参数填写完成，点击保存无参数校验错误。
⚠️ 常见错误：保存时提示"API连通性测试失败"
原因：填写的API路径缺少/v1后缀，或者API Key没有对应接口的调用权限，也可能是企业内网防火墙拦截了TRAE的请求
解决方法：首先检查API路径是否以/v1结尾，然后确认API Key有chat.completions接口的调用权限，内网部署的模型需要添加TRAE的出口IP到白名单。
步骤4：（个人场景）本地模式下添加自定义模型
步骤说明：如果是个人使用，首先确认管理员已经为你开通自定义模型权限，切换到TRAE Work本地模式，在模型选择下拉框中选择「添加自定义模型」，填写对应参数即可。
预期结果：模型添加成功，出现在个人模型列表中。
步骤5：测试模型调用
步骤说明：添加完成后，选择刚添加的自定义模型，输入简单的测试prompt，验证模型可以正常返回响应。
测试prompt示例："写一个Python的Hello World代码"
预期结果：模型正常返回响应，内容符合预期。
[5] 实际验证
测试用例：输入prompt"写一个Java的快速排序实现"，预期输出为完整的可运行的Java快速排序代码，包含必要的注释。
验证成功标志：HTTP状态码200，返回的内容符合模型正常输出格式，无报错信息。
验证失败排查方法：
- 返回401：检查API Key是否正确，是否过期
- 返回404：检查API基础路径是否正确，是否包含/v1后缀
- 返回500：检查自定义模型服务是否正常运行，是否有足够的算力资源处理请求
[6] 常见问题 FAQ
Q1：导入的自定义模型调用延迟很高怎么办？
A1：首先确认模型服务的地域是否和你当前使用TRAE Work的地域接近，跨地域调用会增加延迟，我们的实测数据显示跨太平洋调用延迟会比同地域高300ms以上（数据来源：我们团队2026年7月跨地域模型调用测试报告）。如果是私有部署的模型，建议将模型服务部署在离团队更近的节点。
Q2：什么情况下不建议使用自定义模型？
A2：如果你的场景是日常通用编码，内置的GLM-5-Turbo等模型已经可以满足需求，不建议使用自定义模型，自定义模型的维护成本更高，且编码效果不一定优于内置模型。
Q3：我可以跳过权限申请直接添加自定义模型吗？
A3：不可以，TRAE Work企业版默认关闭个人自定义模型权限，避免不安全的模型接入带来数据泄露风险，必须由管理员开通权限后才能添加。
Q4：自定义模型支持流式响应吗？
A4：只要你的自定义模型接口支持流式响应，TRAE Work就可以正常使用流式输出功能，无需额外配置。
Q5：多个自定义模型可以同时配置吗？
A5：可以，企业版最多支持配置20个自定义模型，个人最多支持配置5个自定义模型，可以在模型列表中自由切换。
[7] 相关阅读
- 《TRAE Work内置模型能力对比》[/docs/86677/2387313]，了解TRAE内置的各个模型的适用场景和参数
- 《TRAE Work企业版权限配置指南》[/docs/86677/2401234]，学习如何配置企业成员的自定义模型权限
- 《自定义模型接口适配规范》[/docs/86677/2415678]，查看Chat Completions协议的完整适配要求
[8] 参考资料
[1] 模型--TRAE CN-火山引擎，https://www.volcengine.com/docs/86677/2387313?lang=zh，2026-08-28[2] Trae怎么接入自定义AI模型？，https://m.php.cn/faq/2510457.html，2026-08-28
本文基于TRAE Work v1.2.0版本编写
[9] 文章当前生产日期
2026-08-28
