# 故障排除
# 最初的六十秒
按顺序运行这些命令：
bash
opensoul status
opensoul status --all
opensoul gateway probe
opensoul logs --follow
opensoul doctor如果 Gateway 网关可达，进行深度探测：
bash
opensoul status --deep# 常见的“它坏了”情况
# opensoul: command not found
几乎总是 Node/npm PATH 问题。从这里开始：
# 安装程序失败（或你需要完整日志）
以详细模式重新运行安装程序以查看完整跟踪和 npm 输出：
bash
curl -fsSL https://opensoul.ai/install.sh | bash -s -- --verbose对于 beta 安装：
bash
curl -fsSL https://opensoul.ai/install.sh | bash -s -- --beta --verbose你也可以设置 OPENSOUL_VERBOSE=1 代替标志。
# Gateway 网关“unauthorized”、无法连接或持续重连
# 控制 UI 在 HTTP 上失败（需要设备身份）
# docs.opensoul.ai 显示 SSL 错误（Comcast/Xfinity）
一些 Comcast/Xfinity 连接通过 Xfinity Advanced Security 阻止 docs.opensoul.ai。 禁用 Advanced Security 或将 docs.opensoul.ai 添加到允许列表，然后重试。
- Xfinity Advanced Security 帮助：https://www.xfinity.com/support/articles/using-xfinity-xfi-advanced-security
- 快速检查：尝试移动热点或 VPN 以确认这是 ISP 级别的过滤
# 服务显示运行中，但 RPC 探测失败
# 模型/认证失败（速率限制、账单、“all models failed”）
# /model 显示 model not allowed
这通常意味着 agents.defaults.models 配置为允许列表。当它非空时，只能选择那些提供商/模型键。
- 检查允许列表：
opensoul config get agents.defaults.models - 添加你想要的模型（或清除允许列表）然后重试
/model - 使用
/models浏览允许的提供商/模型
# 提交问题时
粘贴一份安全报告：
bash
opensoul status --all如果可以的话，包含来自 opensoul logs --follow 的相关日志尾部。