SOBA Agent - CLI coding agent with memory, MCP, and cozy TUI

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,
  "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,
    "backgroundTimeoutMs": 15000
  },
  "registry": {
    "activeProvider": "deepseek",
    "activeModelId": "deepseek-v4-flash",
    "customProviders": []
  }
}

最小配置：

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

2. 参数列表

2.1. Provider 参数

参数	类型	默认值	说明
`baseUrl`	`string`	`""`	OpenAI-compatible API 的 base URL。为空时从 active provider 推导
`apiKey`	`string`	`""`	API key
`model`	`string`	`""`	完整模型 ID，例如 `deepseek/deepseek-v4-flash` 或 `openrouter/anthropic/claude-sonnet-4.6`

2.2. 模型响应参数

参数	类型	默认值	说明
`maxOutputTokens`	`number`	`8192`	每次模型响应的最大输出 token。默认值只是占位；可用时会从 active model definition 读取真实值
`maxCompletionTokens`	`number`	`0`	reasoning/thinking token 上限。`0` 表示不显式限制，使用 provider 默认值
`contextWindow`	`number`	`128000`	模型上下文窗口。默认值是占位，通常从 active model definition 获取
`temperature`	`number`	`0.7`	采样温度，范围 0 到 2

2.3. 运行安全参数

参数	类型	默认值	说明
`maxAgentIterations`	`number`	`0`	单个任务内模型调用的紧急上限。`0` 表示无限制
`maxStalledIterations`	`number`	`4`	连续无进展多少次后认为循环卡住
`maxRunMinutes`	`number`	`0`	单个任务最大分钟数。`0` 表示无限制
`bashMaxTimeoutSeconds`	`number`	`300`	单次 `bash` tool 调用的最大 timeout

2.4. 会话

参数	类型	默认值	说明
`sessionDir`	`string`	`~/.soba/sessions`	JSONL 会话文件目录

2.5. 界面

参数	类型	默认值	说明
`lang`	`"en" \| "ru" \| "zh"`	`"en"`	默认界面语言
`theme`	`TuiThemeName`	`"graphite"`	TUI 主题：`graphite`、`ember`、`aurora`、`synthwave`、`paper`、`forest`、`highContrast`、`clay`、`operator`、`ink`

3. 环境变量

环境变量会覆盖 config.json。

变量	对应配置	说明
`SOBA_BASE_URL`	`baseUrl`	API base URL
`SOBA_API_KEY`	`apiKey`	API key
`SOBA_MODEL`	`model`	模型 ID
`SOBA_MAX_OUTPUT_TOKENS`	`maxOutputTokens`	输出 token 上限
`SOBA_MAX_COMPLETION_TOKENS`	`maxCompletionTokens`	reasoning token 上限
`SOBA_CONTEXT_WINDOW`	`contextWindow`	上下文窗口大小
`SOBA_MAX_AGENT_ITERATIONS`	`maxAgentIterations`	迭代上限
`SOBA_MAX_STALLED_ITERATIONS`	`maxStalledIterations`	stall recovery 前的无进展迭代次数
`SOBA_MAX_RUN_MINUTES`	`maxRunMinutes`	任务最大分钟数
`SOBA_BASH_MAX_TIMEOUT_SECONDS`	`bashMaxTimeoutSeconds`	单次 `bash` tool 调用最大 timeout
`SOBA_LANG`	`lang`	界面语言
`SOBA_THEME`	`theme`	TUI 主题
`SOBA_AUTO_COMPACT`	`compaction.auto`	`false` 或 `0` 会关闭 auto-compaction
`SOBA_SOUND_ENABLED`	`sound.enabled`	开启/关闭声音通知
`SOBA_SOUND_VOLUME`	`sound.volume`	音量 0.0 到 1.0
`SOBA_SOUND_REPEAT`	`sound.repeatMode`	`repeat`/`true`/`1` 表示重复，`once`/`false`/`0` 表示一次
`DEEPSEEK_API_KEY`	DeepSeek provider key	DeepSeek API key
`MOONSHOT_API_KEY`	Kimi provider key	Moonshot Kimi API key
`DASHSCOPE_API_KEY`	Alibaba provider key	Alibaba Qwen API key
`OPENROUTER_API_KEY`	OpenRouter provider key	OpenRouter API key

4. CLI 参数

CLI 参数拥有最高优先级。

4.1. 启动模式

参数	短参数	说明
`--interactive`	`-i`	启动交互式 TUI
`--continue`	`-c`	继续最近的会话
`--resume`	`-r`	通过交互式选择器恢复会话
`--session <id>`	`-s`	按 ID 继续指定会话

4.2. Provider 与模型

参数	短参数	说明
`--model <id>`	`-m`	覆盖模型 ID
`--api-key <key>`	`-k`	覆盖 API key
`--base-url <url>`		覆盖 API base URL

4.3. 限制

参数	说明
`--max-output-tokens <n>`	输出 token 上限
`--max-completion-tokens <n>`	reasoning/thinking token 上限
`--context-window <n>`	覆盖模型上下文窗口
`--budget <n>`	设置任务总 token 预算
`--max-agent-iterations <n>`	紧急迭代上限
`--max-stalled-iterations <n>`	stall recovery 前的无进展迭代次数
`--max-run-minutes <n>`	任务最大分钟数
`--bash-max-timeout-seconds <n>`	单次 `bash` tool 调用最大 timeout

4.4. 控制与调试

参数	说明
`--no-session`	交互模式但不保存会话
`--no-color`	关闭颜色
`--no-stream`	关闭 streaming
`--stream`	显式开启 streaming
`--debug`	将 loop decisions 写入 JSONL 会话文件
`--no-auto-compact`	关闭 proactive compaction，等同于 `compaction.auto: false`
`--lang <locale>`	覆盖界面语言：`en`、`ru`、`zh`
`--theme <name>`	覆盖 TUI 主题

4.5. 信息

参数	短参数	说明
`--help`	`-h`	显示帮助
`--version`	`-v`	显示版本

5. Provider 配置

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

内置 providers：

ID	名称	Base URL
`deepseek`	DeepSeek	`https://api.deepseek.com`
`kimi`	Moonshot Kimi (K2 for code)	`https://api.moonshot.cn/v1`
`alibaba`	Alibaba Qwen (Singapore)	`https://dashscope-intl.aliyuncs.com/compatible-mode/v1`
`openrouter`	OpenRouter	`https://openrouter.ai/api/v1`

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

添加自定义 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 中。

6. Compaction 配置

Compaction 通过 compaction 配置段控制。

参数	默认值	说明
`auto`	`true`	开启 proactive 后台 compaction
`compactOnTurnComplete`	`true`	每个 turn 完成后后台 compaction
`compactOnMilestone`	`true`	milestone checkpoint 时后台 compaction
`minTokensForAutoCompact`	`32000`	考虑 auto-compaction 的最低 effective tokens
`minReclaimableTokens`	`12000`	值得回收的最低 token 数
`minSavingsRatio`	`0.25`	最低节省比例，默认 25%
`keepRecentTokens`	`20000`	compaction 后保留的最近 token 数
`safetyReserveTokens`	`8192`	从 context window 中扣除的安全保留量
`backgroundTimeoutMs`	`15000`	后台 compaction 操作 timeout

Hard limit:

hardLimit = contextWindow - maxOutputTokens - safetyReserveTokens

当 effective tokens 超过 hardLimit 时，SOBA 会执行 blocking compaction。这个行为不能通过 auto: false 关闭。完整 compaction guide 当前在俄语文档中：Compaction and Context Capsules。

7. 优先级

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

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

特殊规则：

maxOutputTokens 和 contextWindow 会尽量从 active model definition 获取。CLI 参数可以覆盖它们，适合本地代理或模型元数据不准确的高级场景。
compaction.auto 可以通过 SOBA_AUTO_COMPACT=false 或 --no-auto-compact 覆盖。
数字 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)

配置

本頁目錄