密钥与认证
API Key 无效或已过期（401）
最常见原因是复制了列表里的遮罩文本（sk-••••...••••）。使用目标行的"显示 / 复制"按钮获取完整值。新建密钥后稍等片刻再验证；仍失败则检查有效期与配额，必要时删除重建。
额度不足（402）
前往控制台充值或购买资源包；先在账单页确认消耗曲线是否正常，排除密钥泄露后的异常调用。
编码工具
模型选择器里没有 yunzhi / claude 配置不生效
运行 yunzhi-helper，进入对应工具的管理菜单选择配置装载/配置刷新，然后完全退出并重启工具（OpenCode TUI / Claude Code）。配置只在新进程启动时加载。
Claude Code 仍然打开 Anthropic 登录页
按上一条刷新配置后用 /status 核对：base URL 应为根端点 https://maas.piteyun.com（多写 /v1 会 403）。不要用网页登录绕过网关。
Codex 无法接入
当前平台未上线 OpenAI Responses API，Codex 0.154+ 已移除 chat 协议，属预期状态。详见配置 Codex 页顶部说明。
调用行为
SDK 读不到 choices
非流式响应是包裹结构，取 body.data.choices；流式是标准 OpenAI SSE。优先使用流式可完全避开这个问题。
模型列表里没有预期的模型
模型随套餐与上游变化。运行 Helper 的"刷新模型列表"重新拉取；确认密钥属于正确的工作空间。不要手动填写列表中不存在的模型 ID。
回复内容为空但 tokens 有消耗
推理模型会把大部分 token 花在思考上。用流式并读取 reasoning_content / thinking block，或在请求中明确要求简短作答。
其他
如何彻底恢复某个工具的官方登录
Helper 对应工具菜单里提供一键清除（Claude Code 有"清除网关配置"；OpenCode / Codex 删除对应配置段或文件后重启工具即可）。
哪里能看到消耗与账单
控制台的用量页按密钥维度统计，支持余额预警。建议给不同用途分配独立密钥，便于归因。