OpenSquilla OpenSquilla
文档导航
文档 / 配置

配置

OpenSquilla 可以通过 onboarding 向导、Web UI 设置流程、CLI 命令、环境变量和 TOML 文件进行配置。日常设置请使用 CLI 命令，仅在进阶或脚本化部署时才编辑 TOML。

配置加载顺序

OpenSquilla 按以下顺序读取配置：

  1. OPENSQUILLA_GATEWAY_CONFIG_PATH
  2. ./opensquilla.toml
  3. ~/.opensquilla/config.toml
  4. 内置默认值

当你希望写入或查看项目本地的配置文件时，使用 --config ./opensquilla.toml。

密钥处理

密钥应优先使用环境变量引用：

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

不要将原始 API key 提交到 TOML 文件、shell 历史、示例或 issue 报告中。

首次运行向导

opensquilla onboard

常用选项：

opensquilla onboard --if-needed
opensquilla onboard --minimal
opensquilla onboard --provider openrouter --api-key-env OPENROUTER_API_KEY
opensquilla onboard --provider openai --model gpt-5.4-mini --api-key-env OPENAI_API_KEY
opensquilla onboard --provider ollama --model llama3.1
opensquilla onboard status

router 模式默认为 recommended。当你希望直接进行单模型路由时，使用 --router disabled。

重新配置单个章节

configure 命令用于编辑选定的章节：

opensquilla configure provider --provider openrouter --api-key-env OPENROUTER_API_KEY
opensquilla configure router --router recommended
opensquilla configure router --router openrouter-mix
opensquilla configure router --router disabled
opensquilla configure search --search-provider duckduckgo
opensquilla configure search --search-provider tavily --api-key-env TAVILY_API_KEY
opensquilla configure channels
opensquilla configure image-generation
opensquilla configure memory-embedding

支持的章节：

  • provider
  • router
  • channels
  • search
  • image-generation
  • memory-embedding

配置决策表

需求推荐命令
首次设置opensquilla onboard
CI 或安装脚本opensquilla onboard --if-needed
切换 provideropensquilla configure provider ...
启用或禁用 routeropensquilla configure router ...
配置 Web 搜索opensquilla configure search ...
配置消息平台opensquilla configure channels
查看当前值opensquilla config get
持久化进阶配置项opensquilla config set <key> <value> --config <path>

provider 配置

查看 provider 支持情况：

opensquilla providers list
opensquilla providers configure openrouter
opensquilla providers status

onboarding 已验证的 provider 包括：

  • OpenRouter
  • OpenAI
  • Anthropic
  • Ollama
  • DeepSeek
  • Gemini
  • DashScope / Qwen
  • Moonshot AI
  • Zhipu / Z.AI
  • 百度千帆
  • 火山引擎方舟

OpenSquilla 还在 provider 注册表中包含其他 OpenAI 兼容或自托管后端的条目。在你的安装环境中运行 opensquilla providers list 可以查看当前目录。

阅读：providers-and-models.md

router 配置

router 模式：

模式适用场景
recommended想要所选 provider 的默认路由配置。
openrouter-mix想要 OpenRouter 的混合模型默认配置。
disabled希望每个 turn 都使用一个固定配置的 provider/model。

命令：

opensquilla configure router --router recommended
opensquilla configure router --router openrouter-mix
opensquilla configure router --router disabled

router 支持的 provider 配置取决于已安装的构建版本和已配置的 provider。在使用直接 model 运行进行评测之前，请阅读 features/squilla-router.md。

搜索配置

查看搜索 provider：

opensquilla search list
opensquilla search status
opensquilla search query "OpenSquilla release notes"

配置搜索：

opensquilla configure search --search-provider duckduckgo
opensquilla configure search --search-provider bocha --api-key-env BOCHA_SEARCH_API_KEY
opensquilla configure search --search-provider brave --api-key-env BRAVE_SEARCH_API_KEY
opensquilla configure search --search-provider tavily --api-key-env TAVILY_API_KEY
opensquilla configure search --search-provider exa --api-key-env EXA_API_KEY

本构建中运行时支持的搜索 provider 包括 DuckDuckGo、Bocha、Brave Search、Tavily 和 Exa。DuckDuckGo 是免密钥路径。部分密钥的设置可以只配置一个带密钥的 provider；全密钥的设置可以暴露 BOCHA_SEARCH_API_KEY、BRAVE_SEARCH_API_KEY、TAVILY_API_KEY 和 EXA_API_KEY，从而在请求未指定明确 provider 时，让运行时的 provider 选择能够按模式和能力进行挑选。search_provider 是 search_api_key 和 search_api_key_env 的凭据锚点；它并不是对自动搜索的硬性路由承诺。其他 provider 的元数据可能用于未来或尚未在运行时支持的集成。

阅读：search.md

channel 配置

列出支持的 channel 类型：

opensquilla channels types --json
opensquilla channels describe feishu
opensquilla channels add telegram --name personal
opensquilla channels status

channel 保存会更新配置。编辑后请重启 gateway：

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

详见 channels.md。

记忆配置

实用命令：

opensquilla memory status
opensquilla memory index
opensquilla memory list
opensquilla memory search "project preference"
opensquilla memory show <path>
opensquilla memory dream
opensquilla memory flush-session <session-key>

配置 embedding 行为：

opensquilla configure memory-embedding

记忆可以将 Markdown 支撑的数据源与 SQLite 关键词索引和语义索引结合起来。记忆的具体形态取决于已配置的 provider 和本地 embedding 支持情况。

阅读：features/memory.md

sandbox 和权限

查看或更改策略：

opensquilla sandbox status
opensquilla sandbox on
opensquilla sandbox full
opensquilla sandbox bypass
opensquilla sandbox reset

一次性自动化权限：

opensquilla agent --permissions restricted -m "Read the repo and summarize it"
opensquilla agent --permissions full -m "Make a local patch and run tests"

对于必须停留在工作区内的无人值守自动化：

opensquilla agent \
  --workspace /path/to/project \
  --workspace-lockdown \
  --scratch-dir /path/to/project/.scratch \
  -m "Investigate and propose the smallest fix"

阅读：tools-and-sandbox.md

出站 URL 过滤与 Fake-IP DNS

抓取 URL 的工具会通过 opensquilla.tools.ssrf 中共享的 SSRF 防护来验证解析出的地址。私有、回环、链路本地和保留地址段默认被阻止。

某些受信任的代理或 fake-IP DNS 设置会把诸如 github.com 之类的公网主机名解析到 RFC 2544 基准地址段 198.18.0.0/15 中的地址。除非运维人员显式选择启用，否则 OpenSquilla 会持续阻止这些地址：

[tools]
trusted_fake_ip_cidrs = ["198.18.0.0/15"]

此设置只接受 198.18.0.0/15 的子网。即使配置了，回环地址、RFC 1918 私有段、链路本地地址以及其他内部地址段仍然被硬性阻止。如果某个公网主机名解析到这些被硬性阻止的地址段之一，请修复 DNS 或代理设置，而不要绕过该防护。

gateway 绑定

前台：

opensquilla gateway run --listen 127.0.0.1 --port 18791

托管：

opensquilla gateway start --json
opensquilla gateway status
opensquilla gateway stop
opensquilla gateway restart

绑定优先级：

  1. --listen
  2. --bind
  3. OPENSQUILLA_LISTEN
  4. OPENSQUILLA_GATEWAY_HOST
  5. config 中的 host
  6. 127.0.0.1

原始配置编辑

对于进阶设置，请查看 opensquilla.toml.example 并直接编辑当前生效的配置文件。常规的 provider、router、搜索、channel 和 sandbox 改动请使用 CLI 命令，可以避免常见的键结构错误。

手动修改文件后，请重启 gateway 并运行：

opensquilla doctor
opensquilla gateway status

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

在 GitHub 上编辑此页(英文原稿) OpenSquilla 文档 · 中文社区翻译