OpenSquilla OpenSquilla
文档导航
文档 / 排障

排障

从以下命令开始：

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。

为 Bug 报告收集诊断信息

一个操作即可收集维护者所需的全部信息：

  • CLI：opensquilla bundle —— 即使 gateway 无法启动也能工作。
  • **Web UI：**Logs 页面 → Diagnostic bundle 按钮。
  • **桌面应用：**应用菜单 → Download Diagnostics…（如果应用无法连接到其 gateway，则会改为打开日志文件夹）。

该 bundle 是一个单独的 zip 文件，包含 gateway 日志、近期错误记录、router 决策与 trace 切片、一份离线健康报告，以及已抹除全部密钥的配置。本地路径会被 规范化为 ~，并且对话内容会被排除在外，除非你显式选择包含 （--include-content 或对话框中的复选框）。请将该 zip 附加到你的 GitHub issue 上。

当某个 turn 失败时，错误信息末尾会带有类似 (ref: a1b2c3d4) 的引用代码。 请在报告中引用该代码 —— 它能把你的描述直接关联到 bundle 中记录的错误。

日志所在位置

  • CLI/gateway 安装：~/.opensquilla/logs/（debug.log 是滚动的 gateway 日志；gateway.log 捕获守护进程化后的 stdout）。
  • 桌面应用（macOS）：~/Library/Application Support/OpenSquilla/logs/ （打包构建）或 ~/Library/Application Support/@opensquilla/desktop-electron/logs/ （开发构建）—— desktop.log 是应用生命周期日志， gateway.log 是内嵌 gateway 的输出。gateway 自身的状态位于它们旁边的 opensquilla/state/ 下。

端口已被占用

使用其他端口：

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。

在 macOS 终端安装上，LightGBM 可能需要系统的 OpenMP 运行时。如果启动日志中出现来自 lightgbm/lib/lib_lightgbm.dylib 的 Library not loaded: @rpath/libomp.dylib， 请安装它并重启 gateway：

brew install libomp
opensquilla gateway restart

桌面应用会捆绑其所需的原生运行时；此恢复步骤仅适用于终端或源码安装。

搜索不可用

查看 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、IQS、Tavily 或 Exa：

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

export IQS_SEARCH_API_KEY="..."
opensquilla configure search --search-provider iqs --api-key-env IQS_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。

Docker：其他机器无法访问 Web UI

compose 的默认端口发布仅限回环地址 （127.0.0.1:18791:18791），因此其他设备无法访问 gateway。 请改为在所有网卡上发布端口 —— 并先配置 token 认证：

ports:
  - "18791:18791"

保持 OPENSQUILLA_LISTEN 为 0.0.0.0；暴露与否由 ports 映射控制， 而非由绑定地址控制。如果宿主机运行了防火墙，请允许来自局域网的 TCP 18791 入站连接。完整流程见： docker.md。

Docker：Web UI 能连上但配置更改被拒绝

容器化的 gateway 绑定通配地址，因此每个浏览器 —— 包括宿主机本机上的 浏览器 —— 都被视为远程操作者。没有 token 的远程操作者可以聊天， 但不能管理配置或 onboarding。请启用 token 认证：

environment:
  OPENSQUILLA_AUTH_MODE: token
  OPENSQUILLA_AUTH_TOKEN: ${OPENSQUILLA_AUTH_TOKEN:?generate one with openssl rand -hex 32}

将 token 的值放在 compose.yaml 旁边一个被 git 忽略的 .env 文件中， 然后在 URL 中携带 token 登录：

http://<server-address>:18791/control/?token=<value>

请专门使用 token 模式 —— password 和 trusted-proxy 模式不支持 Web UI 连接。如果这些变量没有生效，state 卷中的 config.toml 可能 已经包含了一个 [auth] 表 —— 启动时 TOML 的值优先于 OPENSQUILLA_AUTH_*；请在那里（或在 Web UI 中）修改 token 并重启。

Docker：Gateway 在 bind mount 的 state 目录上启动失败

容器以非 root 的 UID 10001 运行。归属于其他用户的 bind mount 目录 不可写，gateway 会在创建数据库时失败。将目录所有权交给容器用户并重启：

sudo chown -R 10001:10001 /srv/opensquilla
docker compose up -d

默认的命名卷（opensquilla-state）没有这个问题 —— 镜像会以正确的 所有者预创建 state 根目录。

Docker：构建失败并提示 “model assets are unavailable”

docker build 会校验捆绑的 router 模型，并拒绝把 Git LFS 指针文件 烘焙进镜像。构建前请先拉取实际文件（在 Debian 上 git-lfs 是与 git 分开的软件包）：

sudo apt install -y git git-lfs
git lfs pull --include="src/opensquilla/squilla_router/models/**"
docker build -t opensquilla:local .

预构建镜像可完全避免此问题 —— 参见 docker.md。

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

在 GitHub 上编辑此页(英文原稿) OpenSquilla 文档 · 中文社区翻译