故障排查
Agent 没回应
检查 Provider 配置、API Key、网络、Hooks 阻断，并按层级隔离问题。
症状
在 Agent 面板里发送消息后没有任何回应：可能是输入框转圈停在 "Thinking..."，可能是直接静默没动静，也可能弹一个红色 toast 然后消失。Agent 不会自己告诉你哪个环节坏了 — 它会把网络、Provider、Hooks、Sidecar 四层的失败都报成"没回应"。
在排查之前先确认一件事：换一个新 chat（Cmd/Ctrl + N），输入 ping 一类的极短问题，再观察行为。如果新 chat 能回 — 那是上下文 / 历史消息的问题；如果新 chat 也卡 — 那是配置或基础设施层的问题。
常见原因
- API Key 过期、被撤销、或被云厂商限速（最常见，占约 60%）
- Provider endpoint 配置错（base URL 缺
/v1、写成了 http 而非 https） - 本地 Go sidecar 进程崩了 — UI 还在，但底层路由没人接
- Hooks 在 PreToolUse 阶段返回了 deny，导致 Agent 拿不到任何工具
- 系统防火墙 / 公司代理拦截 outbound HTTPS
- 账户余额 / 额度耗尽（OpenAI 显示 429，但 UI 没翻译）
逐步诊断
按这个顺序排查 — 从最便宜的检查到最贵的检查：
- Settings → Providers — 看当前激活 provider 后面有没有绿色 "Ready" 标签
- 点 provider 行右边的 "Test" 按钮，它会发一个最小请求，5 秒内返回结果
- 打开 logs 目录（见下方命令），看最近 1 分钟内有没有
error或panic行 - 在 Activity Monitor / Task Manager 里搜
kition-sidecar，确认进程还活着 - 换一个 provider（如临时挂个 Anthropic 而原本用 OpenAI）— 如果换了能跑，问题在原 provider
- 关闭所有 Hooks（Settings → Hooks → 全部 disable），再发一条消息
查日志的常用命令
macOS 在 Terminal 里：
# Tail the live agent log
tail -F ~/Library/Logs/Kition/agent.log
# Find recent errors across all logs
grep -inE "error|panic|429|401|500" ~/Library/Logs/Kition/*.log | tail -40
# Sidecar boot trace (look for "listening on")
grep -i "sidecar" ~/Library/Logs/Kition/main.log | tail -20修复
- Key 失效：去 provider 控制台撤销并重发，回到 Settings → Providers 粘新 key，点 Save → Test
- Sidecar 死掉：菜单栏 Kition → Restart Sidecar（或 Cmd/Ctrl + Shift + R 在 Settings 内）
- Hooks 阻断：Settings → Hooks，看 PreToolUse 里那条规则，临时 disable 或修正它的匹配条件
- 代理 / 防火墙：Settings → Network 里挂 HTTP_PROXY，或让 IT 把
api.openai.com等域名加白名单 - 额度耗尽：去 provider 账户充值 / 升档，等 1 分钟限速重置
应急方案
如果上面都不行，作为临时方案可以：挂一个备用 provider（任何 OpenAI-compatible endpoint 都行 — Together、Groq、自建 vLLM），把它设为默认，先恢复手感。等主 provider 修好再切回。
另外，如果你只是想读已有笔记，编辑器和数据表完全不依赖 Agent — 可以关闭 Agent 面板照常工作。
什么时候该提 bug
- "Test" 按钮成功但实际对话失败 — 说明 router 层有 bug
- Sidecar 反复崩，重启后 30 秒内又死
- 日志里出现
panic:加 Go stack trace - 同一 Key 在官方 Playground 能用、在 Kition 里 401