opensquilla/opensquilla · 上手攻略

  • 仓库：opensquilla/opensquilla
  • 链接：https://github.com/opensquilla/opensquilla
  • 分类：AI Agent / LLM Router / 本地推理
  • 作者：Jay
  • 更新：2026-07-13

这是什么

OpenSquilla 是一个token 高效的微内核 AI Agent 框架，核心理念是"同等预算，更多能力"（Same budget, more capability）。它用一个本地模型路由器（SquillaRouter）自动把每个对话回合路由到「最便宜且能胜任」的模型，同时配备持久记忆、分层沙箱、内置网页搜索和端侧 Embedding，所有入口（Web UI、CLI、聊天频道）共用同一 turn 循环，工具分发和重试行为完全一致。

简单说：你在本地跑一个 Agent 网关，SquillaRouter 负责判断"这个问题该用哪个模型"，每次都尽量用最便宜的模型完成任务，省 token、省预算，同时不损失质量。

解决什么问题

  • 多模型选择困难：同时跑多个 LLM 提供商（OpenAI、Anthropic、DeepSeek、Qwen/DashScope、Ollama 等 20+）时，不知道该把请求发哪个，OpenSquilla 自动路由。
  • Token 成本高：不用每个任务都调最贵的模型，本地路由器会在精度和成本之间做权衡。
  • Agent 状态管理复杂：记忆、沙箱、工具调用分散在不同模块，维护成本高；OpenSquilla 用统一 turn 循环把这一切串起来。
  • 多平台部署繁琐：同一个 Agent 要在 CLI、Web UI、Slack/Discord/飞书等多个渠道跑，行为不一致。OpenSquilla 各渠道共用同一核心逻辑。

快速安装

桌面安装（推荐桌面用户）

下载 DMG（macOS ARM64）或 EXE（Windows x64），拖入 Applications 或直接运行：

  • macOS ARM64：https://github.com/opensquilla/opensquilla/releases/download/v0.5.0rc3/OpenSquilla-0.5.0-rc3-mac-arm64.dmg
  • Windows x64：https://github.com/opensquilla/opensquilla/releases/download/v0.5.0rc3/OpenSquilla-0.5.0-rc3-win-x64.exe

⚠️ Windows 版目前无代码签名，SmartScreen 会报警，点"更多 info → 仍然运行"即可。

快速终端安装（跨平台，推荐）

推荐用 uv 安装，不依赖系统 Python：

# 1. 安装 uv（Linux/macOS）
curl -LsSf https://astral.sh/uv/install.sh | sh
source "$HOME/.local/bin/env"

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

# 2. 安装 OpenSquilla
uv tool install --python 3.12 "opensquilla[recommended] @ https://github.com/opensquilla/opensquilla/releases/download/v0.5.0rc3/opensquilla-0.5.0rc3-py3-none-any.whl"

# 3. 配置并运行
opensquilla onboard
opensquilla gateway run

📌 Python 版本要求 3.12+。如果 opensquilla 命令找不到，重开终端或重新执行 source "$HOME/.local/bin/env"（Linux/macOS）。

从源码安装（追踪主分支）

git lfs install
git clone https://github.com/opensquilla/opensquilla.git
cd opensquilla
git lfs pull --include="src/opensquilla/squilla_router/models/**"
# Linux/macOS
bash scripts/install_source.sh
# Windows
powershell -ExecutionPolicy Bypass -File ./scripts/install_source.ps1

开发源码模式（修改代码）

git clone https://github.com/opensquilla/opensquilla.git
cd opensquilla
uv sync --extra recommended --extra dev
uv run opensquilla --help

核心用法

基础命令

opensquilla onboard          # 首次配置向导
opensquilla gateway run      # 启动网关（前台运行）
opensquilla channels status  # 查看已配置渠道状态

# 卸载
opensquilla uninstall --dry-run  # 预览卸载内容
opensquilla uninstall            # 卸载但保留数据
opensquilla uninstall --purge-all  # 删除所有数据

配置文件位置

配置文件在 ~/.opensquilla/config.toml，首次运行 opensquilla onboard 时生成引导。

支持的 LLM 提供商（20+）

内置支持：TokenRhythm、OpenRouter、OpenAI、Anthropic、Ollama、DeepSeek、Google Gemini、Qwen/DashScope 等，通过统一 provider 层接入，无需改代码。

渠道（Channel）接入

基础安装已支持飞书、Telegram、DingTalk、QQ、企业微信、Slack、Discord 等主流 IM。Matrix 渠道需额外安装：

# 依赖 matrix 插件
OPENSQUILLA_INSTALL_EXTRAS=matrix bash scripts/install_source.sh

SquillaRouter 本地路由器

默认安装会带上 SquillaRouter（ONNX 运行时 + LightGBM），它根据对话历史判断该用哪个模型。如需关闭：

opensquilla onboard  # 选 --router disabled

或配置环境变量：

OPENSQUILLA_INSTALL_PROFILE=core  # 仅装核心运行时，不装路由器

隐私开关

OpenSquilla 默认收集匿名安装遥测（仅版本/OS/架构，无 API Key/对话内容）。关闭方法：

OPENSQUILLA_PRIVACY_DISABLE_NETWORK_OBSERVABILITY=true

或 config.toml 中设：

[privacy]
disable_network_observability = true

典型适用场景

场景 说明
多模型混用 同时接入多个 LLM 提供商，希望自动选择最优性价比模型
本地 AI 路由 本地部署的 Ollama/Qwen 模型配合云端 API，统一调度
跨渠道 Agent 同一个 Agent 同时跑在 Discord、飞书、Telegram，行为一致
Token 成本控制 高频调用场景，用本地路由器自动降级到便宜模型
需要持久记忆 Agent 需要跨会话记住上下文，而非每次重置

坑与注意

  1. Windows 缺 VCRuntime：Windows 快速终端安装后，SquillaRouter 可能报 DLL load failed，需手动安装 Visual C++ Redistributable。从源码安装的 PowerShell 脚本会自动用 winget 装。

  2. macOS 缺 libomp：终端安装后 SquillaRouter 报 Library not loaded: @rpath/libomp.dylib，运行 brew install libomp 即可解决。桌面版已自带运行时，不受影响。

  3. Windows 升级注意：从 RC3 升级到 RC4+ 时，不要先卸载 RC3（卸载脚本可能清掉 Desktop 用户数据），直接覆盖安装。RC4 以后才支持正常卸载保留数据。

  4. uv 路径问题：uv tool install 后 opensquilla 命令找不到，通常是 ~/.local/bin 还未加入 PATH，重新执行安装时的 source 命令或重开终端即可。

  5. Git LFS 必需：源码安装必须先跑 git lfs pull --include="src/opensquilla/squilla_router/models/**"，否则路由器模型文件是空指针占位符，路由功能失效。

  6. Python 3.12 以下不支持：核心依赖要求 Python 3.12+，老系统注意版本。

与同类对比

维度 OpenSquilla Dify / LangFlow AutoGen crew.ai
定位 微内核路由 Agent 可视化工作流编排 多 Agent 对话框架 Agent 团队编排
路由能力 ✅ 本地 SquillaRouter ❌ 手动选模型 ❌ ❌
多渠道 ✅ 飞书/Slack/Discord/Telegram ❌ ❌ ❌
Token 效率优化 ✅ 核心设计目标 ❌ ❌ ❌
学习曲线 低 中 中高 中
持久记忆 ✅ 内置 ✅ 部分 部分
上手难度 简单 中 中 中

OpenSquilla 最大差异化：它是唯一一个把「token 高效路由」作为核心目标的 Agent 框架，而不是事后加的插件。其他框架更多关注工作流编排或多 Agent 协作。

一句话推荐结论

如果你在多模型混用或高频调用的场景下关注 token 成本，OpenSquilla 的本地路由器 + 统一 turn 循环是当前市面上少见的开箱即用方案，安装简单、渠道覆盖广，值得一试。