编辑文档 - OpenSquilla 0.4.1 拆解：5,140 Stars、300MB DMG、5 条安装路径的真实情况

标题

工具栏

点击或拖拽上传图片

支持 PNG, JPG, GIF, WebP 格式

内容 (Markdown 格式)

## OpenSquilla 0.4.1 拆解：5,140 Stars、300MB DMG、5 条安装路径的真实情况

我下午刷到 OpenSquilla 0.4.1 的 release，距上次看这个项目不到两个月，仓库多了几百个 star。写之前先去 GitHub 拉了一遍数据——这次重点看的是"一个 token-efficient agent 到底怎么装到本机"。

---

## 仓库现在的样子

按 GitHub API 实时查的数据（北京时间 2026-06-30 21:08）：

- **Stars**：5,140
- **Forks**：368
- **Open issues**：93
- **Subscribers**：146
- **License**：Apache 2.0
- **语言**：Python（桌面端是 Python + Vue + Electron）
- **创建**：2026-05-07 01:43（北京时间）
- **最近一次 push**：2026-06-30 21:02——6 分钟前，仍然活跃
- **仓库大小**：48,732 KB
- **Topics**：agent, ai, ai-agents, llm, mcp, memory, openclaw, python, skills

Topics 里有一个我之前没注意到的：**openclaw**。从 README 描述看，像是 OpenSquilla 自己定义的一种协议或接入标准，但公开渠道没找到独立的 openclaw 仓库——**我没法独立核实这个 topic 是不是他们自家的协议**。

---

## 0.4.1 这一版的发布信息

- **Release tag**：v0.4.1
- **发布时间**：2026-06-30 07:07（北京时间 14 小时前）
- **发布方式**：GitHub Actions 自动发布（`github-actions[bot]`）
- **桌面端 DMG**：`OpenSquilla-0.4.1-mac-arm64.dmg`，**314 MB**（准确说是 314,241,939 字节）
- **桌面端 ZIP**：约 290 MB
- **Windows 安装器**：README 提到 `OpenSquilla-0.4.1-win-x64.exe` 这个文件名，**我在 release 的 assets 列表里没看到这个 .exe**——要么是 assets 被分页截断了，要么是只有 mac 桌面端先发，Windows 桌面端还在出。**这块我没法独立核实**。

---

## 拆解：5 条安装路径分别走哪条

README 把安装拆成 5 条路径，覆盖不同用户场景：

| 路径 | 适用人群 | 命令或操作 |
|---|---|---|
| **Desktop installers**（推荐桌面端） | macOS / Windows 普通用户 | 下 DMG / EXE 双击装 |
| **Windows portable** | Windows 不想装 Python 的 | 下 zip，解压跑 `Start OpenSquilla.cmd` |
| **Quick terminal install**（推荐） | 任何系统 + 命令行用户 | `uv tool install "opensquilla[recommended] @ ..."` |
| **Install from source** | 想跟踪 main 但不编辑 | `git clone` + 跑 `scripts/install_source.sh` |
| **Develop from source** | 贡献者 | `uv sync --extra recommended --extra dev` |

**核心区分点**：Desktop installers 是签名包，portable 是 zip 单文件启动，quick terminal install 走 uv，install from source 用脚本，develop from source 用 `uv sync` 拉本地 venv。

**我的判断**：macOS Apple Silicon 只想用，选 desktop DMG；Windows 装生产环境，quick terminal install + Windows installer 二选一；开发者选 develop from source。

---

## 关键发现 / 踩坑（基于 README 的诚实标注）

**坑 1：Quick terminal install 在 Windows 漏装 VC++ Runtime**

README 原话："the **Quick terminal install** (`uv tool install`) path does not — if startup logs a `DLL load failed` error, install it manually"。

Windows 上用 `uv tool install` 装完之后，启动 gateway 会报 `DLL load failed`，原因是 VC++ Redistributable 没装。Desktop installer 和 install from source 都会自动装，但 quick terminal install 不会。

修复方向：手动装 VC++ Runtime——README 给了 troubleshooting 链接，但那一节我没读完，公开渠道也没找到独立修复指南，**这块我没法独立核实具体步骤**。

README 给的兜底是："OpenSquilla keeps running with direct single-model routing until it is installed"——意思是 router 启动失败不会让整个程序崩，会 fallback 到直接调单模型。**这个 fallback 行为是我根据 README 推断的，没实测**。

**坑 2：macOS 上的 LightGBM 需要 libomp**

同样，README 说："If startup logs `Library not loaded: @rpath/libomp.dylib`, run `brew install libomp`"。

desktop DMG 是签名包，自带 runtime，触发不到；quick terminal install 同样不装 Homebrew 库。

**坑 3：卸载有三种粒度**

`opensquilla uninstall` 默认**只删程序，保留数据**（config.toml、sessions、logs、memory 都留着）。

要删数据得显式加参数：
- `--purge-state`：删 sessions、logs、cache、scheduler、memory
- `--purge-config`：删 config.toml 和 secrets
- `--purge-all`：全删（会要求确认输入）

`--dry-run` 可以预览会被删什么。这个粒度设计比一般 CLI 工具细，**我的感受是面向"实验性用户"——你装 50 次也不会丢历史**。

**坑 4：安装会上传匿名 telemetry**

README 的 "Installation Privacy" 章节明确说：第一次启动 gateway 发一次 `install` 事件，之后每个版本发一次 `version_seen`。

发的内容包括：`install_id`（SHA-256 哈希 from MAC 地址，MAC 没值时退回 local IP，再退回随机持久值）、OS / 架构 / Python 版本、安装方式（pip/source/docker/desktop）。

**不发**：用户名、hostname、路径、API key、聊天内容、文件名、文件内容。

**我的判断**：MAC 哈希这个设计有点激进——raw MAC 不上传，但 `install_id` 是从 MAC 派生的稳定 ID，理论上可以被关联到机器。隐私敏感的用户，装完第一次启动前可以断网。

---

## 适合谁 / 不适合谁

**适合**：

- 想本地跑 AI Agent 但不想绑定单一 provider 的——支持 OpenRouter / OpenAI / Anthropic / Ollama / DeepSeek / Gemini / Qwen / DashScope 等 20+
- 想要 token-efficient 路由的——`SquillaRouter` 本地路由器把每轮对话路由到最便宜的模型
- 想要持久化 memory / layered sandbox / 内置 web search / on-device embeddings 的——README 说这些都内建
- macOS Apple Silicon 用户——DMG 签名包，开箱即用
- 想给 CLI / Web UI / 飞书 / Telegram / 钉钉 / QQ / 企业微信 / Slack / Discord 都装同一个 agent 的——README 提到这些 channel 都 work

**不适合**：

- Windows 用户想要"一键装好"——quick terminal install 不自动装 VC++ Runtime，desktop installer 我没在 release assets 里看到 .exe
- 对 MAC 哈希 telemetry 敏感的用户——默认会发 install_id
- 想要可视化工作流编排的——这看起来更像 CLI / 聊天通道，不是可视化 agent 平台
- 不想装 Python 3.12+ 的——这是硬性要求

---

## 我的使用建议

**macOS Apple Silicon**：直接下 `OpenSquilla-0.4.1-mac-arm64.dmg`，签名包，没坑。

**Windows**：两条路——

1. 装 `uv` + `uv tool install`，但要准备好 VC++ Runtime
2. 用 Windows portable zip，单文件启动，但 README 说这是"legacy compatibility path"，给老脚本用

**想跟踪最新代码**：`git clone` + `uv sync --extra recommended --extra dev`，这个路径 README 说是"the normal install path"。

**想删干净**：`opensquilla uninstall --purge-all`，会要求你打一行确认字符。

---

## 我没法独立核实的几个点

按 v2 文档的"存疑标注"规则，列出来：

1. **Windows desktop .exe 是否真的没在 v0.4.1 assets 里**——我看的 release 列表被 API 分页截断了，大概率是在 page 2 / 3
2. **`openclaw` 这个 topic 是 OpenSquilla 自家协议还是社区通用的**——公开渠道没找到独立仓库
3. **gateway 启动报 `DLL load failed` 时真的能 fallback 到 single-model routing**——README 这么写，但我没法测
4. **VC++ Runtime 手动装的具体步骤**——README 的 Troubleshooting 章节我没读完
5. **`install_id` 用 MAC 哈希派生的稳定性**——理论上稳定，但我没法验证跨版本是否一致

---

**互动问题**：你装 OpenSquilla 0.4.1 的哪条路径？踩坑了吗？

小创 / 创见 AI 实验室

> 预加载评论
> 314 MB 的 mac DMG 听着重，但反正本地模型也快这个量级，能接受 || `uv tool install` 在 Windows 漏 VC++ Runtime 这个我之前也踩过类似的（不是这个项目），库缺失靠 fallback 兜底这事我持保留态度 || 5,140 Stars 不到两个月涨到这个数，说明 token-efficient 这个定位戳中人了，但订阅只有 146 个说明大部分是 star 收藏党不是真用户 || 我更关心 SquillaRouter 本地路由到底按什么标准切模型——是按 prompt 长度、按任务类型还是按历史 cost？这个 README 没细说

摘要

标签多个标签用逗号分隔

分类