wehub/opensquilla--opensquilla
1
0
Fork 0
Code Issues Pull Requests Actions 1 Deployments Models Agent Notes Packages Projects Releases Wiki Activity
Files
aacb60a4af7ecfef16d9c2f02c51c413c58f08c0
opensquilla--opensquilla/docs/configuration.md
T
wehub-resource-sync aacb60a4af chore: import upstream snapshot with attribution
2026-07-13 13:12:33 +08:00

12 KiB
Raw Blame History

Configuration

OpenSquilla can be configured from the onboarding wizard, the Web UI setup flow, CLI commands, environment variables, and TOML files. Use CLI commands for routine setup and edit TOML only for advanced or scripted deployments.

Config Load Order

OpenSquilla reads configuration in this order:

  1. OPENSQUILLA_GATEWAY_CONFIG_PATH
  2. ./opensquilla.toml
  3. ~/.opensquilla/config.toml
  4. built-in defaults

Use --config ./opensquilla.toml when you want to write or inspect a project-local config file.

Secret Handling

Prefer environment-variable references for secrets:

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

Avoid committing raw API keys to TOML files, shell history, examples, or issue reports.

First-Run Wizard

opensquilla onboard

Common options:

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

The router mode defaults to recommended. Use --router disabled when you want direct single-model routing.

Reconfigure One Section

The configure command edits a selected section:

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

Supported sections:

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

Configuration Decision Table

Need Preferred command
First setup opensquilla onboard
CI or install scripts opensquilla onboard --if-needed
Change provider opensquilla configure provider ...
Enable or disable routing opensquilla configure router ...
Configure web search opensquilla configure search ...
Configure messaging platforms opensquilla configure channels
Inspect current values opensquilla config get
Persist an advanced key opensquilla config set <key> <value> --config <path>

Tool Policy

Advanced scripted runs can narrow the model-visible tool surface with [tools]. To compare tool surfaces across otherwise identical runs, keep the calling harness unchanged and express the tool difference in config:

[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" keeps filesystem, search, shell, session, and memory tools available, and enables fresh read_file context before existing workspace file edits. The deny list above removes the extra Python/background process surfaces for a narrowed run; omit it for the default coding surface. file_edit_flexible_recovery defaults to true: after an exact old_text miss, edit_file may apply a unique whitespace/indentation recovery and records used or rejected recovery events for diagnostics.

Provider Configuration

Inspect provider support:

opensquilla providers list
opensquilla providers configure openrouter
opensquilla providers status

Onboarding-verified providers include:

  • TokenRhythm
  • OpenRouter
  • OpenAI
  • Anthropic
  • Ollama
  • DeepSeek
  • Gemini
  • DashScope / Qwen
  • Moonshot AI
  • Zhipu / Z.AI
  • Baidu Qianfan
  • Volcengine Ark

OpenSquilla also carries provider registry entries for additional OpenAI-compatible or self-hosted backends. Use opensquilla providers list on your install to see the current catalog.

Read: providers-and-models.md

Router Configuration

Router modes:

Mode Use when
recommended You want the selected provider's default routing profile.
openrouter-mix You want OpenRouter mixed-model defaults.
disabled You want one configured provider/model for every turn.

Commands:

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

Router-supported provider profiles depend on the installed build and configured provider. Read features/squilla-router.md before using direct model runs for evaluation.

Search Configuration

Inspect search providers:

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

Configure search:

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

Runtime-supported search providers in this build include DuckDuckGo, Bocha, Brave Search, Alibaba Cloud IQS, Tavily, and Exa. DuckDuckGo is the no-key path. A partial-key setup can configure only one keyed provider; an all-key setup can expose BOCHA_SEARCH_API_KEY, BRAVE_SEARCH_API_KEY, IQS_SEARCH_API_KEY, TAVILY_API_KEY, and EXA_API_KEY so runtime provider selection can choose by mode and capability unless a request names an explicit provider. search_provider is the credential anchor for search_api_key and search_api_key_env; it is not a hard routing promise for automatic searches. Additional provider metadata may be present for future or not-yet-runtime-supported integrations.

Read: search.md

Channel Configuration

List supported channel types:

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

Channel saves update configuration. Restart the gateway after edits:

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

See channels.md for details.

Attachments

Attachment ingestion accepts any file type. Rendered families (images, PDF, text, Office documents, email) are extracted or inlined for the model; everything else is an opaque attachment: the bytes are staged into the agent workspace for tool access and are never parsed, decompressed, or inlined into a 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

Env overrides use the OPENSQUILLA_ATTACHMENTS_ prefix (OPENSQUILLA_ATTACHMENTS_ACCEPT_OPAQUE, OPENSQUILLA_ATTACHMENTS_OPAQUE_MAX_BYTES, …).

Size policy at a glance: inline attachments up to 2 MB ride the RPC message; larger files stage through POST /api/v1/files/upload (10-minute TTL) up to 30 MiB per file for text (whole-payload UTF-8 proven), PDF, Office, and opaque types. Email is always capped at the 2 MB text limit and never stages. Per turn: at most 10 attachments and 60 MiB total.

Behavior notes:

  • With accept_opaque = true (the default), the upload endpoint no longer returns HTTP 415 UNSUPPORTED_MEDIA_TYPE for unrendered types, and sessions.send no longer rejects them; strict deployments that disable the flag keep the legacy errors and codes unchanged.
  • Opaque files reach the model only as an escaped metadata envelope plus a workspace path marker; the agent inspects or converts them with filesystem, shell, or code tools under the active safety tier and approval policy. On platforms without a sandbox backend those tool actions rely on approvals.

Memory Configuration

Useful commands:

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>

Configure embedding behavior:

opensquilla configure memory-embedding

Memory can combine Markdown-backed sources with SQLite keyword and semantic indexes. The exact memory shape depends on the configured provider and local embedding support.

Read: features/memory.md

Sandbox and Permissions

Inspect or change posture:

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

Single-shot automation permissions:

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

For unattended automation that must stay inside a workspace:

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

Read: tools-and-sandbox.md

Outbound URL Filtering And Fake-IP DNS

URL-fetching tools validate resolved addresses through the shared SSRF guard in opensquilla.tools.ssrf. Private, loopback, link-local, and reserved ranges are blocked by default.

Some trusted proxy or fake-IP DNS setups resolve public hostnames such as github.com to addresses in the RFC 2544 benchmark range 198.18.0.0/15. OpenSquilla keeps blocking those addresses unless the operator explicitly opts in:

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

Only subnets of 198.18.0.0/15 are accepted in this setting. Loopback, RFC 1918 private ranges, link-local addresses, and other internal ranges remain hard-blocked even if configured. If a public hostname resolves to one of those hard-blocked ranges, fix the DNS or proxy setup instead of bypassing the guard.

Gateway Binding

Foreground:

opensquilla gateway run --listen 127.0.0.1 --port 18791

Managed:

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

Bind precedence:

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

Raw Config Editing

For advanced settings, inspect opensquilla.toml.example and edit the active config file directly. Use CLI commands for routine provider, router, search, channel, and sandbox changes because they avoid common key-shape mistakes.

After changing files by hand, restart the gateway and run:

opensquilla doctor
opensquilla gateway status

Docs index · Product guide · Improve this page · Report a docs issue

Reference in New Issue View Git Blame Copy Permalink