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

内置 DeepSeek、Moonshot Kimi、Alibaba Qwen、OpenRouter providers，动态模型发现和自定义 providers。

SOBA 可以使用任何 OpenAI-compatible API。本页说明如何使用内置 providers、切换模型、添加自定义 providers，以及排查常见连接问题。

v0.4.0 的重要变化： 模型不再保存在硬编码列表里。SOBA 会通过 GET /v1/models 动态发现模型，所以 provider 新增模型后，通常不需要等待 SOBA 发版。

1. 架构

SOBA 使用 provider registry。它包含：

内置 providers：4 个预置 base URL 的 provider
自定义 providers：用户添加的任意 OpenAI-compatible API
动态模型发现：从 provider API 拉取模型列表，并缓存在内存中

┌──────────────────────────────────────────┐
│              Registry                    │
│                                          │
│  ┌────────────────┐  ┌────────────────┐ │
│  │ Built-in       │  │ Custom         │ │
│  │ Providers (4)  │  │ Providers (∞)  │ │
│  └────────────────┘  └────────────────┘ │
│                                          │
│  ┌────────────────────────────────────┐  │
│  │ Dynamic Model Discovery             │  │
│  │ GET /v1/models → in-memory cache    │  │
│  └────────────────────────────────────┘  │
└──────────────────────────────────────────┘

2. 内置 providers

SOBA v0.4.0 提供 4 个内置 providers。它们都使用 OpenAI-compatible adapter。

ID	名称	Base URL	API key env	说明
`deepseek`	DeepSeek	`https://api.deepseek.com`	`DEEPSEEK_API_KEY`	V3、R1、Coder
`kimi`	Moonshot Kimi	`https://api.moonshot.cn/v1`	`MOONSHOT_API_KEY`	Kimi K2 很适合代码
`alibaba`	Alibaba Qwen	`https://dashscope-intl.aliyuncs.com/compatible-mode/v1`	`DASHSCOPE_API_KEY`	Qwen3、Qwen-Coder，新加坡区域
`openrouter`	OpenRouter	`https://openrouter.ai/api/v1`	`OPENROUTER_API_KEY`	可路由 Claude、GPT、Gemini、Llama 等大量模型

2.1. 动态发现

启动时，SOBA 会对 active provider 调用 GET {baseUrl}/models。结果缓存在当前进程内。随后 SOBA 会选择一个合适的默认模型，并优先选择偏代码的模型。

缓存只存在于内存中。要刷新它，请重启 SOBA，或在 TUI 里用 Ctrl+M 打开模型选择器。

3. 选择模型

3.1. 查看可用模型

soba provider list

输出会按 provider 分组展示 providers 和模型。当前 active model 会带星号。

3.2. 选择模型

在 TUI 中可以用 Ctrl+M 切换模型。单次运行可以通过 CLI 或 env 传入模型：

# 单次 CLI 运行
soba --model deepseek-v4-flash "Check the project"

# 环境变量
export SOBA_MODEL="anthropic/claude-sonnet-4.6"

soba provider use <id> 会把 active provider 切到它的 default model。自定义 providers 可以用 --default-model 设置默认模型；未设置时使用第一个 --model。

3.3. 实用模型选择

这不是永久排行榜，只是截至 2026 年 6 月 21 日的实用参考。跑大任务前建议先看 soba provider list：模型别名、价格和限制都变得很快。

任务	推荐模型	原因
快速、便宜的编码	`deepseek/deepseek-v4-flash`	适合日常改动的快速 DeepSeek V4 模型。旧的 `deepseek-chat` / `deepseek-reasoner` 现在主要是兼容别名
推理和复杂验证	`deepseek/deepseek-v4-pro`	更重的 DeepSeek V4 模型，适合需要仔细推理、验证和排查的任务
最高质量的 agentic code	`openrouter/openai/gpt-5.5`	当 tool-heavy agent loop 需要最高质量时使用：规划、修改、验证和谨慎的最终答复。直接使用 OpenAI API 时模型 id 是 `gpt-5.5`
复杂编码任务	`openrouter/anthropic/claude-sonnet-4.6`	适合大型重构、代码库导航和 agentic work
长周期 agent 任务	`openrouter/minimax/minimax-m3`	MiniMax M3 上下文很长，适合持续使用工具的任务；直接走 MiniMax API 时模型 id 是 `MiniMax-M3`
Kimi 编码	`kimi/kimi-k2.7-code`	当前的 Kimi 编码模型；需要速度时可以试 `kimi-k2.7-code-highspeed`
Qwen 编码	`openrouter/qwen/qwen3-coder`	适合作为 agentic coding、tool use 和大型仓库场景的备选
免费试用	`openrouter/free`	OpenRouter 会选择可用的免费模型；具体 `:free` id 经常变化
本地工作	custom provider → Ollama	`http://localhost:11434/v1`

4. 自定义 providers

任何 OpenAI-compatible API 都可以添加成自定义 provider。

4.1. 添加 provider

# Ollama，本地且不需要 key
soba provider add ollama \
  --base-url http://localhost:11434/v1 \
  --model llama3.1="Llama 3.1",8192,2048

# 本地模型建议从较小限制开始：
# 8192 = contextWindow，2048 = maxOutput。
# 128000,8192 可能会明显压到笔记本内存。

# Groq
soba provider add groq \
  --base-url https://api.groq.com/openai/v1 \
  --api-key-env GROQ_API_KEY \
  --model llama-3.3-70b-versatile="Llama 3.3 70B",128000,8192

# Together AI
soba provider add together \
  --base-url https://api.together.xyz/v1 \
  --api-key-env TOGETHER_API_KEY \
  --model meta-llama/Llama-3.3-70B-Instruct-Turbo="Llama 3.3 70B",128000,8192

# 任意 self-hosted OpenAI-compatible API
soba provider add my-api \
  --base-url https://my-llm.company.com/v1 \
  --api-key-env MY_LLM_KEY \
  --model company-code-model="Company Code Model",128000,8192

4.2. `soba provider add` 参数

参数	必填	说明
`<id>`	是	唯一 provider ID，只允许字母、数字和短横线
`--base-url <url>`	是	OpenAI-compatible API base URL
`--api-key-env <VAR>`	否	存放 API key 的环境变量名。省略时认为 provider 不需要 key
`--name <name>`	否	展示名称
`--model <spec>`	是	模型规格：`id=name,contextWindow,maxOutput[,supportsStreaming[,supportsThinking]]`。可重复
`--default-model <id>`	否	默认模型。省略时使用第一个 `--model`
`--adapter <openai\|anthropic>`	否	Provider adapter。当前 runtime 路径主要面向 OpenAI-compatible API
`--from-file <path>`	否	从 JSON 文件加载 provider 定义
`--set-active`	否	添加后立即设为 active provider

4.3. 管理自定义 providers

# 查看 provider 定义
soba provider show ollama

# 设为 active provider
soba provider use ollama

# 删除自定义 provider
soba provider remove ollama

目前没有 update 命令。要修改 URL 或模型列表，请先删除自定义 provider，再重新添加。

4.4. 存储位置

自定义 providers 保存在 ~/.soba/config.json 的 registry.customProviders 中：

{
  "registry": {
    "activeProvider": "deepseek",
    "activeModelId": "deepseek-v4-flash",
    "customProviders": [
      {
        "id": "ollama",
        "name": "Ollama (Local)",
        "baseUrl": "http://localhost:11434/v1",
        "apiKeyEnv": "OLLAMA_API_KEY",
        "adapter": "openai"
      }
    ]
  }
}

5. CLI 管理

完整的 soba provider 命令：

# 帮助
soba provider help

# 列出 providers 和模型
soba provider list

# 选择 active provider 以及它的 default model
soba provider use deepseek

# 添加自定义 provider
soba provider add <id> --base-url <url> --model <spec> [--api-key-env <VAR>] [--name <name>]

# 删除自定义 provider
soba provider remove <id>

# 查看 provider 定义
soba provider show <id>

Provider 和模型管理目前主要通过 CLI 命令和 TUI 模型选择器完成。

6. 认证

6.1. API key 来源

优先级：

已保存的 provider key：registry.providers.<providerId>.apiKey，通常由首次启动 wizard 为内置 providers 创建
Provider-specific 环境变量：DEEPSEEK_API_KEY、MOONSHOT_API_KEY、DASHSCOPE_API_KEY、OPENROUTER_API_KEY
Legacy flat config：SOBA_API_KEY 或 apiKey，作为 fallback 保留

对于 registry providers，更推荐 provider-specific env vars 或已保存的 provider key。

6.2. 自定义 providers

使用 --api-key-env MY_VAR 时，SOBA 会从 process.env.MY_VAR 读取 key。如果省略 --api-key-env，provider 会被认为不需要 key，这对本地 OpenAI-compatible server 很方便。

7. 诊断

7.1. 检查连接

# 直接检查 API
curl -H "Authorization: Bearer $DEEPSEEK_API_KEY" https://api.deepseek.com/models

# 通过 SOBA 检查
soba provider list

7.2. 常见问题

问题	原因	解决办法
`401 Unauthorized`	API key 错误	检查 provider-specific env vars 或保存的 provider key
`404 Not Found`	base URL 错误	检查 `--base-url` 或配置
`Model not found`	provider 不提供该模型	检查 `soba provider list`，打开 `Ctrl+M`，或传入有效的 `--model`
`Context overflow`	超过 context window	降低 `maxOutputTokens` 或使用 compaction
`429 Too Many Requests`	provider rate limit	等待，或降低请求频率
Timeout	provider 没有响应	检查网络，或换一个 provider

7.3. 刷新模型缓存

模型缓存在当前进程内。如果 provider 新增了模型，请重启 SOBA，或打开 Ctrl+M 选择器重新 discovery。

7.4. 遇到问题时切换 provider

soba provider use openrouter
soba --model meta-llama/llama-3.3-70b-instruct "Continue the task"

Provider 与模型