配置

SOBA 会从多个来源读取配置，优先级很清楚：CLI 参数 > 环境变量 > config.json > 默认值。本页说明主要选项，以及它们如何一起工作。

1. 配置文件

配置文件位于 ~/.soba/config.json。SOBA 首次运行时会自动创建，也可以手动创建。

{
  "baseUrl": "https://api.deepseek.com",
  "apiKey": "YOUR_API_KEY",
  "model": "deepseek/deepseek-v4-flash",
  "maxOutputTokens": 8192,
  "maxCompletionTokens": 0,
  "reasoning": { "mode": "provider_default" },
  "contextWindow": 65536,
  "temperature": 0.7,
  "maxAgentIterations": 0,
  "maxStalledIterations": 4,
  "maxRunMinutes": 0,
  "bashMaxTimeoutSeconds": 300,
  "sessionDir": "~/.soba/sessions",
  "lang": "zh",
  "theme": "graphite",
  "compaction": {
    "auto": true,
    "compactOnTurnComplete": true,
    "compactOnMilestone": true,
    "minTokensForAutoCompact": 32000,
    "minReclaimableTokens": 12000,
    "minSavingsRatio": 0.25,
    "keepRecentTokens": 20000,
    "safetyReserveTokens": 8192,
    "autoCompactThresholdRatio": 0.8,
    "timeoutMs": 15000
  },
  "registry": {
    "activeProvider": "deepseek",
    "activeModelId": "deepseek-v4-flash",
    "customProviders": []
  }
}

最小配置：

{
  "apiKey": "YOUR_API_KEY",
  "model": "deepseek/deepseek-v4-flash"
}

2. 参数列表

2.1. Provider 参数

2.2. 模型响应参数

2.3. 运行安全参数

2.4. 会话

2.5. 界面

3. 环境变量

环境变量会覆盖 config.json。

4. CLI 参数

CLI 参数拥有最高优先级。

4.1. 启动模式

4.2. Provider 与模型

4.3. 限制

4.4. 控制与调试

4.5. 信息

5. Provider 配置

SOBA v0.6.x 使用 provider registry。更多细节见 Provider 与模型。

内置 providers：

每个 provider 的模型会通过 GET /models 动态发现，并缓存在当前进程内。TUI 中用 F2 或 /model 打开模型选择器时，会刷新内置 providers。

Discovery 也会读取 context/output limits 与 reasoning capabilities。限额优先级为：用户显式设置 → runtime → active route → model metadata → 精确内置 profile → 保守 fallback。SOBA 不会从模型名称猜测 capabilities；assumed 值会显示 ~，选择时也会警告。

添加自定义 provider：

soba provider add my-llm \
  --base-url https://api.myllm.com/v1 \
  --api-key-env MY_LLM_KEY \
  --model my-code-model="My Code Model",128000,8192

自定义 providers 保存在 registry.customProviders 中。

模型特定的 wire-format 兼容性应在完整的 provider JSON 中声明，并通过 soba provider add <id> --from-file <path> 加载。例如，"compatibility": ["single_system_message"] 会让 SOBA 为拒绝多条 system messages 的 chat template 只发送一条位于开头的 system message。完整 schema 和支持的 features 请参阅模型兼容性元数据。

6. Compaction 配置

Compaction 通过 compaction 配置段控制。

Hard limit:

hardLimit = contextWindow - maxOutputTokens - safetyReserveTokens

当 effective tokens 超过 hardLimit 时，SOBA 会执行 blocking compaction。这个行为不能通过 auto: false 关闭。完整生命周期与阈值说明请参阅 Compaction 与 Context Capsules。

7. 优先级

CLI 参数
    ↓ 覆盖
环境变量
    ↓ 覆盖
config.json
    ↓ 覆盖
默认值

例如：config.json 中是 "theme": "graphite"，环境变量是 SOBA_THEME=forest，同时传入 --theme paper，最终会使用 paper。

特殊规则：

• Reasoning 优先级： request/session override → CLI → env → config → provider default。/reasoning 与 F4 无需重启即可影响下一次 model request。
• Requested 与 effective reasoning 分开保存；不支持的模式会明确 fallback 到 provider default，不会静默 clamp。
• maxOutputTokens 和 contextWindow 会从 active model 和 provider/runtime/route metadata 获取。CLI 与显式 model limits 可以覆盖 discovery。
• compaction.auto 可以通过 SOBA_AUTO_COMPACT=false 或 --no-auto-compact 覆盖。
• 关闭 auto-compaction 只会关闭软触发器；hard limit 和 provider overflow 恢复仍然强制执行。
• turn 和 milestone 只记录 pending intent；SOBA 会在下一次 model call 前显示进度并等待 compaction 完成。
• 数字 0 对 maxAgentIterations 和 maxRunMinutes 表示无限制；对 maxCompletionTokens 表示不显式限制。

8. 校验

SOBA 启动时会校验配置：

• API key 必须存在，除非所选 provider 不需要 key。
• model 必须存在。
• Compaction invariants 必须满足：
  • contextWindow > 0
  • maxOutputTokens > 0
  • safetyReserveTokens >= 0
  • maxOutputTokens + safetyReserveTokens < contextWindow
  • keepRecentTokens < contextWindow - maxOutputTokens - safetyReserveTokens

如果 compaction invariants 不满足，SOBA 会带着 warning 禁用 compaction：

⚠️  Compaction disabled: config validation failed:
    keepRecentTokens (50000) must be < hard limit (47360)