SKILL.md
QCC Plus 调试排查手册
请求类问题
400 错误
| 检查项 | 解决方案 |
|---|---|
| USER_HASH | 检查是否匹配账号 |
| 预热 | 尝试 NO_WARMUP=1 跳过预热 |
| 系统提示 | 确认使用精简系统提示 MINIMAL_SYSTEM=1 |
工具定义格式错误 (tools.*.custom)
- v3.0.1+ 自动清理工具定义中的非标准字段（如 custom、input_examples）
- 代理会自动移除 Anthropic API 不支持的字段，保留 name/description/input_schema
- 如需查看清理日志，检查代理服务器输出
节点/连接类问题
代理连接失败
| 检查项 | 解决方案 |
|---|---|
| 上游地址 | 检查 UPSTREAMBASEURL 配置 |
| 网络 | 确认网络连通性 |
| 重试 | 查看 PROXYRETRYMAX 重试配置 |
MySQL 连接问题
| 检查项 | 解决方案 |
|---|---|
| DSN 格式 | 检查 PROXYMYSQLDSN 格式 |
| 服务状态 | 确认 MySQL 服务运行状态 |
| 网络 | 检查防火墙和端口配置 |
CI/CD 类问题
健康检查超时
| 检查项 | 解决方案 |
|---|---|
| 版本 | v1.0.1+ 已增强健康检查：10s 初始等待 + 6 次重试 |
| 端口 | 检查服务器端口和防火墙配置 |
| 日志 | 查看部署日志：docker logs qcc_test-proxy-1 |
日志位置
| 组件 | 日志命令 |
|---|---|
| Docker 容器 | docker logs <container_name> |
| 代理服务器 | 标准输出 |
| 健康检查 | 代理服务器日志中的 [health] 标签 |
测试环境参数
| 参数 | 值 |
|---|---|
| 重试次数 | PROXYRETRYMAX=3 |
| 单次超时 | 12/6/3s（递减） |
| 总超时 | RETRYTOTALTIMEOUT_SEC=25 |
| 重试状态码 | RETRYONSTATUS=502,503,504 |
| 健康检查模式 | PROXYHEALTHCHECK_MODE=cli |
| 失败阈值 | PROXYFAILTHRESHOLD=3 |
| 探活间隔 | PROXYHEALTHINTERVAL_SEC=30 |
熔断器配置
| 参数 | 值 |
|---|---|
| 窗口 | 120s |
| 失败率 | 0.8 |
| 连续失败 | 10 次 |
| 冷却时间 | 60s |
| 半开探测 | 5 次 |
常见踩坑
前端页面 CSS 硬编码颜色
- 现象：新页面在深色主题下显示异常
- 原因：直接使用硬编码颜色值而非 CSS 变量
- 解决：使用 CSS 变量（
var(--bg)、var(--text)、var(--border)） - 预防：开发新页面时禁止使用硬编码颜色
Codex 执行卡住无响应
- 现象：
codex exec运行超过 30 分钟无输出 - 原因：网络问题或 API 超时
- 解决：使用
KillShell终止后重试，或设置 timeout - 预防：对于简单分析任务，直接用 Claude 而非 Codex
Shell 转义问题导致 Codex 失败
- 现象：直接传递含特殊字符的 prompt 导致命令解析错误
- 原因：Shell 对引号、换行等字符的转义处理
- 解决：写入临时文件后用
cat file | codex exec - 预防：始终使用临时文件方式调用 Codex