opensquilla

环境要求

• Python 3.12+（用 uv 安装时会自动管理 Python，无需系统 Python）
• 操作系统：Windows、macOS 或 Linux
• 首次安装需联网下载依赖（ONNX Runtime、LightGBM、NumPy、tokenizers 等）
• 仅源码安装需要 Git + Git LFS 及 Node.js/npm（release wheel 与桌面版不需要）

安装与启动步骤

1. 1安装 uv（Mac/Linux）

   用官方脚本安装 uv 工具链，它会把 OpenSquilla 装进独立环境并自带 Python。若 uv --version 已可用可跳过。

   curl -LsSf https://astral.sh/uv/install.sh | sh
   . "$HOME/.local/bin/env"

   复制

2. 2安装 uv（Windows）

   Windows PowerShell 下安装 uv，安装后把 .local\bin 加入当前会话 PATH，避免找不到命令。

   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
   $env:Path = "$env:USERPROFILE\.local\bin;" + $env:Path

   复制

3. 3安装 OpenSquilla

   从 GitHub Release 拉取 0.5.4 wheel 并安装 recommended 附加依赖（含 SquillaRouter 运行时），首次安装需要联网。

   uv tool install --python 3.12 "opensquilla[recommended] @ https://github.com/TokenRhythm/opensquilla/releases/download/v0.5.4/opensquilla-0.5.4-py3-none-any.whl"

   复制

4. 4初始化配置

   运行引导程序完成基础配置，按提示填写模型与渠道信息即可。

   opensquilla onboard

   复制

5. 5启动网关

   启动 OpenSquilla gateway，即可通过 CLI、Web UI 与聊天渠道使用智能体。

   opensquilla gateway run

   复制

6. 6桌面版安装（可选）

   macOS 下载 dmg 拖入应用程序；Windows 下载 exe 安装。安装包已内置 Vue 控制台，无需 Node.js。

7. 7源码安装（可选）

   需 Git LFS 拉取模型资产，再运行官方安装脚本（内部会执行 npm ci/build 与 uv tool install）。

   git lfs install
   git clone https://github.com/TokenRhythm/opensquilla.git
   cd opensquilla
   git lfs pull --include="src/opensquilla/squilla_router/models/**"
   bash scripts/install_source.sh

   复制

如何确认成功

安装后终端能执行 opensquilla 命令；运行 opensquilla gateway run 后网关启动即成功。

常见问题

注意事项

• release wheel 与桌面安装包已内置 Vue 控制台，这类安装方式不需要 Node.js 或 npm。
• Windows v0.5.4 官方安装包仍未签名，可能触发 SmartScreen，企业策略受限时可改用终端安装。
• 源码安装每次重装都会重建 node_modules 并重新构建控制台，耗时与磁盘占用较高。
• macOS 桌面版升级前先退出正在运行的应用，再将 DMG 中的 App 拖入「应用程序」。