Cherry Studio缺失instructions导致OpenAI-Response API访问失败

Cherry Studio缺失instructions导致OpenAI-Response API访问失败

最近在使用Cherry Studio通过OpenAI-Response类型访问兼容OpenAI Responses API的接口时，遇到了一个400 Bad Request问题。最终定位发现，原因是请求体中缺失有效的顶层instructions字段。

问题现象

在Cherry Studio中配置OpenAI-Response服务后，请求接口：

https://api.example.com/v1/responses

报错如下：

错误名称: AI_APICallError 错误信息: Bad Request 状态码: 400

响应内容：

{"detail":"Instructions are required"}

Cherry Studio实际发送的请求体中，虽然已经在助手里配置了提示词：

You are a helpful assistant.

但请求体变成了类似这样：

{"model":"gpt-5.5","input":[{"role":"developer","content":"You are a helpful assistant."},{"role":"user","content":[{"type":"input_text","text":"say hi"}]}],"instructions":"[undefined]","text":{"verbosity":"low"},"stream":true}

可以看到，助手提示词被放进了input数组中的developer消息里，而顶层的instructions字段却是：

"instructions":"[undefined]"

因此服务端返回：

Instructions are required

原因分析

OpenAI Responses API支持顶层instructions字段，例如：

{"model":"gpt-5.5","instructions":"You are a helpful assistant.","input":[{"role":"user","content":[{"type":"input_text","text":"say hi"}]}]}

但Cherry Studio在OpenAI-Response模式下，并没有自动把助手提示词映射到顶层instructions，而是将其作为developer消息放入input。

对于某些兼容OpenAI Responses API的中转站或上游服务来说，顶层instructions是必填项。因此，即使input中存在developer消息，仍然会因为缺少有效的instructions而报错。

此外，请求体中还可能出现多个字符串形式的：

"[undefined]"

例如：

"temperature":"[undefined]","top_p":"[undefined]","max_output_tokens":"[undefined]","tools":"[undefined]"

这些未设置参数理论上应该被省略，而不是以字符串形式发送。

解决方法

在Cherry Studio的模型或供应商配置中，找到自定义参数，手动添加：

{"instructions":"You are a helpful assistant."}

如果希望使用中文提示词，也可以写成：

{"instructions":"你是一个有帮助的AI助手。"}

保存后重新测试，OpenAI-Response API即可正常访问。

修复后的请求体示例

添加自定义参数后，请求体中会包含有效的顶层instructions：

{"model":"gpt-5.5","instructions":"You are a helpful assistant.","input":[{"role":"developer","content":"You are a helpful assistant."},{"role":"user","content":[{"type":"input_text","text":"say hi"}]}],"text":{"verbosity":"low"},"stream":true}

虽然此时提示词可能同时出现在instructions和input[0].role = developer中，但至少可以满足服务端对instructions的要求。

问题归因

这个问题主要与Cherry Studio的OpenAI-Response请求体构造有关：

1. 助手提示词没有自动映射到顶层instructions；
2. 未设置的参数可能被序列化为字符串"[undefined]"；
3. 某些Responses API兼容服务要求必须提供顶层instructions。

因此，这不属于OpenAI官方API本身的问题。中转站只是对instructions字段要求较严格，而Cherry Studio没有自动提供该字段。

总结

如果在Cherry Studio中使用OpenAI-Response时遇到：

Instructions are required

可以优先检查请求体中是否存在有效的顶层：

"instructions":"..."

如果没有，直接在Cherry Studio的自定义参数中手动添加instructions即可解决。