故障排查
一句话总结：先看本页对照表，多数问题能就地解决；如果需要提 issue，请附上 Claw 版本、Claw 日志、相关报错截图。
适用场景
- 安装、登录、连接 Claw 时报错。
- Agent 跑半天没回应或卡在等待输入。
- 推送、下载、自更新偶发失败。
现象对照表
| 现象 | 第一步做什么 |
|---|---|
| 装不上 Claw | curl -fsSL .../install/claw.sh 单独跑一遍看错误 |
| Claw 离线 | 查看 Claw 管理页日志 + Admin 服务可达性 |
| Agent 不回复 | 检查 LLM Connection 是否有效，看右下角错误 |
| 推送不到达 | 检查系统通知权限 + Admin FCM/APNs 凭据 |
| 下载链接 404 | 等几秒重试；下载源会自动回退 |
安装类报错
spawn node ENOENT
通常是运行环境 PATH 缺失。Claude Code Driver 已在启动前自动补齐 Node 路径；如仍出现，确认 Claw 进程加载了最新代码。
Failed to authenticate. API Error: 403 ... Request not allowed
API Key 与 OAuth 登录态冲突，或 key 无权限。当前本地 override 优先走 OAuth；如仍报错先确认 Claude Code 已完成登录。
Not logged in · Please run /login
本机 Claude Code OAuth 会话不存在或失效，执行 /login 后重试。
连接类问题
- Claw 一直显示离线：在主机上执行
journalctl --user -u myclaws-claw -n 200（Linux）或launchctl list io.myclaws.claw（macOS）确认服务在跑；然后看 Claw 日志最后几条。 - 直连地址改了但旧会话没切换：旧会话需要手动重连；新会话立即用新地址。
LLM 类问题
- 流式响应一直没出：检查 Connection 的 Base URL；OpenRouter / Custom 必须填正确路由。
token limit exceeded：在 Connection 中调整上下文窗口大小，或手动/compact压缩。- Codex / Claude Code 子代理失败：检查工具是否选了专属 Connection；prefer
reclaude或独立 OAuth。
推送类问题
- iOS 不响应：检查 ATS 配置 + APNs 凭据。
- Android FCM 大陆送达率低：切到 JPush 通道。
- 后台通知没出：系统通知权限可能被关；App 内消息中心正常表示链路 OK，只是通知层断了。
下载类问题
/download跳转到 404：服务端会自动回退到原生 OSS 域名https://<bucket>.oss-<region>.aliyuncs.com或 GitHub Release。- APK 下载需要勾选未知来源：移动端浏览器安全策略。
各端日志位置
- Claw runtime 日志：
~/.myclaws/claw/logs/与服务日志（systemd / launchd）。 - Admin 日志：取决于部署方式（PM2 / Docker / Systemd）。
- Client 桌面端日志：见 Electron 默认日志路径。
提 issue 时要附的信息
提 issue 时务必附环境信息
Claw 版本、运行平台、报错截图与最近 Claw 日志（脱敏后）能极大缩短排查时间。
自更新失败可手工再跑一次安装脚本
不会破坏数据；Canonical 路径与服务身份不变。
跨主机迁移属于高风险动作
备份 ~/.myclaws/claw/data/ 后再操作；遇到不可恢复问题可重新安装并恢复数据。