配置

本页说明如何配置 Bub：调用哪个模型、经哪个提供商访问、以及启动时加载哪些 channel 凭据。

Bub 自己的配置按以下优先级（从高到低）读取：

进程环境（BUB_* 变量）。
CLI 启动阶段加载的 .env 值，或显式声明 env_file=".env" 的 settings class 读取到的 .env 值。
~/.bub/config.yml（由 bub onboard 创建）。

当未显式提供 BUB_API_KEY 时，下游模型 SDK 仍可能读取自己的提供商变量，例如 OPENROUTER_API_KEY。Bub 的 settings 层只映射 BUB_* 变量。

开始之前

Bub 已安装（bub --help 可用）。
你已拥有某个模型提供商的 API key，或已运行 bub login openai 完成 OAuth。

1. 运行交互式初始化

bub onboard 依次引导你选择 provider、填写 API key 和必要的 URL、检查连接、搜索选择模型，再配置 channel 与流式输出。托管服务使用默认 URL；自定义 OpenAI 兼容服务请选择 OpenAI-compatible。API key 留空可使用环境变量中的凭证。获取模型列表失败时，可以修改连接、重试或手动输入模型 ID。连接检查只获取模型列表，不发起模型生成请求。已登录 OpenAI OAuth 时会跳过模型发现，直接手动输入模型。收集到的配置会替换 ~/.bub/config.yml；已有文件内容不会合并到本轮交互中。插件可通过 onboard_config hook 添加自己的交互提示。

bub onboard

文件默认位于 ~/.bub/config.yml。BUB_HOME 控制 bub.home，包括 history、tapes 与托管插件项目；它不会移动默认配置文件。嵌入 Bub 且需要不同配置路径时，请使用 BubFramework(config_file=...)。

2. 检查配置文件

最小配置示例：

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

顶层键对应 src/bub/builtin/settings.py 中的 AgentSettings。每个 channel 的子键（如 telegram:）对应该 channel 的 Settings 子类。

3. 用环境变量在运行时覆盖

每个 YAML 键都有对应的环境变量。规则是 BUB_<UPPERCASE_KEY>：

变量	用途
`BUB_MODEL`	模型标识，如 `openrouter:openrouter/free` 或 `openai:<codex-model>`。
`BUB_API_KEY`	当前提供商的 API key。使用 `bub login openai` 时保持未设置。
`BUB_API_BASE`	覆盖提供商的基础 URL。使用 Codex OAuth 时保持未设置，以便 Bub 路由到 Codex backend。
`BUB_HOME`	Bub 的运行时数据目录（history、tapes、托管插件项目）。默认 `~/.bub`；不会移动默认配置文件。
`BUB_<PROVIDER>_API_KEY`	单个提供商的 key，如 `BUB_OPENROUTER_API_KEY`。
`BUB_<PROVIDER>_API_BASE`	单个提供商的基础 URL。

使用 bub login openai 时，Bub 会从 CODEX_HOME 或 ~/.codex 读取 Codex OAuth 凭据，并自动 refresh。这个路径下使用 openai: provider 的模型标识，同时保持 BUB_API_KEY 和 BUB_API_BASE 未设置。

完整变量表（包括 channel 防抖参数和高级模型客户端设置）见 Settings 参考。

4. 配置 channel 凭据

每个 channel 有自己的设置前缀。内置 Telegram channel 读取 BUB_TELEGRAM_*：

BUB_TELEGRAM_TOKEN=123456:abcdef...
BUB_TELEGRAM_ALLOW_USERS=123456789,your_username
BUB_TELEGRAM_ALLOW_CHATS=-1001234567890
BUB_TELEGRAM_PROXY=http://127.0.0.1:7890   # 可选

这些变量驱动的消息处理与访问控制行为见 Telegram。

5. 验证

打印已加载 hook 映射：

bub hooks

跑一次端到端：

bub run "say hi"

预期输出会把每个 outbound 打印成两部分：先是一行 [<channel>:<chat_id>] 前缀，随后是消息正文。

后续阅读

Channels —— 选择 Bub 监听的接入面。
Telegram —— 配置机器人。
Settings 参考 —— 完整环境变量表。
部署 —— 把这份配置打入容器。