OpenSquilla：跨平台私有化AI Agent框架，统一WebUI/CLI/多IM渠道交互

一、OpenSquilla是什么

OpenSquilla 是基于 Apache-2.0 开源协议、Token高效型微内核AI智能体框架，项目灵感源自 OpenClaw，支持 Windows、macOS、Linux、Docker 全平台私有化本地部署。

项目核心定位：同等大模型预算下，实现更强AI智能体能力、更低推理成本。区别于传统AI Agent固定绑定单一模型，OpenSquilla 搭载本地SquillaRouter路由引擎，在设备本地完成任务分级判断，自动分配性价比最高的大模型处理每一轮对话，同时统一提供WebUI可视化控制台、终端CLI、主流社交聊天渠道三套交互入口，所有交互共享同一套任务执行循环，工具调用、重试机制、日志记录行为完全统一。

它兼顾个人开发者、企业自动化运维、办公协作、代码开发多场景，内置持久化本地记忆、分层安全沙箱、联网搜索、文档生成、定时任务、多子代理等完整能力，原生兼容20+国内外主流大模型服务商，无需修改代码即可快速切换模型厂商。

二、功能特色

1. 本地SquillaRouter智能模型路由（核心差异化优势）

内置基于LightGBM+ONNX的本地分类器，任务复杂度判断全程本地运行，无需上传文本至第三方。通过文本长度、语言类型、代码片段、关键词、语义向量多维度打分，将任务分为T0-T3四档，自动匹配最低成本且能完成任务的LLM；简单问答调用轻量低价模型，复杂代码/长推理任务自动切换高端模型。官方基准测试显示，对比全程使用Claude Opus 4.7方案，总Token成本降低约90%，任务平均分几乎无衰减（0.9251 vs 0.9255）。支持一键关闭路由，直连单一模型。

2. 全兼容多LLM厂商插件层

插件化Provider架构，原生对接20+主流大模型平台：OpenRouter、OpenAI、Anthropic、Ollama、DeepSeek、Gemini、通义千问DashScope、Moonshot、vLLM、LM Studio、硅基流动等，统一配置文件规范，切换服务商无需修改业务代码，支持主模型+故障备用模型自动切换。

3. 统一多端交互网关

内置Starlette ASGI网关服务，默认本地端口18791，三大交互入口共用任务引擎：

• WebUI可视化控制台：http://127.0.0.1:18791/control/，可视化配置模型、记忆、渠道、定时任务；

• 终端CLI：完整命令集，支持一键初始化、配置、启动、迁移、成本统计；

• 多IM聊天渠道：飞书、钉钉、企业微信、QQ、Telegram、Discord、Slack、Matrix等，支持websocket/轮询/公网Webhook双模式接入。

4. 按需加载MCP技能系统

内置15款开箱即用原生技能：代码调试、GitHub操作、定时任务、Office文档生成（PPTX/Word/Excel/PDF）、网页摘要、天气预报、文件处理等；支持MCP客户端/服务端双向兼容，技能仅在任务触发时加载，减少内存占用；开发者可自定义、发布私有技能。

5. 本地持久化分层记忆

采用SQLite存储会话、对话记录，搭配全文检索sqlite-vec向量语义检索双重记忆召回：

• 短期会话记忆：保存单次对话上下文；

• 长期持久记忆：MARKDOWN笔记存储，支持向量归一化检索、关键词兜底匹配；

• 可选记忆衰减、梦境知识合并优化，向量嵌入本地ONNX运行，也可切换OpenAI/Ollama向量服务。

6. 三层安全沙箱防护

Standard/Strict/Locked三级权限管控矩阵，Linux平台支持Bubblewrap代码隔离，Windows暂未提供沙箱执行；内置拒绝日志，多次拒绝高危操作自动暂停自主运行；所有工具输出XML转义，抵御提示注入攻击；敏感工具调用强制人工审批（人在回路）。

7. 内置全链路工具能力

原生集成文件读写、终端进程执行、Git操作、Brave/DDG联网搜索（SSRF安全拦截）、多格式文档生成、AI图像生成、TTS文本转语音；支持定时Cron自动化任务、深度子代理嵌套、Token/费用统计、全链路诊断日志。

8. 一键跨框架数据迁移

原生支持 OpenClaw、Hermes Agent 数据迁移，可导入记忆、人设、技能、渠道配置，支持预演迁移报告、冲突处理、密钥同步，降低用户迁移成本。

三、技术细节

1. 底层运行环境：基于Python 3.12开发，使用uv做环境隔离与依赖管理，提供Windows便携包（内置独立Python运行时，无需本地安装Python）、源码编译、Docker镜像三种部署模式；Windows路由依赖VC++运行库，便携安装包自动一键部署。

2. 网关架构：ASGI异步网关，WebSocket RPC长连接支撑WebUI与多渠道实时通信，单进程承载全部交互入口，无多实例数据割裂问题。

3. 路由推理底层：SquillaRouter基于ONNX Runtime本地推理，轻量LightGBM分类模型，无云端推理开销，离线环境可完整运行模型调度。

4. 存储架构：SQLite持久化会话、定时任务、渠道状态；本地文件存储记忆文档、配置文件；向量检索基于sqlite-vec轻量化向量库，无需额外向量数据库。

5. 扩展机制

• Extras可选依赖：matrix加密聊天、PDF文档增强、MCP协议扩展；

• 配置加载优先级：环境变量 > 自定义配置文件路径 > 当前目录opensquilla.toml > 用户目录配置 > 内置默认配置；

6. 版本迭代优化（0.2.0/0.2.1核心改进）

• 0.2.0：新增跨框架迁移、完整CLI聊天终端、时区Cron定时、优化IM渠道适配、子代理并发管控；

• 0.2.1：修复Windows便携启动依赖检测、优化超长工具结果容错、WebUI展示优化、向量检索归一化修复、长会话稳定性提升。

四、适用应用场景

1. 个人开发者本地AI助手：代码自动编写、项目调试、Git自动化、文档批量生成、本地文件批量处理，依靠SquillaRouter大幅降低API调用成本。

2. 企业办公自动化：飞书/钉钉群聊智能机器人，自动生成会议纪要、定时报表推送、数据查询、周报自动撰写，支持定时Cron任务无人值守运行。

3. 私有知识库问答：本地文档向量记忆，离线检索企业内部资料，数据不上传第三方云端，满足数据保密需求。

4. 多模型统一调度平台：企业同时采购多款大模型API，通过OpenSquilla自动分流任务，控制AI调用成本。

5. 运维自动化：服务器定时巡检、日志分析、批量脚本执行，搭配WebUI远程监控智能体运行状态。

6. 二次开发MCP智能体：基于微内核架构定制垂直领域Agent，搭建私有化AI客服、行业数据分析机器人。

五、主流使用方法（三大部署方案）

方案1：Windows便携包（新手首选，无需Python）

1. 下载官方便携压缩包：https://github.com/opensquilla/opensquilla/releases/latest/download/OpenSquilla-windows-x64-portable.zip

2. 解压至可读写文件夹，右键Start OpenSquilla.cmd以管理员身份运行；

3. 首次启动运行交互式初始化向导，填入LLM服务商API密钥；

4. 访问 http://127.0.0.1:18791/control/ 进入Web控制台。

方案2：跨平台终端快速安装（全系统推荐）

1. 安装uv包管理器

• Mac/Linux：

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

- Windows PowerShell：

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

2. 一键安装0.2.1正式版

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

3. 初始化并启动网关

  opensquilla onboard
  opensquilla gateway run

方案3：源码部署/开发调试

1. 拉取源码并同步LFS模型资产

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

2. 生产环境安装

  # Mac/Linux
  bash scripts/install_source.sh
  # Windows PowerShell
  .\scripts\install_source.ps1

3. 开发调试环境（修改源码专用）

  uv sync --extra recommended --extra dev
  uv run opensquilla --help

方案4：Docker容器部署

1. 源码目录构建本地镜像

  docker build -t opensquilla:local .

2. 一键启动容器服务

  ./start.sh # Windows使用start.ps1
  docker compose up -d

六、竞品对比表格

七、常见问题解答（FAQ）

Q1：启动时报DLL load failed，onnxruntime加载失败如何解决？

A：该报错为Windows缺少VC++ 2015-2022运行库。便携包安装会自动部署，uv快速安装方式需手动下载安装微软官方vc_redist.x64.exe；安装完成后执行opensquilla gateway restart重启网关即可恢复SquillaRouter路由功能，缺失运行库时智能体可正常运行，但会关闭自动模型分流，仅使用单一模型。

Q2：如何关闭自动模型路由，固定使用单一LLM？

A：初始化向导执行opensquilla onboard --router disabled；也可后期修改配置：opensquilla configure router --router disabled，重启网关生效。如需重新开启路由，将参数修改为recommended。

Q3：公网其他设备如何访问WebUI控制台？

A：启动网关时绑定0.0.0.0全网卡监听：opensquilla gateway run --listen 0.0.0.0 --port 18791；同时防火墙/云服务器安全组放行18791端口，必须配置访问Token鉴权，禁止无认证暴露公网。

Q4：如何从OpenClaw旧项目迁移全部配置与记忆？

A：先执行预演查看迁移内容：opensquilla migrate openclaw --json；确认无冲突后执行正式迁移：opensquilla migrate openclaw --apply；如需同步密钥，增加--migrate-secrets参数。Hermes迁移命令逻辑一致，替换源名称即可。

Q5：离线无网络环境能否完整运行OpenSquilla？

A：可以。提前完整拉取Git LFS路由模型资产，安装全部依赖缓存；关闭联网搜索功能，仅本地模型路由、记忆、文件工具可离线完整运行，仅LLM调用仍需对应模型服务商网络（本地Ollama模型可完全断网）。

Q6：安装后终端输入opensquilla提示命令不存在怎么办？

A：uv安装完成后新开终端窗口；执行uv tool update-shell刷新环境变量；Windows可手动追加%USERPROFILE%\.local\bin至系统PATH。

Q7：IM聊天渠道连接失败如何排查？

A：修改渠道配置后必须重启网关opensquilla gateway restart；执行opensquilla channels status 渠道名 --json查看状态，仅enabled、configured、connected同时为true代表正常连通；飞书/钉钉websocket模式无需公网IP，Webhook模式需要公网可访问地址。

八、相关链接

• GitHub仓库：https://github.com/opensquilla/opensquilla

九、总结

OpenSquilla 是一款聚焦AI调用成本优化的开源微内核AI智能体，依托本地离线SquillaRouter模型路由引擎实现行业独有的任务分级调度，在不降低智能体任务完成质量的前提下大幅削减大模型API开销，同时兼顾全平台轻量化部署、20+主流大模型兼容、多渠道统一交互、本地隐私记忆、分层安全管控与跨旧框架一键迁移能力，相比OpenClaw、Hermes Agent具备更突出的成本控制优势，适合预算敏感的个人开发者、需要多模型统一调度的中小企业，同时提供便携包、终端、Docker、源码四类部署方案，覆盖新手快速上手与开发者二次开发全需求，完整的CLI命令与可视化Web控制台大幅降低AI智能体搭建与运维门槛。