配置

Bub 按以下顺序读取配置，优先级从高到低：

环境变量（以 BUB_ 前缀开头）；
.env 文件：CLI 启动时自动从当前工作区中加载，或读取声明了 env_file=".env" 的配置类；
~/.bub/config.yml，由 bub onboard 创建。

对于配置中未声明的字段将使用配置类的默认值。完整的可写配置项见配置项。

1. 完成初始配置

在终端命令行中执行如下命令进入交互式配置流程，完成后写入 ~/.bub/config.yml 配置文件中。

bub onboard

2. 检查配置文件

现在可以检查 ~/.bub/config.yml，示例如下：

# ~/.bub/config.yml
model: openrouter:openrouter/free
api_key: sk-or-...
telegram:
  token: "123456789:your-telegram-bot-token"
  allow_users: "123456789,your_username"

3. 用环境变量覆盖

常用的环境变量如下所示：

变量	说明
`BUB_MODEL`	模型标识，如 `openrouter:openrouter/free`、`codex:<model>`。
`BUB_API_KEY`	当前提供商的 API 密钥；使用 `bub login codex` 时无需设置。
`BUB_API_BASE`	提供商的服务 URL；留空则使用默认端点。
`BUB_HOME`	运行时数据目录，默认为 `~/.bub`
`BUB_<PROVIDER>_API_KEY`	指定提供商的密钥，如 `BUB_OPENROUTER_API_KEY`。
`BUB_<PROVIDER>_API_BASE`	指定提供商的服务 URL。

完整变量表见配置项。

4. 配置模型与备用模型

model 配置使用 provider:model 格式设置。如主模型不可用时按顺序尝试备用模型（fallback model），在 ~/.bub/config.yml 中配置可进行修改：

model: openai:gpt-5-mini
fallback_models:
  - openrouter:openrouter/free

每个候选提供商都需要自己的有效凭据。fallback 只覆盖创建客户端和打开请求的失败；消息流已经开始后发生的错误不会换一个模型重放，以免重复产生副作用。完整规则见模型与 fallback。

5. 配置 Telegram 渠道（可选）

如果你打算把 Bub 当做一个 Telegram 机器人来使用，可以使用内置的 Telegram 渠道，配置示例如下：

BUB_TELEGRAM_TOKEN=123456789:your-telegram-bot-token
BUB_TELEGRAM_ALLOW_USERS=123456789,your_username
BUB_TELEGRAM_ALLOW_CHATS=-1001234567890
BUB_TELEGRAM_PROXY=http://127.0.0.1:7890   # 可选

点击查阅更多有关于 Telegram 渠道的配置项。

6. 验证

现在可以试着与 Bub 进行对话：

$ bub run "Can you introduce yourself?"

[cli:local]
I'm a virtual assistant designed to support a wide range of tasks including coding, design, research, and automation. I can integrate with code repositories, access web resources, leverage specialized skills, and streamline workflows. If you have specific tasks or questions about my capabilities, feel free to ask!