OpenClaw、Claude Code、Dify、n8n 这类 AI Agent 工具接入 DeepAI API 中转站 时，最容易被忽略的不是 Base URL，也不是 API Key，而是请求体里的消息角色。一个很典型的错误是：同一个模型在 Cherry Studio 或 curl 里能用，放到 OpenClaw 自定义 OpenAI-compatible Provider 里却直接 400，错误提示为 developer is not one of ['system','assistant','user','tool','function']。
developer 需要按兼容性映射为 system。问题背景：developer role 为什么会让兼容模型 400
这个问题来自 OpenClaw Issue #27037。用户通过 OpenAI-compatible 代理接入 Qwen 后端时，OpenClaw 给所有 openai-completions Provider 都发送了 role: "developer"。但很多非 OpenAI 后端，例如 Qwen、GLM、DeepSeek、Kimi、部分 Azure 或自建代理，仍然只接受 system、user、assistant、tool、function 这类更传统的 Chat Completions 角色。
这就会造成一种很迷惑的现象：DeepAI API 中转站本身能正常路由，模型 ID 和 Key 也没问题，但上游后端在解析 messages[0].role 时直接拒绝请求。这个错误不是“模型不可用”，而是“客户端把更偏 OpenAI 原生或 Responses/Harmony 体系的角色发给了并不支持它的兼容端”。
复现方式：同一模型 system 能通，developer 失败
Issue 中的验证很直接：同一个代理、同一个模型，请求体使用 system 可以正常返回；把第一条指令改成 developer 就返回 400。排查时可以用 DeepAI API 中转站做同样的最小复现，把变量控制在消息角色上。
curl https://api.deepai.wang/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_DEEPAI_KEY" \
-d '{
"model": "your-compatible-model",
"messages": [
{"role": "system", "content": "你是一个严谨的 API 接入助手"},
{"role": "user", "content": "用一句话说明你能正常回复"}
]
}'
如果 system 能通，而下面这种 developer 失败，就基本能确认问题在 role 兼容性，而不是认证、额度、域名解析或模型路由。
{
"model": "your-compatible-model",
"messages": [
{"role": "developer", "content": "你是一个严谨的 API 接入助手"},
{"role": "user", "content": "测试"}
]
}
修复思路：非原生 OpenAI endpoint 默认关闭 developer role
相关修复在 OpenClaw PR #29479 中合并。PR 的核心做法是：当 openai-completions 模型的 baseUrl 不是原生 api.openai.com 时，兼容性层强制把 supportsDeveloperRole 设为 false。这样 OpenClaw 在构造 Chat Completions 请求时，会把开发者指令按兼容端可接受的方式落到 system 角色。
对 DeepAI API 中转站用户来说，这个策略非常合理。中转站背后可能路由到多个供应商，同一个 https://api.deepai.wang/v1 下既有原生 OpenAI 风格模型，也有 Qwen、DeepSeek、GLM、Kimi 或其他兼容服务。客户端不能只因为接口名叫 OpenAI-compatible，就假设所有后端都支持 OpenAI 最新角色扩展。
DeepAI API 中转站场景下怎么配置 OpenClaw
如果你使用的是包含 PR #29479 之后修复的 OpenClaw 版本，通常不需要额外配置。重点是 Base URL 写到中转站根路径，并确保实际运行的 OpenClaw 进程已经升级。
{
"models": {
"providers": {
"deepai": {
"baseUrl": "https://api.deepai.wang/v1",
"apiKey": "YOUR_DEEPAI_KEY",
"api": "openai-completions",
"models": [{
"id": "your-compatible-model",
"name": "DeepAI Compatible Model",
"contextWindow": 65536,
"maxTokens": 8192
}]
}
}
},
"agents": {
"defaults": {
"model": {
"primary": "deepai/your-compatible-model"
}
}
}
}
- Base URL：填写
https://api.deepai.wang/v1，不要写成/v1/chat/completions。 - 模型 ID：使用 DeepAI API 中转站后台实际开放的模型名，不要把展示名称当成路由 ID。
- 升级验证：升级 OpenClaw 后重启桌面端、gateway、Docker 或 systemd 服务，确认没有继续跑旧版本。
- 日志验证：在中转站日志里查看第一条消息角色是否已经变成
system。
如果暂时不能升级，如何临时绕过
如果生产环境暂时不能升级 OpenClaw，可以先在模型兼容配置里显式声明不支持 developer role。不同版本配置字段可能略有差异，但排查方向是一致的：让 OpenClaw 不要给非原生 OpenAI 端点发送 role: "developer"。
{
"id": "your-compatible-model",
"name": "DeepAI Compatible Model",
"compat": {
"supportsDeveloperRole": false
}
}
如果你的版本不支持这个字段，另一个临时办法是在自建转发层里做 role 映射：当目标模型不是原生 OpenAI 且 messages[i].role === "developer" 时，把它转换为 system。不过这属于代理层补丁，长期还是建议升级客户端，避免工具调用、流式响应和多轮上下文继续遇到类似兼容问题。
常见坑位
- 把 400 当成 Key 错：如果错误正文明确指向
messages[0].role，优先排查角色，而不是反复换 Key。 - 只在一个客户端测试：Cherry Studio 能通而 OpenClaw 失败，往往说明两者请求体不同，应该对比中转站日志。
- 误以为 OpenAI-compatible 等于完全 OpenAI：兼容通常指路径和主体结构相似，不代表所有新字段、新 role、新参数都被每个后端接受。
- 忽略 Azure 和代理：PR #29479 特别提到 Azure、generic proxy、Qwen proxy 等场景都应关闭 developer role。
- 服务没切版本：升级后如果 systemd 或 Docker 仍指向全局旧包，请求体不会发生变化。
给站长和团队的 SEO 接入建议
如果你运营 DeepAI API 中转站，建议把“请求体兼容性”写进接入文档，而不是只给用户 Base URL 和 Key。开发者真正搜索的问题通常是“OpenClaw 400 developer role”“Qwen developer is not one of system user assistant”“OpenAI Compatible role 不兼容”。把这些问题整理成可复现教程，可以帮助用户理解中转站的价值：统一入口、集中日志、快速对比请求体，并根据目标模型做更稳的兼容策略。
更实用的做法是，在 DeepAI API 中转站后台或文档里给模型标注能力：是否支持工具调用、是否支持流式、是否支持 parallel_tool_calls、是否接受 developer role、是否需要把系统指令放到 system。这样 OpenClaw、Dify、n8n、Cline 等客户端出现问题时，排查会从“猜模型”变成“查字段”。
参考资料
- OpenClaw Issue #27037：developer role not recognized by non-OpenAI backends
- OpenClaw PR #29479：force supportsDeveloperRole=false for non-native OpenAI endpoints
- OpenAI Harmony Response Format：Roles
- OpenClaw openai-completions tools 参数排查
总结
OpenClaw 接入 DeepAI API 中转站时，如果非 OpenAI 后端返回 developer is not one of system/user/assistant/tool/function，不要先怀疑中转站不可用。优先检查请求体里的 messages[].role：对 Qwen、DeepSeek、GLM、Kimi、Azure 或通用代理这类兼容端，开发者指令通常应该以 system 发送。升级到包含 PR #29479 的 OpenClaw 版本，或临时设置 supportsDeveloperRole: false，再结合 DeepAI API 中转站日志验证角色映射，通常就能让 400 迅速消失。
