背景

不少用户会把 Open CoDesign 接到各类“coding plan”或 Claude Code 协议转换/兼容服务上使用。这类服务虽然表面上提供 OpenAI 兼容接口，但往往还带有额外的“应用白名单”或客户端身份校验，只允许特定客户端访问，例如 Claude Code、openclaw、Hermes 等。

在这种情况下，Open CoDesign 即使配置方式看起来正确，也可能因为不在服务端白名单内而报错。用户看到的现象通常像是：

• 400 / 403 请求失败
• developer / role 不兼容之类的报错
• 与 bug: 通义千问 Qwen API 报错 'developer is not one of [...roless...]' #184 类似的 provider 兼容性错误

但这类问题很多时候并不是 Open CoDesign 本身的 provider 适配 bug，而是服务端明确限制了允许接入的应用。

需求

希望在产品中增加更清晰的提示，提前告知用户：

• 某些 coding plan / 代理 / 兼容 API 服务带有应用白名单
• 即使它们声称“OpenAI 兼容”，也不代表 Open CoDesign 一定可用
• 若服务只允许 Claude Code / openclaw / Hermes / 官方客户端等特定应用，Open CoDesign 可能无法兼容
• 当出现与 bug: 通义千问 Qwen API 报错 'developer is not one of [...roless...]' #184 类似的报错时，需要提示用户排查是否为服务端白名单或客户端限制，而不只是模型参数问题

建议方案

可以考虑至少增加一层提示：

1. 在模型或 Base URL 配置入口增加说明
   明确提示“部分 coding plan / 兼容服务存在应用白名单，Open CoDesign 可能无法使用”。

2. 在连接失败或常见 provider 报错时补充引导文案
   对 400 / 403、role 不支持等常见错误，增加“可能是服务端应用白名单或客户端限制”的提示。

3. 在文档 / FAQ 中单独补充一节
   解释 OpenAI 兼容 API 不等于客户端完全兼容，避免用户误以为这是通用 bug。

价值

• 降低用户误报 bug 的概率
• 减少围绕第三方兼容端点的重复排障成本
• 帮助用户更快判断问题是否出在服务端白名单策略，而不是 Open CoDesign 配置错误

相关 issue

• bug: 通义千问 Qwen API 报错 'developer is not one of [...roless...]' #184