需按网络层→认证层→网关层→业务层逐级排查Agent Space API调用失败问题；必须先开启OpenAI兼容模式，否则返回404或schema mismatch；baseURL须为https://xxx/v1格式，apiKey须为sk-xxx原始密钥；curl测试可定位DNS、连接、认证及服务健康问题。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
Agent Space API接入后出现调用失败、超时、404或响应结构异常等问题，需按网络层→认证层→网关层→业务层顺序逐级验证，跳过任一层都可能把read timeout误判为密钥错误。
确认是否启用OpenAI兼容模式
打开Agent Space控制台 → 进入「API设置」→ 查看「兼容模式开关」是否已开启。关闭状态时，所有请求都会返回404或schema mismatch错误。【未开启此开关则后续所有配置均无效】
若页面无该选项，说明当前版本不支持原生兼容，必须使用中转网关。
检查opencode.json配置是否合法
方法一：核对baseURL格式
baseURL必须以https://开头，末尾必须带/v1，例如https://api.dreamrouter.dev/v1；多一个斜杠（如/v1/）或少一个（如/v1/chat/completions）都会导致400错误。
方法二：验证apiKey与baseURL配对关系
⚠️ apiKey字段填的是Agent Space原始密钥（sk-xxx），不是DreamRouter的token；baseURL填的是中转地址，二者不可互换。
方法三：用opencode --debug验证流式响应
执行命令后观察输出：若卡在“connecting”阶段，是connect timeout；若卡在“waiting for first chunk”，是read timeout或后端未返回event-stream头。
分层定位故障点
第一步：测试DNS与TCP连通性
运行curl -v https://your-agentspace-domain/v1/models，观察time_namelookup和time_connect值。若time_connect > 2s，检查/etc/resolv.conf或更换DNS为8.8.8.8。
第二步：绕过SDK直连网关
用curl模拟请求：curl -X POST https://your-agentspace-domain/v1/agents/xxx/run -H "Authorization: Bearer sk-xxx" -d '{"input":"test"}'。若返回504，说明Nginx proxy_read_timeout设置过短；若返回401，确认密钥是否复制完整、有无前后空格。
第三步：验证后端服务健康状态
登录Agent Space部署节点，执行curl -s http://localhost:8000/health。返回非200表示内部服务已宕机，此时修改客户端配置无意义。
第四步：检查工具调用链路参数
若仅特定工具报错（如Industry Research Agent返回空结果），查看日志中是否含“invalid industry name”或“database connection refused”——这属于业务层错误，需单独检查工具注册参数与下游依赖。
