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>

工具策略

进阶的脚本化运行可以通过 [tools] 收窄模型可见的工具面。若要在其他条件完全相同的运行之间比较工具面，请保持调用侧 harness 不变，并把工具差异表达在配置中：

[tools]
profile = "coding"
also_allow = ["retrieve_tool_result"]
deny = ["execute_code", "background_process", "process"]
file_edit_requires_fresh_read = true
file_edit_flexible_recovery = true

profile = "coding" 保留文件系统、搜索、shell、session 和记忆工具可用，并在编辑工作区中已有文件之前启用新鲜的 read_file 上下文。上面的 deny 列表为收窄的运行移除了额外的 Python/后台进程工具面；如需默认的 coding 工具面，省略它即可。 file_edit_flexible_recovery 默认为 true：当精确的 old_text 未命中后，edit_file 可以应用唯一的空白/缩进恢复，并为诊断记录已使用或被拒绝的恢复事件。

provider 配置

查看 provider 支持情况：

opensquilla providers list
opensquilla providers configure openrouter
opensquilla providers status

onboarding 已验证的 provider 包括：

  • TokenRhythm
  • 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
opensquilla configure search --search-provider iqs --api-key-env IQS_SEARCH_API_KEY

本构建中运行时支持的搜索 provider 包括 DuckDuckGo、Bocha、Brave Search、阿里云 IQS、Tavily 和 Exa。DuckDuckGo 是免密钥路径。部分密钥的设置可以只配置一个带密钥的 provider；全密钥的设置可以暴露 BOCHA_SEARCH_API_KEY、BRAVE_SEARCH_API_KEY、IQS_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。

附件

附件摄取接受任意文件类型。可渲染的类别（图片、PDF、文本、Office 文档、邮件）会被提取或内联给模型；其他所有文件都是*不透明（opaque）*附件：其字节会被暂存到 agent 工作区供工具访问，绝不会被解析、解压或内联进 provider prompt。

[attachments]
# Admit opaque (non-rendered) attachment types: archives, binaries,
# audio/video, unknown formats. false restores the legacy fail-closed
# rendered-types-only admission gate on every surface.
accept_opaque = true
# Per-file ceiling for opaque attachments (bytes).
opaque_max_bytes = 31457280            # 30 MiB
# Aggregate RAM ceiling for the in-memory staged-upload store. When reached,
# new uploads get HTTP 507 UPLOAD_STORE_FULL (retryable; staged entries
# expire within the 10-minute TTL); a payload larger than the cap itself is a
# permanent 413. Non-positive or invalid values fall back to the default —
# this cap can be raised but not disabled. Requires a gateway restart.
upload_store_max_total_bytes = 314572800    # 300 MiB
# Disk budget for attachment copies materialized into an agent workspace
# (<workspace>/.opensquilla/attachments). When exceeded, new materializations
# degrade to an unavailable marker; existing files are never evicted. Set to
# 0 (or any non-positive value) to disable the budget entirely.
workspace_attachment_disk_budget_bytes = 1073741824  # 1 GiB
# Persist attachment bytes with session transcripts.
persist_transcripts = true
# media_root = ""                      # default: resolved from the cache dir
transcript_disk_budget_bytes = 2147483648   # 2 GiB
artifact_max_bytes = 31457280               # 30 MiB
artifact_disk_budget_bytes = 536870912      # 512 MiB

环境变量覆写使用 OPENSQUILLA_ATTACHMENTS_ 前缀 （OPENSQUILLA_ATTACHMENTS_ACCEPT_OPAQUE、OPENSQUILLA_ATTACHMENTS_OPAQUE_MAX_BYTES 等）。

大小策略速览：不超过 2 MB 的内联附件随 RPC 消息传输；更大的文件通过 POST /api/v1/files/upload 暂存（10 分钟 TTL），文本（需通过整体载荷的 UTF-8 校验）、PDF、Office 和不透明类型每个文件最多 30 MiB。邮件始终受 2 MB 文本上限约束且从不走暂存。每个 turn：最多 10 个附件、共 60 MiB。

行为说明：

  • 当 accept_opaque = true（默认值）时，上传端点不再对未渲染类型返回 HTTP 415 UNSUPPORTED_MEDIA_TYPE，sessions.send 也不再拒绝它们；关闭该开关的严格部署会保持原有错误与错误码不变。
  • 不透明文件只以转义后的元数据信封加工作区路径标记的形式到达模型；agent 在当前安全层级与审批策略下，用文件系统、shell 或代码工具检查或转换它们。在没有 sandbox 后端的平台上，这些工具操作依赖人工审批。

记忆配置

实用命令：

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 文档 · 中文社区翻译