opensquilla--opensquilla/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

OpenSquilla — 高效省 Token 的 AI Agent

同样的预算，让 Agent 做更多事、做更好的事。
微内核 AI Agent——智能路由、持久记忆、安全沙箱、开箱即用的搜索与本地嵌入。

English · 中文 · 日本語 · Français · Deutsch · Español

本文档译自英文 README.md，如有出入请以英文版为准。

---

最新动态

• 📢 2026-07-03 —— 我们的技术报告 Agentic Routing: The Harness-Native Data Flywheel（预览版）已发布，随 OpenSquilla 0.5.0 Preview 1 一同放出。报告详细介绍了 harness 原生路由如何把日常 Agent 流量转化为自我改进的数据飞轮。

---

概览

OpenSquilla 是一个高效利用 Token 的微内核 AI Agent。本地模型路由会把每一轮都发给能处理它的最便宜模型；持久记忆、分层沙箱、内置网络搜索和设备端嵌入共同构成了这个 统一共享的轮次循环。

每个入口——Web UI、CLI 和聊天渠道——都跑在同一个循环里，因此工具调度、重试和决策日志的行为处处一致。可插拔的提供商层对接 TokenRhythm、OpenRouter、OpenAI、Anthropic、 Ollama、DeepSeek、Gemini、Qwen/DashScope 等 20 多个 LLM 提供商，无需改动你的代码或 配置结构。

OpenSquilla 0.5.0 Preview 3 是当前预览发布版本。

如需面向任务的产品文档，请从 OpenSquilla 产品指南或文档索引开始。

---

安装

OpenSquilla 可运行于 Windows、macOS 和 Linux。请选择与你的使用场景匹配的安装方式。

桌面安装包和终端快速安装会直接给你一个预构建的发布版，无需 Git。另外两种——从源码安装和从源码开发——则需要克隆 Git 仓库后再构建(git clone + Git LFS)。

发布版安装命令使用 GitHub 上已发布的 release 资源。Python wheel 安装使用带版本号的 wheel 文件名，因为安装器会校验嵌入在 wheel 文件名中的版本号。

对于 0.5.0 Preview 3 的桌面使用，建议从 GitHub Release 下载打包桌面安装包:macOS 上为 OpenSquilla-0.5.0-rc3-mac-arm64.dmg，Windows 上为 OpenSquilla-0.5.0-rc3-win-x64.exe。

安装方式	适合人群	何时使用
桌面安装包（推荐桌面用户）	macOS 和 Windows 用户	打包桌面应用
终端快速安装（推荐）	任意系统的最终用户	在终端中安装发布版 wheel
从源码安装	跟踪 main 分支的用户	从检出运行，而非修改它
从源码开发	贡献者	编辑、测试或调试源码

前置条件

要求	终端快速安装	从源码安装	从源码开发
Python 3.12+	通过 uv	通过 uv 或系统	通过 uv
Git + Git LFS	—	必需	必需
uv	缺失则自动安装	推荐	必需

默认的 recommended 安装档会安装 SquillaRouter——OpenSquilla 的设备端模型路由 ——及其模型资源；OPENSQUILLA_INSTALL_PROFILE=core 则会省略这些依赖。而 --router disabled 这个独立的 onboarding 标志则会保留已装好的依赖，只在运行时关闭路由。

在 Windows 上，SquillaRouter 内置的 ONNX 运行时还需要 Visual C++ 运行库。源码安装用的 PowerShell 安装器会通过 winget 自动装好它；而终端快速安装(uv tool install)这条路径不会——如果启动时记录了 DLL load failed 错误，请手动安装(见故障排查)。在装好之前，OpenSquilla 会以直连单一模型的路由方式继续运行。

在 macOS 终端安装时，SquillaRouter 的 LightGBM 运行时可能还需要系统的 OpenMP 库。 桌面应用会内置它所需的运行库，但终端快速安装不会安装 Homebrew/系统库。 如果启动时记录了 Library not loaded: @rpath/libomp.dylib，请运行 brew install libomp，然后重启网关。在装好之前，OpenSquilla 会以直连单一模型的路由方式 继续运行。

安装链接:Git · Git LFS · uv。

桌面安装包

0.5.0 Preview 3 桌面安装包将 Vue 控制台和网关运行时打包在一个 Electron 外壳中。

• macOS Apple Silicon: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

升级前请退出任何正在运行的 OpenSquilla 桌面应用。已有的 ~/.opensquilla/config.toml 和会话数据会被复用。

在 Windows 上从 RC3 升级到 RC4 或更高版本时，请直接运行新安装包覆盖现有安装。 请勿先卸载 RC3：RC3 的卸载程序可能会删除桌面端用户数据。升级前请备份 %APPDATA%\OpenSquilla。RC4 及更高版本的安装包在常规卸载时会保留用户配置数据。

终端快速安装

在 Windows、macOS 和 Linux 上的推荐路径。uv 会把 OpenSquilla 装进独立的隔离环境，并自带一个专用的 Python，不依赖系统 Python。此路径仅安装已发布的版本；如需 main、开发分支 或本地检出，请使用从源码安装。

1. 安装 uv——如果 uv --version 已经可用则跳过。

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"
$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"

这会从 release URL 安装 OpenSquilla wheel，再由 uv 下载所选 extra 所声明的依赖。 默认的 recommended extra 包含 SquillaRouter 运行时依赖，如 ONNX Runtime、LightGBM、 NumPy 和 tokenizers，因此首次安装需要联网，除非这些 wheel 已经缓存好了。uv 不会安装 系统原生运行库，如 macOS 的 libomp 或 Windows 的 Visual C++ Redistributable；若路由 运行时报告原生库加载错误，请参见故障排查。

3. 配置并运行。

opensquilla onboard
opensquilla gateway run

Note

如果在全新 uv 安装后立即找不到 opensquilla，请打开一个新终端，或重新执行第 1 步中的 PATH 设置命令。

如需完全锁定版本的安装，请使用带版本号的 wheel URL: https://github.com/opensquilla/opensquilla/releases/download/v0.5.0rc3/opensquilla-0.5.0rc3-py3-none-any.whl。

从源码安装

用这条路径可以直接从克隆下来的代码运行 OpenSquilla，而不去改动它。这份克隆只是给安装器当包源用；装好之后 请使用 opensquilla 命令——不要运行 uv run。如果你打算修改代码，请改用 从源码开发。

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. 运行安装器

   macOS / Linux

   bash scripts/install_source.sh
   

   Windows PowerShell

   powershell -ExecutionPolicy Bypass -File ./scripts/install_source.ps1
   

   该脚本会用 uv tool install 把 .[recommended](SquillaRouter + 记忆 + 本地模型)装进一个专用的用户环境；如果 uv 不可用，就退回到 python -m pip install --user。如果安装后 opensquilla 不在 PATH 上，请打开 一个新终端。

3. （可选）安装进阶 extra。 大多数渠道——Feishu（飞书）、Telegram、DingTalk（钉钉）、 QQ、WeCom（企业微信）、Slack 和 Discord——在基础安装下即可使用。可选的 extra 有:

   • matrix — Matrix 渠道(引入 matrix-nio)
   • matrix-e2e — 带端到端加密的 Matrix 渠道（需要 libolm）
   • document-extras — 通过 WeasyPrint 生成 PDF

   OPENSQUILLA_INSTALL_EXTRAS=matrix bash scripts/install_source.sh        # macOS / Linux
   

   powershell -ExecutionPolicy Bypass -File ./scripts/install_source.ps1 -Extras matrix   # Windows
   

4. 配置并运行——见配置。

从源码安装——终端前置条件与安装器选项

从终端安装前置条件(Git、Git LFS、uv)

Windows PowerShell:

winget install --id Git.Git -e
winget install --id GitHub.GitLFS -e
powershell -ExecutionPolicy Bypass -c "irm https://astral.sh/uv/install.ps1 | iex"
git lfs install

macOS(Homebrew):

brew install git git-lfs uv
git lfs install

Debian / Ubuntu:

sudo apt update && sudo apt install -y git git-lfs
curl -LsSf https://astral.sh/uv/install.sh | sh
git lfs install

在 Fedora 上使用 sudo dnf install -y git git-lfs；在 Arch 上使用 sudo pacman -S --needed git git-lfs；然后用上面的 curl 命令安装 uv。这些安装器 对 PATH 的修改会在新的终端会话中生效。

安装器环境变量与 PATH 检查

OPENSQUILLA_INSTALL_PROFILE=core   bash scripts/install_source.sh   # 最小运行时，无 SquillaRouter
OPENSQUILLA_INSTALL_DRY_RUN=1      bash scripts/install_source.sh   # 仅打印计划

用 command -v opensquilla(macOS/Linux)或 where.exe opensquilla(Windows)确认 你的 shell 实际运行的是哪个 opensquilla。如果它不在 PATH 上，请运行 uv tool update-shell。从本地检出重新安装后，请重启网关以加载更新后的包。

从源码开发

如果你要动 OpenSquilla 的源代码——改代码、跑测试，或在这份克隆里调试行为——就用这条路径。 它不是常规的安装路径。与从源码安装不同，此路径需要 uv: uv sync 会创建一个仓库本地的 .venv，而 uv run 会针对此检出中的文件执行命令。

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

recommended extra 在开发时也包含 SquillaRouter;dev extra 会安装测试、lint 和 类型检查工具。把额外的 extra 安装到你运行的同一个环境中:

uv sync --extra recommended --extra dev --extra matrix
uv run opensquilla channels status matrix --json

在这种模式下，请为配置中的每一条 opensquilla 命令加上 uv run 前缀。不要用用户本地的 opensquilla 命令去调试开发版代码——那个命令跑在另一个 Python 环境里。

卸载

用 opensquilla uninstall 卸载 OpenSquilla。它默认保留你的数据，只移除程序本身:

opensquilla uninstall --dry-run   # 预览将被移除和保留的内容
opensquilla uninstall             # 移除程序，保留你的数据

如需同时删除数据，请显式选择:

opensquilla uninstall --purge-state    # 会话、日志、缓存、调度器、记忆
opensquilla uninstall --purge-config   # config.toml 和密钥（.env）
opensquilla uninstall --purge-all      # 全部（会要求你输入确认）

运行中的网关会先被清空并停止，删除只在 OpenSquilla 主目录内进行；若是 Docker 或桌面安装，则会改为提供引导式的卸载步骤。桌面或操作系统应用的移除仍按各平台方式处理；CLI 引导不会删除桌面 app bundle。完整参考见 docs/cli.md。

---

安装隐私

OpenSquilla 使用匿名安装遥测来估算安装数量、版本采纳情况和运行时兼容性。数据只在网关 首次启动时上报，并且每个 OpenSquilla 版本只上报一次。OpenSquilla 也可能执行被动更新 检查，包括桌面启动时的自动更新检查。上传设了很短的超时，绝不会阻塞启动。

发送的内容:

• schema 版本
• 本地生成的稳定 install_id 摘要
• OpenSquilla 版本
• 事件类型(install 或 version_seen)
• 安装方式(pip、source、docker、desktop 或 unknown)
• 操作系统、系统版本、CPU 架构，以及 Python 主/次版本号
• 首次见到与发送的时间戳
• CI/测试环境标记(ci_environment)

install_id 是一个本地单向 SHA-256 摘要，由可用的 MAC 地址派生；无 MAC 时使用本地 IP 地址，并以一个随机持久化值兜底。原始 MAC/IP 值不会被上传。

不发送的内容:用户名、主机名、路径、API key、提供商配置、聊天/会话/记忆/Agent 内容、 文件名或文件内容。源 IP 在传输层可能会被 HTTP 服务器看到，但它不在上传的数据内。

要在启动前关闭非用户主动触发的网络可观测性:

OPENSQUILLA_PRIVACY_DISABLE_NETWORK_OBSERVABILITY=true

或在配置中设置:

[privacy]
disable_network_observability = true

这个统一开关覆盖自动安装遥测、被动更新检查和桌面启动自动更新检查。用户主动触发的操作仍可能在明确意图后访问网络服务，例如手动发布/下载/更新检查，以及已配置的提供商、搜索或渠道。

旧环境变量仍兼容:

OPENSQUILLA_TELEMETRY_DISABLED=true
OPENSQUILLA_UPDATE_CHECK_DISABLED=true

进阶部署可以使用自己的端点:

OPENSQUILLA_TELEMETRY_ENDPOINT=https://example.com/v1/install

---

配置

首次配置

opensquilla onboard 是交互式的首次配置向导。它会写入当前配置文件；当你传入 --api-key-env 时，提供商密钥会留在环境变量里。路由默认为 recommended （在受支持的提供商上启用 SquillaRouter）；如需直连单一模型，使用 --router disabled。

opensquilla onboard                # 完整交互式向导
opensquilla onboard --if-needed    # 幂等:适用于脚本和重装
opensquilla onboard --minimal      # 仅配置提供商；跳过渠道与搜索
opensquilla onboard status         # 查看每个配置项，但不写入

在 SSH、CI 或任何没有 TTY 的环境中，请使用非交互形式——把密钥放在环境变量里， 并传入它的变量名，而不是它的值:

Linux / macOS

export OPENROUTER_API_KEY="sk-..."
opensquilla onboard --provider openrouter --api-key-env OPENROUTER_API_KEY

Windows PowerShell

$env:OPENROUTER_API_KEY="sk-..."
opensquilla onboard --provider openrouter --api-key-env OPENROUTER_API_KEY

OpenRouter 仅作示例——可替换为任意受支持的提供商及其对应的 API key 变量。

之后无需重做整个向导即可重新配置某一个部分（以下示例假设相关 API key 已在环境中）:

opensquilla configure provider --provider openai --model gpt-4o --api-key-env OPENAI_API_KEY
opensquilla configure router --router recommended
opensquilla configure search   --search-provider duckduckgo
opensquilla configure search   --search-provider exa --api-key-env EXA_API_KEY
opensquilla configure channels

各部分:provider、router、channels、search、image-generation、 memory-embedding。Web UI 在 /control/setup 暴露相同的目录和状态模型:Provider 和 Router 是快速路径，而 Channels、Search、Image generation 和 Memory embedding 位于 能力中心（Capability Center），可以稍后配置。渠道留空会被当作主动跳过，而不是配置失败。

配置加载顺序:OPENSQUILLA_GATEWAY_CONFIG_PATH → ./opensquilla.toml → ~/.opensquilla/config.toml → 内置默认值。对单个密钥来说，环境变量里的值始终优先于配置文件里的值。

从 OpenClaw 或 Hermes Agent 迁移

如果你已经在 ~/.openclaw 或 ~/.hermes 下有状态，请先执行一次 dry run 查看迁移报告， 然后再显式应用:

opensquilla migrate openclaw --json
opensquilla migrate openclaw --apply

opensquilla migrate hermes --json
opensquilla migrate hermes --apply

使用 opensquilla migrate --source openclaw,hermes --apply 可同时导入两个默认主目录。 只有在看过 dry-run 报告之后，才加上 --migrate-secrets。自定义路径和冲突处理见 MIGRATION.md。

运行

opensquilla gateway run                # 前台运行，127.0.0.1:18791
opensquilla gateway start --json       # 后台运行 + 健康检查等待
opensquilla chat                       # 交互式 REPL
opensquilla agent -m "你的提示词"       # 一次性执行，便于自动化

在 http://127.0.0.1:18791/control/ 打开 Web UI。Health（健康） 视图会显示 OpenSquilla 是否就绪、哪些项尚未就绪，以及下一步的恢复建议。在 CLI 中，运行:

opensquilla doctor
opensquilla doctor --json
opensquilla doctor --config ./opensquilla.toml --json

/health 和 /healthz 是用于进程检查的轻量存活探针。opensquilla doctor 和 Web UI 的 Health 视图则是检查就绪状态的地方，涵盖提供商配置、记忆、日志、搜索、渠道、沙箱状态、 路由、图像生成以及恢复指引。按 Ctrl+C 可停止前台网关。

其他命令组包括 sessions、skills、memory、migrate、cron、channels、 providers、models 和 cost。运行 opensquilla --help 或 opensquilla <组名> --help 查看详情。

进阶配置——验证渠道、公网绑定、Docker

连接并验证一个消息渠道

保存渠道只是改了配置，并不代表它在运行时真的连得上。编辑渠道后请重启网关，然后验证实时渠道:

opensquilla gateway restart
opensquilla channels status <name> --json

只有当状态数据里 enabled=true、configured=true 且 connected=true 时，才算渠道已连上。Feishu（飞书）默认使用 websocket 模式，Telegram 使用轮询，Slack 可使用 Socket Mode——这些模式都不需要公网 URL。Feishu webhook 模式、Telegram webhook 模式、 Slack webhook 模式以及 WeCom（企业微信）则需要一个公网可达、提供商可访问的 URL。

公网绑定

要从另一台机器访问 Web UI，请把网关绑定到所有网络接口，并使用主机的公网 IP:

opensquilla gateway run --listen 0.0.0.0 --port 18791

公网访问还要求主机防火墙或云安全组允许该端口的入站 TCP。不要在 [auth] mode = "none" 的情况下暴露网关——在绑定到 0.0.0.0 之前请先配置 token 认证。

Docker

预构建的多架构镜像(amd64/arm64)会随每个发布标签发布到 ghcr.io/opensquilla/opensquilla——完整的容器部署指南见 docs/docker.md(家庭服务器与 NAS、带 token 认证的局域网访问、升级):

OPENSQUILLA_GATEWAY_IMAGE=ghcr.io/opensquilla/opensquilla:latest docker compose up -d

不设置 OPENSQUILLA_GATEWAY_IMAGE 时,compose 路径运行一个你自己构建的 opensquilla:local 镜像。请从一份已拉取 Git LFS 路由 资源的源码检出来构建它(克隆与 git lfs pull 见从源码安装):

docker build -t opensquilla:local .

随后 ./start.sh(Windows 上为 start.ps1)会运行 docker compose up -d 并跟踪网关 日志。Docker 省掉的是宿主机上的 Python 工具链，而不是本地镜像构建那一步。

提供商分级、沙箱调优、图像生成和并发设置位于 opensquilla.toml.example。

---

0.4.1 更新内容

OpenSquilla 0.4.1 是面向桌面端与 Control UI 方向的维护版本:

• 桌面可靠性 —— 打包后的网关检查现在覆盖 Coding 模式、code-task 和 SquillaRouter 启动，桌面窗口/产物处理更加稳定。
• 六种语言客户端支持 —— Control UI 和桌面客户端在首屏和设置界面支持英语、简体中文、 日语、法语、德语和西班牙语。
• Coding 模式与路由打包 —— 如果路由资源缺失或仍是 Git LFS 指针，桌面构建会快速失败， 防止生成功能受损的发布包。
• 遥测与 Windows 打磨 —— 安装遥测会跳过 CI 和测试环境，Windows 桌面资源使用 OpenSquilla 徽标。
• 主线治理 —— 普通 pull request 和发布集成统一围绕 main，维护者分支则保留用于发布、 热修复、预发布、集成和沙箱工作。

完整说明:CHANGELOG.md · docs/releases/0.4.1.md。

0.2.1 更新内容

OpenSquilla 0.2.1 是一个专注于发布包启动和长时运行 Agent 可靠性的维护版本:

• Windows 便携版启动 —— 便携版启动器能更好地检测并引导安装内置 ONNX 路由所需的 Visual C++ 运行库。
• 长时运行的 Agent 轮次 —— 工具密集的 WebUI 会话现在能更利落地从各种状况中恢复:超大工具结果、格式错误的工具调用、产物交付环节，以及降级的最终响应。
• 更干净的 WebUI 输出 —— 生成的产物标记不会出现在普通聊天回放中，而已交付的文件仍然 可见。
• 记忆召回评分 —— 本地以及 OpenAI 兼容的嵌入向量，会在语义搜索前先做归一化；当向量得分偏低时，强关键词匹配依然能派上用场。

完整说明:CHANGELOG.md · 发布说明。

0.2.0 更新内容

此版本在迁移、CLI 聊天、渠道、调度和长时运行的工具工作等方面扩展了 OpenSquilla:

• 从现有 Agent 主目录迁移 —— opensquilla migrate 可以预览并执行从现有 OpenClaw/Hermes 主目录的导入，包括记忆、persona 文件、技能、MCP/渠道配置、冲突处理 和迁移报告。
• 可用的聊天 CLI —— opensquilla chat 拥有稳定的终端 UI、流式输出、排队输入、 斜杠模式发现、工具/状态条，以及更具确定性的实时提示行为。
• 跨界面的 cron 自动化 —— cron 作业现在涵盖结构化排程、时区感知的精确/周期性/cron 运行、 渠道或 webhook 投递、失败目标、手动运行，以及 WebUI/CLI/RPC 的一致性。
• 更好的 Feishu 和 Discord 渠道 —— 渠道适配器暴露更清晰的能力元数据、更安全的 私信/群组处理、原生的文件与产物路径，以及改进的附件/线程行为，同时特权操作保持受限作用域。
• 更稳健的长时运行轮次 —— 失败的轮次不会进入提供商回放，格式错误的工具调用也会得到更稳妥的处理；需要审批的重试则会等操作者拍板。
• 更智能的上下文与工具预算 —— 提供商预算压缩、提示缓存保留、对工具结果做大小限制，以及能感知副作用的并发，让大型、工具密集的会话更可预测。
• Web UI 与发布打磨 —— 在 0.2.0 中对按时间排序、表格布局、移动端控件、重复通知、配置表单、release URL 和安装路径都做了打磨收紧。

完整说明:CHANGELOG.md · 发布说明。

---

核心功能

能力	它做什么
省 Token 的路由	SquillaRouter——recommended extra 中一个本地的 LightGBM + ONNX 分类器——会按长度、语言、代码、关键词和语义嵌入给每一轮打分，再在四个分级（C0–C3；旧的 T0–T3 命名是其别名）里把它分派给能胜任的最便宜模型。分类在本机上完成；为了做这个判断，你的提示词不会离开本机。
自适应推理与提示	OpenSquilla 仅对路由判定为复杂的轮次请求扩展推理，系统提示也随任务复杂度伸缩——简单轮次用轻量提示，复杂轮次用完整指令。
20+ 个 LLM 提供商	提供商注册表面向 20 多个 LLM 后端——TokenRhythm、OpenRouter、OpenAI、Anthropic、Ollama、DeepSeek、Gemini、DashScope/Qwen、Moonshot、Mistral、Groq、Zhipu、SiliconFlow、vLLM、LM Studio 等等，并支持主用 + 回退选择；首次 onboarding 会暴露已验证的子集。
按需技能与 MCP	15 个内置技能(coding、GitHub、cron、pptx/docx/xlsx/pdf、摘要、tmux、天气等)仅在任务需要时加载。OpenSquilla 是 MCP 客户端，也可以作为 MCP 服务端运行——opensquilla mcp-server run 需要 mcp extra(安装 opensquilla[recommended,mcp])。技能可以从 CLI 编写、安装和发布。
持久化本地记忆	一份精选的 MEMORY.md 加上带日期的 Markdown 笔记，通过 SQLite 全文关键词搜索和 sqlite-vec 语义召回来检索。嵌入通过内置 ONNX 在设备端运行，也可切换到 OpenAI/Ollama。可选的指数衰减和需主动启用的“做梦(dream)”记忆整合也可用。
分层安全沙箱	基于权限矩阵的三档策略（Standard / Strict / Locked）。在 Linux 上 Bubblewrap 隔离代码执行；macOS 的 Seatbelt 后端目前只生成 profile（尚未真正执行），Windows 上则还没有沙箱后端。拒绝账本（denial ledger）会在反复拒绝后自动暂停自主运行，清除被拒的输出；技能元数据和工具结果也会做 XML 转义，以防提示注入。
内置工具	文件读/写/编辑、shell 与后台进程、git、网络搜索（DuckDuckGo、Bocha、Brave、Tavily 或 Exa），以及带 SSRF 防护的网页抓取、电子表格/PPTX/PDF 创作、图像生成，以及文本转语音。
统一网关	一个运行在 127.0.0.1:18791 上、带 WebSocket RPC 和内嵌控制台(/control/)的 Starlette ASGI 服务。Web UI、CLI，以及 Terminal、WebSocket、Slack、Telegram、Discord、Feishu、DingTalk、WeCom、Matrix、QQ 这些渠道，都共用同一个 TurnRunner。
持久会话、子 Agent 与调度	由 SQLite 支撑的会话、转录和回放存储，并带有按 Agent 隔离的工作区。Agent 可以派生深度受限的子 Agent；SchedulerEngine 内置了 cron 解析器，会通过 opensquilla cron 运行周期性作业。
操作者控制	人在环路(human-in-the-loop)审批可以暂停敏感的工具调用，等人来决定；按轮次和按会话的 Token 与成本汇总(opensquilla cost)及诊断信息均可从 CLI 和 Web UI 获取。

MetaSkill 文档:docs/features/meta-skills.md、 docs/features/meta-skill-user-guide.md 和 docs/authoring/meta-skills.md。

---

基准测试结果

PinchBench 1.2.1 在 25 个任务上的平均结果:

Agent	基座模型	平均分	总输入 token	总输出 token	总成本
OpenSquilla	模型路由（Opus4.7、GLM5.1、DS4 Flash）	0.9251	1,721,328	61,475	$0.688
OpenClaw	Claude Opus 4.7	0.9255	3,066,243	50,890	$6.233

分数是 25 个任务的均值；token 数和成本是整次运行的总计。

---

故障排查

macOS：Library not loaded: @rpath/libomp.dylib

如果启动时从 lightgbm/lib/lib_lightgbm.dylib 记录了 Library not loaded: @rpath/libomp.dylib,OpenSquilla 会以直连单一模型的路由方式继续 运行，但内置的 SquillaRouter 运行时会保持不活动，直到安装 macOS 的 OpenMP 运行库。

桌面应用会内置它所需的原生运行库。如果你是通过终端快速安装或从 shell 进行源码安装， 请用 Homebrew 安装 libomp 并重启网关:

brew install libomp
opensquilla gateway restart

Windows：DLL load failed / Visual C++ 运行库

如果启动时记录了 DLL load failed while importing onnxruntime_pybind11_state, OpenSquilla 会以直连单一模型的路由方式继续运行，但内置的 SquillaRouter 运行时会保持 不活动，直到安装适用于 Visual Studio 2015–2022(x64)的 Visual C++ Redistributable。

从源码安装的 PowerShell 安装器会尝试通过 winget 安装该 redistributable。如果你使用的是终端快速安装，或 winget 不可用，请手动安装它并重启 PowerShell:https://aka.ms/vs/17/release/vc_redist.x64.exe。然后恢复推荐的路由:

opensquilla onboard --provider openrouter --api-key-env OPENROUTER_API_KEY --router recommended
opensquilla gateway restart

---

致谢

OpenSquilla 的灵感来自 OpenClaw。内置的第三方内容在 THIRD_PARTY_NOTICES.md 中注明出处。

社区贡献者都记在 CONTRIBUTORS.md 里，其中也包含针对 squash 合并或回放工作、按发布版本给出的署名说明。

---

贡献者

感谢所有为 OpenSquilla 做出贡献的人。

---

参与贡献

我们欢迎各种形式的贡献——bug 报告、功能想法、文档、新的提供商或渠道适配器、技能，以及 核心运行时方面的开发。请参阅 CONTRIBUTING.md，然后到 GitHub 上提 issue 或 pull request。

行为准则 · 安全 · 支持 · 许可证（Apache-2.0）