OpenSquilla 深度研究报告

> 版本：v0.3.1 | 开源协议：Apache 2.0 | GitHub Stars：4.1k+ > 研究日期：2026年6月14日

---

一、OpenSquilla 介绍

1.1 项目定位

OpenSquilla 是一个 Token高效的开源微内核 AI Agent 框架，由中国团队（上海基元律动科技）开发。创始人王云鹤（原华为大模型负责人）、CTO 韩凯。首轮融资估值 1 亿美元。项目灵感来源于 OpenClaw（俗称"小龙虾"），以 Python 重写，融入智能路由与工作流编排等核心创新。

> 核心理念：同样的预算，让 Agent 做更多事、做更好的事。（Same budget, more capability, better results.）

1.2 解决的核心痛点

AI Agent 在实际使用中面临两大矛盾：

1.3 微内核架构

借鉴操作系统微内核设计哲学——核心引擎只做最少的事（编排调度 + 状态管理），其余能力以插件形式在"用户态"运行。

                        ┌──────────────────────────────────────────┐
                        │       统一 Turn 循环（TurnRunner）           │
                        ├──────────────────────────────────────────┤
                        │    CLI  │  Web UI  │  聊天频道（10+）       │
                        ├──────────────────────────────────────────┤
                        │        SquillaRouter（本地模型路由）          │
                        │   持久记忆  │  安全沙箱  │  搜索  │  工具     │
                        ├──────────────────────────────────────────┤
                        │   engine/  │ provider/ │ gateway/ │ memory/ │
                        │ channels/  │  tools/   │  sandbox/ │ skills/ │
                        └──────────────────────────────────────────┘

核心模块：

1.4 核心功能矩阵

二、OpenSquilla 部署

2.1 四种安装路径对比

2.2 方式一：Windows 便携包（最简）

# 1. 下载便携版 zip
# https://github.com/opensquilla/opensquilla/releases/latest/download/OpenSquilla-windows-x64-portable.zip

# 2. 解压后，右键 "Start OpenSquilla.cmd" → 以管理员身份运行

# 3. 浏览器打开 http://127.0.0.1:18791/control/

2.3 方式二：终端一键安装（推荐）

第一步：安装 uv 包管理器

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

# Windows PowerShell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

第二步：安装 OpenSquilla

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

第三步：配置并启动

# 交互式配置向导
opensquilla onboard

# 启动网关
opensquilla gateway run

# 浏览器打开 http://127.0.0.1:18791/control/

2.4 方式三：源码安装

# 克隆仓库（含 Git LFS 拉取路由模型）
git lfs install
git clone https://github.com/opensquilla/opensquilla.git
cd opensquilla
git lfs pull --include="src/opensquilla/squilla_router/models/**"

# 运行安装脚本
bash scripts/install_source.sh           # macOS/Linux
powershell -File ./scripts/install_source.ps1  # Windows

# 配置并启动
opensquilla onboard
opensquilla gateway run

2.5 方式四：Docker 部署

# 从源码构建镜像（需先拉取 LFS 资产）
docker build -t opensquilla:local .

# 使用启动脚本
./start.sh    # macOS/Linux
start.ps1     # Windows

2.6 安装配置选项

# 最小化安装（不含路由器）
OPENSQUILLA_INSTALL_PROFILE=core bash scripts/install_source.sh

# 安装额外扩展（如 Matrix 频道、PDF 生成）
OPENSQUILLA_INSTALL_EXTRAS=matrix,document-extras bash scripts/install_source.sh

2.7 配置文件说明

加载顺序：OPENSQUILLA_GATEWAY_CONFIG_PATH → ./opensquilla.toml → ~/.opensquilla/config.toml → 内置默认值

关键环境变量：

三、OpenSquilla 控制台介绍

3.1 Web UI 控制台

访问地址：http://127.0.0.1:18791/control/

3.2 CLI 命令体系

#### 基础运维

opensquilla gateway run                # 前台运行网关（127.0.0.1:18791）
opensquilla gateway start --json       # 后台运行 + 健康检查等待
opensquilla gateway restart            # 重启网关
opensquilla doctor                     # 健康检查
opensquilla doctor --json              # JSON 格式健康检查

#### 交互模式

opensquilla chat                       # 交互式 REPL 聊天
opensquilla agent -m "your prompt"     # 单次执行（自动化友好）

#### 配置管理

# 首次配置向导
opensquilla onboard                    # 完整交互式
opensquilla onboard --if-needed        # 幂等模式
opensquilla onboard --minimal          # 最小化配置
opensquilla onboard status             # 检查配置状态

# 分别配置各模块
opensquilla configure provider --provider openai --model gpt-4o --api-key-env OPENAI_API_KEY
opensquilla configure router --router recommended
opensquilla configure search --search-provider brave --api-key-env BRAVE_SEARCH_API_KEY
opensquilla configure channels

#### 诊断与监控

opensquilla diagnostics on             # 开启路由诊断
opensquilla cost                       # 查看成本统计
opensquilla sessions --help            # 会话管理

#### 技能管理

opensquilla skills list                # 列出所有技能
opensquilla skills search meta         # 搜索 MetaSkills
opensquilla skills inspect <name>      # 检查技能/MetaSkill 组成结构

# MetaSkill 运行管理
opensquilla skills meta runs list      # 列出最近运行
opensquilla skills meta runs show <id> # 查看某次运行
opensquilla skills meta runs steps <id># 查看运行步骤
opensquilla skills meta runs failures --since 24h  # 查看失败记录

# MetaSkill 提案管理
opensquilla skills meta proposals list # 列出提案
opensquilla skills meta proposals show <id>  # 查看提案
opensquilla skills meta proposals accept <id> # 接受提案

#### 迁移工具

opensquilla migrate openclaw --json    # 从 OpenClaw 预览迁移
opensquilla migrate openclaw --apply   # 执行迁移
opensquilla migrate --source openclaw,hermes --apply  # 同时导入两者

3.3 多渠道接入

一次部署，可在以下终端同步使用：

四、智能模型路由演示

4.1 SquillaRouter 工作原理

SquillaRouter 是 OpenSquilla 最核心的技术——一个完全在本地运行的模型路由分类器。

                    ┌─────────────────────────────────────────┐
                    │       SquillaRouter 分类器（本地）          │
 用户输入 ─────────►│                                         │──► 模型分派
                    │  技术栈：LightGBM + ONNX                  │
                    │                                         │
                    │  分析维度：                               │
                    │    • 文本长度分析                         ├──► T0：最经济模型
                    │    • 语言检测                             ├──► T1：性价比模型
                    │    • 代码片段检测                         ├──► T2：中高端模型
                    │    • 关键词匹配                           └──► T3：顶级推理模型
                    │    • 语义嵌入向量                          │
                    │                                         │
                    │  成本：零 Token 消耗（纯本地推理）           │
                    └─────────────────────────────────────────┘

4.2 关键设计优势

4.3 路由配置方法

# 推荐模式（使用 SquillaRouter 智能路由）
opensquilla configure router --router recommended

# OpenRouter 混合模式（多 Provider 成本优化）
opensquilla configure router --router openrouter-mix

# 禁用路由（直接走单一模型，用于测试/审计）
opensquilla configure router --router disabled

4.4 基准测试数据（PinchBench 1.2.1，25 任务）

4.5 路由演示场景

场景一：混合负载（最佳收益）

用户：帮我查一下北京今天天气              → T0 模型（$0.0001）
用户：这段代码有什么性能问题？             → T2 模型（$0.002）
用户：帮我设计一个分布式系统的高可用架构     → T3 模型（$0.015）

在典型混合负载下（80% 简单任务 + 20% 复杂任务），实测成本节省 60-80%。

场景二：全复杂任务（收益较小）

若所有任务都需要顶级推理，路由收益有限，但仍可通过自适应 Prompt 和增量传输节省 10-20% Token。

4.6 路由器诊断

# 开启诊断，查看每轮路由决策
opensquilla diagnostics on

# 检查路由是否生效
opensquilla config get router.enabled
opensquilla config get llm.provider

# 检查 Provider 就绪状态
opensquilla providers status
opensquilla doctor

---

五、MetaSkills 测试演示

5.1 概念定义

MetaSkill 是什么：将可重复的多步骤工作打包为可重用、可检查的声明式工作流。它用 YAML 配置钉死执行顺序、依赖关系、数据传递路径——AI 在编排层面零自由度，但每步内部正常发挥。

与普通 Skill 的区别：

5.2 内置 MetaSkills 目录

5.3 MetaSkill 调用演示

隐式调用（描述期望结果）：

帮我比较一下日本 eSIM、运营商漫游和本地 SIM 卡，
我爸妈要去日本 8 天。包含来源、风险、最终建议，
以及我今晚应该买哪个。

显式调用（直接命名工作流）：

使用 meta-skill `meta-web-research-to-report`。

帮我比较一下日本 eSIM、运营商漫游和本地 SIM 卡，
我爸妈要去日本 8 天。包含来源、风险、最终建议，
以及我今晚应该买哪个。

5.4 MetaSkill Creator 演示

这是一个"元中之元"——用 MetaSkill 生成 MetaSkill。

用户：我需要一个能处理 Newsletter 邮件的工作流。

Creator 内部流水线：
  Step 1: 分析意图 → 理解"Newsletter 处理"的语义
  Step 2: 翻最近 30 天使用记录 → 找相关工作流模式
  Step 3: 选最合适的工作流模板 → 匹配最佳范式
  Step 4: 填槽组装 → 生成 YAML 配置
  Step 5: 冲突检查 → 检测触发词是否与已有技能冲突
  Step 6: 语法校验 → YAML 正确性验证
  Step 7: 风险评估 → 识别潜在安全/隐私问题
  Step 8: 冒烟测试 → 空跑验证流程是否通畅
  Step 9: 通过后给出提案 → 提交给用户审核

对比效果：传统方式需要上千字自然语言规则 + 额外审计脚本；MetaSkill 只需清晰的 5 步 YAML 配置。

5.5 MetaSkill 测试与管理命令

# 发现与检查
opensquilla skills list                     # 列出所有技能
opensquilla skills search meta              # 搜索 MetaSkills
opensquilla skills inspect <meta-skill-name>  # 检查编译后的步骤结构

# 运行审计
opensquilla skills meta runs list           # 列出最近的运行记录
opensquilla skills meta runs show <run-id>  # 查看某次运行详情
opensquilla skills meta runs steps <run-id> # 查看各步骤执行情况
opensquilla skills meta runs failures --since 24h  # 查看失败记录

# 回放与预览
opensquilla skills meta runs replay <run-id> --dry-run  # 预览回放（不实际执行）

# 提案流程
opensquilla skills meta proposals list      # 查看待审核提案
opensquilla skills meta proposals show <id> # 查看提案详情
opensquilla skills meta proposals accept <id> # 接受提案

5.6 MetaSkill 安全模型

• 输出为可审查的工作产物和决策支持草案
• 不是法律、医疗、金融、招聘、学术的最终专业建议
• 发布/安装/支付/签署/发送消息等操作需要明确用户授权

六、遇到的问题和心得

6.1 常见问题与解决

6.2 踩坑记录与经验

一、版本选择需谨慎

v0.2.1 及之前版本中，MetaSkill 功能尚在开发分支，正式版可能未包含。部署前务必确认版本号，建议直接使用最新的 v0.3.1。

二、Windows 沙箱限制

• Linux 有完整的 Bubblewrap 隔离
• macOS 的 Seatbelt 后端仅支持渲染配置，代码执行隔离待实现
• Windows 暂无沙箱后端——若安全隔离是硬需求，建议在 Linux 上部署

SquillaRouter 的 LightGBM 分类器依赖训练数据覆盖范围。对于全新类型的任务（如从未见过的领域术语或特殊格式），可能出现误判复杂度的情况。建议：

• 初期人工观察路由决策（diagnostics on）
• 对于关键任务，可临时 --router disabled 强制走顶级模型

成本节省效果取决于任务分布：

• 简单任务占比 60%+ → 收益巨大（60-80% 成本节省）
• 全是复杂任务 → 收益有限（路由本身不产生价值，仅靠自适应 Prompt 节省 10-20%）
• 典型场景如客服 Agent（80% FAQ + 20% 技术问题）是最佳使用场景

OpenSquilla 虽然以 4.1k Stars 快速增长，但相比 OpenClaw 的成熟生态，第三方 Skill 和社区案例仍然较少。对于需要丰富生态支持的项目，需评估这一差距。

六、依赖要求清单

6.3 最佳实践建议

1. 从 recommended 模式开始：日常使用推荐开启智能路由，仅在测试/审计时禁用 2. 使用 OpenRouter 作为 Provider：一个 Key 调用多个模型，与路由功能配合最佳 3. 善用 onboard --if-needed：脚本化部署和重装场景保证幂等性 4. 定期检查成本统计：opensquilla cost 查看实际节省效果 5. 先阅 MetaSkill 依赖：使用前 opensquilla skills inspect 检查依赖是否就绪 6. 私有化部署优先：所有路由决策和嵌入计算都在本地完成，数据不出境适合合规场景 7. 审批机制不要关闭：人在回路审批是安全兜底，应保持 enabled

6.4 总体心得

OpenSquilla 的价值不是单点的技术突破，而是系统级的成本优化。

它将"每次都用最强模型"的粗暴做法，转变为"用小学数学算 1+1，用微积分算偏微分方程"的分级策略。这种思路本身并不新奇，真正难得的是将它做成了一个零摩擦的开箱即用方案——用户几乎无感知，成本却降了一个数量级。

MetaSkill 则是在"省钱"之上进一步"省心"。 当 AI Agent 执行复杂任务时，"不听话"是比"成本高"更致命的问题。MetaSkill 用配置驱动替代自然语言规则，从根本上解决了执行确定性的问题——框架不让 AI 在编排层面做选择，但每步内部仍保留 AI 的灵活性。

两者加在一起，才构成了一个真正可用的 Agent 方案：路由保证成本可控，MetaSkill 保证输出可靠，记忆保证上下文连续，沙箱保证安全兜底——四者缺一不可。

---

附录：关键链接

*—— 研究完成于 2026年6月14日，OpenSquilla v0.3.1*