OpenSquilla：本地智能路由AI代理，低成本高密度处理复杂任务

30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度今天来看一个在 GitHub 上快速走红的 AI Agent 项目——OpenSquilla。如果你正在寻找一个能帮你省钱、又能高效处理复杂任务的智能助手并且希望它能在本地运行、支持多种大模型、还能接入各种聊天工具那这个项目值得你花十分钟了解一下。OpenSquilla 的核心卖点非常直接用更低的成本获得更高的智能密度。它本质上是一个“微内核”AI 代理最大的特点是内置了一个本地的模型路由器SquillaRouter。这个路由器能根据你每次对话的复杂度长度、语言、代码、关键词等自动将任务分配给最便宜且能胜任的模型去处理。这意味着简单的查询可能交给一个轻量级模型而复杂的编程任务则自动路由到 GPT-4o 或 Claude Opus 这类顶级模型整个过程完全在本地决策你的提示词不会为了路由而外泄。项目目前版本是 0.4.1支持 Windows、macOS 和 Linux提供了桌面安装包、便携版、命令行安装和源码安装等多种方式对新手和开发者都很友好。它集成了 20 个 LLM 提供商如 OpenAI、Anthropic、DeepSeek、Ollama 等自带 15 种开箱即用的技能如代码、GitHub、文档处理、定时任务等并且拥有持久化本地记忆、分层安全沙箱、内置网络搜索等特性。所有入口——Web UI、CLI 和聊天频道如 Slack、Telegram、飞书——都共享同一个任务处理循环行为一致。本文将带你快速上手 OpenSquilla从核心能力速览、环境准备、多种安装方式、基础功能验证到高级配置和常见问题排查让你能快速判断它是否适合你的工作流并顺利部署起来。1. 核心能力速览在深入细节前我们先通过一个表格快速了解 OpenSquilla 的核心规格和特点方便你判断是否符合需求。能力项说明项目类型微内核 AI 代理 (Microkernel AI Agent)核心特性成本优化本地模型路由器按任务复杂度智能分配至最经济模型。多入口统一Web UI、CLI、聊天工具Slack/Telegram/飞书等共享同一处理核心。技能按需加载内置代码、文档处理、Git、定时任务等15技能用时才加载。持久化本地记忆支持 SQLite 全文检索和语义向量搜索本地 ONNX 或远程嵌入。安全沙箱分层安全策略标准/严格/锁定隔离代码执行。支持平台Windows, macOS, Linux启动方式桌面应用.dmg/.exe、便携包Windows、命令行一键安装uv、源码安装、Docker硬件门槛无特殊 GPU 要求。核心路由和本地嵌入推理在 CPU 上运行。主要消耗在于调用外部 LLM API 的成本。显存占用不涉及本地大模型推理无显存占用压力。本地路由和嵌入模型运行在 CPU/内存。是否支持 API是。提供统一的 HTTP/WebSocket 网关服务默认端口 18791所有功能可通过 RPC 调用。是否支持批量任务是。通过opensquilla agent -m “任务”进行单次调用结合opensquilla cron可创建定时/循环任务也支持通过 API 编排工作流。主要适用场景1.成本敏感的多模型调用希望混合使用不同价位的模型以优化开支。2.统一的任务自动化通过一个入口CLI、Web 或聊天工具触发代码生成、文档处理、信息检索等任务。3.安全的本地代理需要在沙箱中安全执行代码或访问本地文件系统的 AI 助手。4.从现有 Agent 迁移可平滑迁移 OpenClaw 或 Hermes Agent 的配置和数据。2. 适用场景与使用边界OpenSquilla 不是一个“全能”的本地大模型而是一个智能的“调度中心”和“工具箱”。理解它的适用边界能帮你更好地利用它。它非常适合以下场景开发者日常助手在终端里用opensquilla chat快速问技术问题、写代码片段、解释错误日志让 AI 根据上下文自动选择最合适的模型。团队协作集成将 OpenSquilla 接入团队的 Slack、飞书或 Discord成员可以直接在聊天窗口里让 AI 查询信息、生成报告、甚至执行简单的自动化脚本在安全沙箱内。成本可控的 AI 应用开发作为后端服务你的应用可以通过 API 调用 OpenSquilla它内部会帮你做成本最优的模型路由你无需在业务逻辑里写一堆if-else来判断该调用哪个模型。个人知识管理利用其本地记忆功能将日常笔记、会议纪要以 Markdown 形式保存后续可以通过语义搜索快速召回相关信息。它可能不适合或不擅长完全离线的本地大模型推理OpenSquilla 本身不包含大模型权重它需要连接外部 LLM API 服务如 OpenAI、Ollama 本地服务等。它的“本地”指的是路由决策和部分工具运行在本地。需要极高实时性的场景模型路由、API 调用、工具执行会引入延迟不适合对延迟要求极低的交互。替代专业的、单一功能的 AI 工具例如对于专业的文生图你可能更需要 Stable Diffusion WebUI对于专业的代码补全你可能更需要 Cursor 或 Copilot。OpenSquilla 的优势在于整合与调度。安全与合规边界工具执行虽然提供了安全沙箱但在“标准”模式下AI 代理仍可能执行文件读写、Shell 命令等操作。务必在可信环境中使用并对敏感操作设置审批流程。数据隐私你的对话历史、记忆笔记默认存储在本地~/.opensquilla/目录。但发送给外部 LLM 提供商如 OpenAI的提示词和接收的回复其隐私政策取决于对应提供商。版权与授权使用其代码生成、文档处理等功能时应确保生成的内容不侵犯第三方版权并遵守相关开源协议。3. 环境准备与前置条件OpenSquilla 的设计目标之一是降低部署门槛但为了获得完整功能仍需满足一些基本条件。1. 操作系统Windows 10/11(x64)macOS(Intel 或 Apple Silicon)Linux(主流发行版如 Ubuntu, Debian, Fedora, Arch 等)2. 基础软件依赖Python 3.12部分安装方式如 Quick terminal install通过uv工具管理无需系统 Python。Git 和 Git LFS如果你选择“从源码安装”或“开发模式安装”则需要它们来克隆仓库和拉取模型路由器的资源文件。uv一个快速的 Python 包安装器和解析器是官方推荐的安装工具能自动处理 Python 版本和依赖隔离。3. 网络要求能够访问 GitHub 以下载安装包或源码。能够访问你配置的 LLM 提供商 API如api.openai.com,api.anthropic.com等。如需使用网络搜索功能需能访问对应的搜索引擎 API如 DuckDuckGo、Exa 等。4. 可选系统库针对模型路由器macOS如果使用命令行安装可能需要libomp库。可通过brew install libomp安装。Windows如果使用命令行安装可能需要Visual C Redistributable for Visual Studio 2015–2022 (x64)。桌面安装包和便携版通常会尝试自动安装。5. 磁盘空间基础安装大约需要几百 MB 空间。如果启用完整的recommended配置包含 SquillaRouter 模型资源会额外占用一些空间用于缓存本地模型文件。6. 端口占用默认网关服务运行在127.0.0.1:18791。请确保该端口未被其他程序占用或准备在启动时指定其他端口。4. 安装部署与启动方式OpenSquilla 提供了多种安装路径你可以根据自身情况选择最合适的一种。这里我们重点介绍最推荐的两种快速终端安装和桌面安装器。4.1 快速终端安装推荐跨平台这是官方最推荐的安装方式使用uv工具能在 Windows、macOS、Linux 上提供一致的体验且无需系统 Python。步骤 1安装 uv如果系统没有uv需要先安装它。Linux / macOS:curl -LsSf https://astral.sh/uv/install.sh | sh # 安装后可能需要重新打开终端或运行以下命令使 uv 生效 . $HOME/.local/bin/envWindows PowerShell:powershell -c irm https://astral.sh/uv/install.ps1 | iex # 将 uv 添加到当前会话的 PATH $env:Path $env:USERPROFILE\.local\bin; $env:Path步骤 2安装 OpenSquilla使用uv tool install命令安装指定版本的 OpenSquilla。以下命令安装 0.4.1 版本并包含推荐的功能包含模型路由器uv tool install --python 3.12 opensquilla[recommended] https://github.com/opensquilla/opensquilla/releases/download/v0.4.1/opensquilla-0.4.1-py3-none-any.whl这个命令会创建一个独立的环境并安装 OpenSquilla 及其所有依赖。步骤 3首次运行与配置安装完成后就可以使用opensquilla命令了。首先进行初始配置opensquilla onboard这是一个交互式向导会引导你选择 LLM 提供商如 OpenRouter, OpenAI, Anthropic 等。配置对应的 API 密钥建议通过环境变量设置如OPENROUTER_API_KEY。选择是否启用模型路由器推荐启用。配置其他能力如搜索、频道等可稍后配置。对于非交互式环境如脚本、CI可以这样配置# Linux/macOS export OPENROUTER_API_KEYsk-你的密钥 opensquilla onboard --provider openrouter --api-key-env OPENROUTER_API_KEY # Windows PowerShell $env:OPENROUTER_API_KEYsk-你的密钥 opensquilla onboard --provider openrouter --api-key-env OPENROUTER_API_KEY步骤 4启动网关服务配置完成后启动服务# 在前台运行日志输出到控制台 opensquilla gateway run # 或者在后台运行并等待服务就绪 opensquilla gateway start --json服务启动后默认监听http://127.0.0.1:18791。打开浏览器访问http://127.0.0.1:18791/control/即可进入 Web 控制台。4.2 桌面安装器适合 macOS/Windows 桌面用户如果你更喜欢图形化应用可以直接下载桌面安装包。macOS (Apple Silicon):下载 OpenSquilla-0.4.1-mac-arm64.dmgWindows (x64):下载 OpenSquilla-0.4.1-win-x64.exe下载后直接安装运行即可。首次运行同样会引导你进行初始配置。桌面版集成了 Web 控制台无需手动启动网关。4.3 Windows 便携版无需安装 Python对于 Windows 用户还有一个便携版本解压即用无需安装 Python 环境。下载 OpenSquilla-windows-x64-portable.zip 。解压到任意可写目录如Downloads或Documents。右键点击Start OpenSquilla.cmd选择“以管理员身份运行”。完成首次运行配置后访问http://127.0.0.1:18791/control/。注意由于目前 Windows 构建未签名可能会触发 SmartScreen 警告选择“更多信息”-“仍要运行”即可。如果被企业策略阻止请使用“快速终端安装”方式。4.4 从源码安装适合跟踪最新特性如果你想运行特定的开发分支或修改代码可以选择此方式。# 1. 克隆仓库需要 Git LFS git lfs install git clone https://github.com/opensquilla/opensquilla.git cd opensquilla git lfs pull --includesrc/opensquilla/squilla_router/models/** # 2. 运行安装脚本 # macOS/Linux bash scripts/install_source.sh # Windows PowerShell powershell -ExecutionPolicy Bypass -File ./scripts/install_source.ps1安装脚本会使用uv或pip在用户环境中安装 OpenSquilla。安装后使用opensquilla命令的方式与其他安装方式相同。5. 功能测试与效果验证安装并启动服务后我们可以通过几种方式来验证 OpenSquilla 是否工作正常并体验其核心功能。5.1 健康检查与 Web 控制台首先检查服务状态opensquilla doctor或者获取 JSON 格式的详细状态opensquilla doctor --json这个命令会检查提供者配置、内存、搜索、频道、沙箱、路由器等各个模块的状态并给出修复建议。然后在浏览器中打开http://127.0.0.1:18791/control/。控制台的Health视图会直观地展示各项服务的就绪情况。这是排查问题的一站式入口。5.2 基础对话测试CLI打开终端使用内置的聊天界面进行测试opensquilla chat这会进入一个交互式 REPL 环境。你可以直接输入问题例如 用 Python 写一个函数计算斐波那契数列的第 n 项。观察回复。如果配置了模型路由器SquillaRouterOpenSquilla 会根据这个问题的复杂度包含代码自动将其路由到配置中能力更强的模型如 GPT-4来处理而不是用便宜的模型。你也可以进行单次任务测试适合自动化脚本opensquilla agent -m 总结一下 OpenSquilla 项目的核心优势用中文回答。5.3 测试技能调用OpenSquilla 的技能是按需加载的。我们测试几个内置技能。1. 文件操作技能在opensquilla chat中尝试 /skill file write ./test_hello.txt 你好OpenSquilla这会在当前目录创建一个文件。然后 /skill file read ./test_hello.txt应该能读取到文件内容。这验证了基本的文件工具和沙箱权限。2. 网络搜索技能首先你需要配置一个搜索提供商。可以通过 Web 控制台的 “Capability Center” - “Search”或使用 CLIopensquilla configure search --search-provider duckduckgo # 或者使用需要 API 密钥的 Exa # opensquilla configure search --search-provider exa --api-key-env EXA_API_KEY配置后在聊天中测试 /skill web_search “OpenSquilla 的最新版本是什么”如果配置正确它将返回网络搜索结果。3. 代码执行技能谨慎使用在安全沙箱内执行代码 /skill shell “python3 -c ‘print(11)’”这会在隔离环境中运行一个简单的 Python 命令。5.4 验证模型路由效果这是 OpenSquilla 的精华功能。为了验证路由是否生效你可以进行对比测试。简单查询问一个非常简单的、事实性的问题如“中国的首都是哪里”。观察 Web 控制台或日志如果日志级别调高看请求被发送到了哪个模型可能是较便宜的模型如 GPT-3.5-turbo 或 DeepSeek 的轻量版。复杂任务问一个需要多步推理、代码生成或创意写作的复杂问题。同样观察路由结果应该会被发送到更强大的模型如 GPT-4o、Claude Opus。你可以在 Web 控制台的会话历史中查看每轮对话turn的详细信息包括使用的模型、消耗的 Token 和估算成本。这是评估其成本节约效果最直接的方式。5.5 测试记忆功能记忆功能允许 AI 记住跨会话的信息。在聊天中说“记住我的名字是张三是一名后端工程师。”结束当前会话退出opensquilla chat。重新开启一个新的会话问“我之前告诉你我的职业是什么” 如果记忆功能正常工作AI 应该能回答“后端工程师”。记忆的底层是本地 SQLite 数据库结合了关键词搜索和向量语义搜索。你可以通过opensquilla memory相关的子命令进行管理。6. 接口 API 与批量任务OpenSquilla 不仅仅是一个聊天工具更是一个可以通过 API 调用的自动化代理服务。6.1 API 网关基础启动的网关服务 (opensquilla gateway run) 就是一个 ASGI 服务器提供了 RPC 接口。所有通过 Web UI 或 CLI 完成的操作理论上都可以通过 API 完成。健康检查端点GET http://127.0.0.1:18791/health或/healthz简单的存活检查。GET http://127.0.0.1:18791/control/api/health更详细的健康状态同opensquilla doctor。核心 RPC 接口主要功能通过 WebSocket RPC 或 HTTP POST 到/rpc端点调用。不过更常用的方式是通过官方提供的客户端 SDK如果有或直接使用opensquilla agent命令进行封装调用。6.2 通过命令行进行“API式”调用对于自动化脚本最直接的方式是使用opensquilla agent命令。# 单次任务调用返回 JSON 格式结果 opensquilla agent -m “分析当前目录下所有 .py 文件并列出其中的函数定义。” --json # 指定会话 ID进行连续对话 SESSION_ID”my_session” opensquilla agent -m “第一句话” --session $SESSION_ID --json opensquilla agent -m “基于上一句继续...” --session $SESSION_ID --json--json参数使得输出易于被其他程序解析。你可以将此命令嵌入到 Shell 脚本、Python 的subprocess或其他任何可以执行命令的环境中。6.3 定时任务CronOpenSquilla 内置了调度引擎可以创建定时任务。# 列出所有定时任务 opensquilla cron list # 创建一个每天上午9点运行的任务并将结果发送到 Slack 频道 opensquilla cron create \ --name “daily_report” \ --schedule “0 9 * * *” \ --channel slack \ --channel-args ‘{“channel”: “#general”}’ \ --prompt “生成昨日的团队工作摘要报告。” # 立即运行一次某个任务 opensquilla cron run daily_report定时任务可以配置为通过 Webhook 或聊天频道交付结果非常适合自动化报告、定时检查等场景。6.4 技能的直接调用部分技能也支持通过 CLI 直接调用便于集成。# 调用网络搜索技能 opensquilla skills invoke web_search --query “OpenSquilla GitHub stars” # 调用文件读取技能 opensquilla skills invoke file_read --path “/path/to/your/file.md”这为构建更复杂的工作流提供了基础模块。7. 资源占用与性能观察OpenSquilla 本身作为一个代理和路由层资源消耗主要分为两部分网关服务进程和本地模型路由/嵌入推理。1. 内存占用网关进程根据技能加载数量和会话并发数通常占用几百 MB 到 1 GB 左右的内存。可以通过系统监控工具如htop,任务管理器观察opensquilla相关进程。SquillaRouter (模型路由器)这是一个本地运行的 LightGBM ONNX 模型用于实时分类任务复杂度。它会在首次需要时加载到内存占用约 100-200 MB。如果未安装或禁用路由器则无此开销。2. CPU 占用日常路由决策和工具调用 CPU 占用很低。当执行本地嵌入模型计算用于记忆的语义搜索时会有短暂的 CPU 峰值。3. 网络 I/O主要的网络流量发生在与外部 LLM API 提供商和搜索 API 的通信上。你可以在网关日志中看到每个请求的耗时。性能观察点关注opensquilla doctor输出中各外部服务Provider、Search的延迟和状态。如果某个 API 响应慢会影响整体体验。4. 磁盘 I/O主要用于读写 SQLite 数据库会话、记忆、配置。首次运行或更新后可能会下载一些模型路由器的资源文件。优化建议按需启用功能如果暂时用不到记忆的语义搜索可以配置为仅使用关键词搜索避免加载嵌入模型。管理会话定期清理旧的、不活跃的会话可以减小数据库文件大小。选择合适的沙箱级别如果完全信任运行环境可以使用“标准”模式如果需要严格隔离使用“严格”或“锁定”模式但这可能会引入一些性能开销进程创建等。监控外部 API 成本使用opensquilla cost命令来查看各会话、各模型的 Token 使用量和估算成本这是优化支出的关键。8. 常见问题与排查方法部署和使用过程中可能会遇到一些问题这里列出常见问题的排查思路。问题现象可能原因排查方式解决方案启动失败提示DLL load failed(Windows)缺少 Visual C 运行时库导致 ONNX 运行时无法加载。查看启动日志错误信息。手动安装 VC 运行时1. 访问 https://aka.ms/vs/17/release/vc_redist.x64.exe 下载安装。2. 重启终端重新运行opensquilla gateway run。启动失败提示Library not loaded: rpath/libomp.dylib(macOS)缺少 OpenMP 库 (libomp)。查看启动日志错误信息。通过 Homebrew 安装brew install libomp然后重启网关。opensquilla命令未找到uv安装后 PATH 未更新或未在新终端中生效。运行which opensquilla(macOS/Linux) 或where.exe opensquilla(Windows)。1. 关闭并重新打开终端。2. 或运行uv tool update-shell更新 shell 配置。3. 确认安装时使用的 Python 环境。Web 控制台 (http://127.0.0.1:18791/control/) 无法访问网关服务未启动端口被占用防火墙阻止。1. 运行opensquilla gateway status。2. 检查端口18791是否被监听netstat -an | grep 18791(macOS/Linux) 或netstat -ano | findstr :18791(Windows)。1. 启动服务opensquilla gateway run。2. 更换端口opensquilla gateway run --port 18792。3. 检查防火墙设置允许本地回环地址访问。配置 LLM 提供商后聊天无响应或报错API 密钥错误网络不通提供商服务异常。1. 运行opensquilla doctor --json查看 Provider 部分状态。2. 检查环境变量中的 API 密钥是否正确设置。3. 尝试用curl直接调用提供商 API 测试连通性。1. 重新配置提供商opensquilla configure provider --provider openai --api-key-env OPENAI_API_KEY。2. 确保网络代理设置正确如果适用。3. 查看提供商状态页面。技能调用失败如web_search技能未配置或配置错误相关依赖未安装。1. 在 Web 控制台 “Capability Center” 检查技能状态。2. 运行opensquilla doctor查看具体错误。1. 配置对应技能如搜索opensquilla configure search --search-provider duckduckgo。2. 对于需要额外依赖的技能如matrix频道需安装对应 extrasOPENSQUILLA_INSTALL_EXTRASmatrix bash scripts/install_source.sh。模型路由器未生效总是使用同一个模型路由器被禁用路由器依赖库加载失败任务复杂度判断阈值设置问题。1. 运行opensquilla configure router status。2. 检查启动日志看是否有路由器加载错误。3. 在 Web 控制台查看会话详情观察“模型”字段。1. 启用路由器opensquilla configure router --router recommended。2. 根据第1、2条的错误信息解决运行时依赖问题VC/libomp。3. 检查opensquilla.toml配置文件中关于路由器的阈值设置。记忆功能不起作用记忆存储路径权限问题嵌入模型未加载。1. 检查~/.opensquilla/目录的读写权限。2. 运行opensquilla doctor查看 Memory 和 Embedding 状态。1. 确保当前用户对配置目录有写权限。2. 如果使用本地嵌入确保 ONNX 运行时正常。也可切换为远程嵌入如 OpenAI。通用排查流程首先运行opensquilla doctor这是最全面的健康检查工具能指出哪个模块出了问题。查看日志运行opensquilla gateway run在前台启动观察控制台输出的日志信息。更详细的日志可以通过设置环境变量OPENSQUILLA_LOG_LEVELDEBUG来获取。检查配置文件主配置文件位于~/.opensquilla/config.toml。检查其中的 provider、router、skills 等配置项是否正确。重置或重新配置如果问题集中在某个模块尝试使用opensquilla configure子命令重新配置该模块。9. 最佳实践与使用建议为了让 OpenSquilla 更稳定、高效、安全地运行可以参考以下建议1. 密钥管理永远不要将 API 密钥硬编码在配置文件或脚本中。使用环境变量来传递密钥例如OPENROUTER_API_KEY,OPENAI_API_KEY。在opensquilla onboard或configure时使用--api-key-env参数引用环境变量名。考虑使用.env文件需在配置中启用支持或系统的密钥管理工具。2. 沙箱安全根据使用场景选择合适的沙箱级别。在不受信任的环境或执行未知代码时务必使用Strict或Locked模式。仔细审查并授权需要高权限的工具调用如文件系统写操作、Shell 命令。OpenSquilla 支持人工审批流程对于敏感操作可以暂停等待确认。3. 成本控制充分利用SquillaRouter的自动路由功能这是节省成本的核心。定期使用opensquilla cost命令分析各模型的使用量和费用根据报告调整路由策略或预算。为不同的任务类型配置不同的“代理”或“会话”并为其绑定不同的默认模型或预算上限。4. 会话与记忆管理为长期项目或特定主题创建独立的会话Session避免记忆混淆。定期清理不再需要的会话和记忆片段以维持系统性能。利用记忆的“关键词搜索”和“语义搜索”组合提高信息检索的准确率。5. 技能开发与集成OpenSquilla 支持 MCP (Model Context Protocol) 和自定义技能。如果你有重复性的工作流程可以考虑将其封装成技能。在集成外部工具或 API 时注意做好错误处理和超时控制避免一个技能的失败导致整个代理卡住。6. 备份与迁移重要的配置和记忆数据位于~/.opensquilla/目录。定期备份此目录。如果需要迁移到新机器可以复制整个~/.opensquilla/目录注意 API 密钥等敏感信息。从 OpenClaw 或 Hermes Agent 迁移时务必先使用opensquilla migrate source --json进行预演检查迁移报告无误后再应用。7. 版本更新关注 GitHub 仓库的 Releases 页面及时获取功能更新和错误修复。更新前建议备份配置和数据。使用uv tool update opensquilla如果通过 uv 安装或按照新版安装说明进行操作。OpenSquilla 作为一个活跃的开源项目其核心价值在于提供了一个可扩展、成本感知、统一接口的 AI 代理框架。它可能不是解决某个单一问题的最强工具但它是串联起你手中各种 AI 能力和自动化流程的“胶水层”。对于开发者、技术团队和 AI 爱好者来说花时间部署和调优 OpenSquilla很可能在未来为你节省大量的时间和 API 调用费用。建议从简单的日常问答和文件处理开始体验逐步探索其频道集成、定时任务和自定义技能等高级功能将其融入你的个性化工作流中。 30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度