快速开始

本指南帮助你在本地完成 OpenSquilla 的安装、配置与运行。它假定你需要标准的产品体验：终端命令、本地 Web UI、SquillaRouter、记忆/搜索支持以及安全的本地默认配置。

环境要求

终端安装需要 Python 3.12 或更新版本。
推荐的终端安装方式需要 uv。
仅当从源码安装时才需要 Git 和 Git LFS。
除非使用 Ollama 等本地 provider，否则需要一个 provider API 密钥。

首次运行设置

交互式设置：

opensquilla onboard

适合脚本的设置：

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

常用变体：

opensquilla onboard --if-needed
opensquilla onboard --minimal
opensquilla onboard --provider openai --api-key-env OPENAI_API_KEY
opensquilla onboard --provider ollama --model llama3.1

--if-needed 适合用于安装脚本，因为它不会重写已经就绪的配置。--minimal 仅配置 provider 路径，跳过可选的 channels/搜索/图像生成部分。

查看 onboarding 状态：

opensquilla onboard status

运行 gateway

前台运行 gateway：

opensquilla gateway run

后台运行 gateway 并等待就绪：

opensquilla gateway start --json
opensquilla gateway status

默认地址：

http://127.0.0.1:18791/control/

为了安全起见，gateway 默认监听回环地址。如需绑定到其他地址，需要显式开启：

opensquilla gateway run --listen 0.0.0.0 --port 18791

只有在配置了合适的认证和网络管控的前提下，才应将非回环地址的 gateway 暴露出去。

首次有效运行

打开 Web UI：

http://127.0.0.1:18791/control/

启动终端聊天：

opensquilla chat

运行一次自动化 turn：

opensquilla agent -m "Inspect this workspace and suggest a test plan"

在指定 workspace 中运行一次性任务：

opensquilla agent \
  --workspace /path/to/project \
  --workspace-strict \
  -m "Review the current diff and list the highest-risk changes"

使用 Web UI 进行基于浏览器的聊天、审批、设置、channels、用量与日志管理。需要终端对话时使用 opensquilla chat。需要一次性自动化时使用 opensquilla agent。

恢复工作

恢复一个终端 chat session：

opensquilla chat --session <session-key>

查看 sessions：

opensquilla sessions list
opensquilla sessions show <session-key>
opensquilla sessions export <session-key>

当精确的历史记录对调试或交接至关重要时，可导出 session。

检查就绪状态

设置完成后运行以下命令：

opensquilla doctor
opensquilla providers list
opensquilla search list
opensquilla channels types --json

如果 gateway 正在运行，可以查看运行时状态：

opensquilla gateway status
opensquilla providers status
opensquilla channels status
opensquilla memory status

关于 provider/模型选择的详细信息，请参见 providers-and-models.md。关于搜索设置，请参见 search.md。

关于 gateway 生命周期、主机/端口以及暴露方式的指引，请参见 gateway.md。

停止或重启

前台 gateway：

Ctrl+C

托管的后台 gateway：

opensquilla gateway stop
opensquilla gateway restart

后续步骤

完成首次运行后：

如果你需要联网调研，请配置搜索：search.md。
如果你需要 Slack、Telegram、Feishu/Lark 或其他消息接入面，请启用 channels：channels.md。
如果你需要持久化的回忆，请查阅记忆相关行为：features/memory.md。
在进行无人值守自动化之前，请检查 tool 权限：tools-and-sandbox.md。
如果你希望进行成本感知的模型 routing，请了解 SquillaRouter：features/squilla-router.md。
如果对产品术语不熟悉，请使用术语表：glossary.md。

从源码安装

当你需要一个基于检出仓库的安装时，使用源码安装：

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

用于开发时，请使用仓库虚拟环境：

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

从源码开发时，请在命令前加上 uv run，以确保使用的是你正在编辑的检出。

文档索引 · 产品指南 · 改进此页面 · 报告文档问题