排障

从以下命令开始：

opensquilla doctor
opensquilla doctor --json
opensquilla gateway status

当 gateway 运行时，http://127.0.0.1:18791/control/ 的 Web UI 健康视图也会报告就绪状态与恢复步骤。

找不到 `opensquilla` 命令

执行 uv tool install 之后，打开一个新终端或运行：

uv tool update-shell

检查可执行文件：

command -v opensquilla

在 Windows PowerShell 上：

where.exe opensquilla

Gateway 未运行

启动它：

opensquilla gateway run

或使用托管的后台进程：

opensquilla gateway start --json
opensquilla gateway status

打开：

http://127.0.0.1:18791/control/

如需聚焦的 gateway 指南，参见 gateway.md。

桌面 Gateway 启动报告迁移锁

首次运行期间，桌面应用会启动本地 gateway 并在打开 Control UI 之前应用待执行的 SQLite 迁移。如果启动被中断，gateway 可能会报告针对 sessions.db 的 yoyo 迁移锁。

当锁记录仅指向已失效或无效的进程 id 时，近期版本会自动恢复。当任何已记录的 pid 仍处于存活状态时，gateway 会让迁移失败保持显眼，并且不会清除该锁。

在桌面 gateway 日志中检查以下事件：

migrator.lock_timeout
migrator.stale_lock_cleared
migrator.lock_held_by_live_process
migrator.stale_lock_retry_failed

如果日志显示该锁被一个存活进程持有，请等待该 gateway 完成启动，或干净地停止该进程。除非你已确认所记录的进程不再运行，否则不要删除 yoyo_lock 记录或运行 yoyo break-lock。

端口已被占用

使用其他端口：

opensquilla gateway run --port 18792

或停止托管的 gateway：

opensquilla gateway stop

Provider 未配置

运行：

opensquilla onboard
opensquilla providers list
opensquilla providers configure openrouter

使用环境变量保管密钥：

export OPENAI_API_KEY="sk-..."
opensquilla configure provider --provider openai --api-key-env OPENAI_API_KEY

Router 依赖问题

如果 SquillaRouter 无法加载，OpenSquilla 仍可使用直接模型路由运行。要禁用 router：

opensquilla configure router --router disabled
opensquilla gateway restart

在 Windows 上，ONNX Runtime 可能需要 Visual Studio 2015-2022 x64 的 Visual C++ Redistributable。安装后重启 shell 与 gateway。

搜索不可用

查看 search providers：

opensquilla search list
opensquilla search status

使用 DuckDuckGo 作为无需 key 的路径：

opensquilla configure search --search-provider duckduckgo

使用带 key 的 Brave：

export BRAVE_SEARCH_API_KEY="..."
opensquilla configure search --search-provider brave --api-key-env BRAVE_SEARCH_API_KEY

当你的工作流需要时效性或更丰富的来源内容时，使用 Bocha、Tavily 或 Exa：

export BOCHA_SEARCH_API_KEY="..."
opensquilla configure search --search-provider bocha --api-key-env BOCHA_SEARCH_API_KEY

export TAVILY_API_KEY="..."
opensquilla configure search --search-provider tavily --api-key-env TAVILY_API_KEY

export EXA_API_KEY="..."
opensquilla configure search --search-provider exa --api-key-env EXA_API_KEY

对于无 key、部分 key 或全部 key 的配置，查看生效的运行时状态：

opensquilla search status --json

Channel 配置已保存但 channel 离线

编辑 channel 配置后重启 gateway：

opensquilla gateway restart
opensquilla channels status <name> --json

对于 webhook channels，请确认 provider 可访问到 gateway，并且回调 secret 一致。

某个 tool 被拒绝

检查 sandbox 与权限状态：

opensquilla sandbox status
opensquilla doctor

对于一次性运行，选择明确的权限姿态：

opensquilla agent --permissions restricted -m "Read only"
opensquilla agent --permissions full -m "Trusted local automation"

Agent 似乎忘记了旧的上下文

长 session 可能会对旧历史进行 compaction。这在上下文压力下属于预期行为。

查看 sessions：

opensquilla sessions show <session-key>
opensquilla sessions export <session-key>

如果精确的旧文本很重要，请将其保存在文件、memory 笔记或导出的 session 中。

某个 turn 过于昂贵或缓慢

尝试：

opensquilla configure router --router recommended
opensquilla diagnostics on
opensquilla cost

对于自动化：

opensquilla agent --max-iterations 20 --timeout 600 -m "Bounded task"

对于较大的工具输出，参见 features/tool-compression.md。

文档索引 · 产品指南 · 改进本页 · 反馈文档问题

排障

找不到 opensquilla 命令