配置应用
选择 Bub 应用调用的模型和接入的渠道。这些配置属于应用；直接构造 core.Agent 时，在 Python 中传入模型与组件，参见构建自己的 Agent。
Bub 自己的配置按以下优先级（从高到低）读取：
- 进程环境（
BUB_*变量）。 - CLI 启动阶段加载的
.env值，或显式声明env_file=".env"的配置类读取到的.env值。 ~/.bub/config.yml（由bub onboard创建）。
当没有显式配置 Bub 凭证时，Bub 读取 <PROVIDER>_API_KEY 和 <PROVIDER>_API_BASE。提供商使用 Republic 名称，将连字符替换为下划线，例如 OPENROUTER_API_KEY、GOOGLE_API_KEY 和 AZURE_OPENAI_API_KEY。显式的 BUB_* 设置优先。
- Bub 已安装（
bub --help可用）。 - 你已拥有某个模型提供商的 API 密钥，或已运行
bub login codex完成 OAuth。
1. 运行交互式初始化
Section titled “1. 运行交互式初始化”bub onboard 依次引导你选择提供商、填写 API 密钥和必要的 URL、检查连接、搜索选择模型，再配置渠道与流式输出。托管服务使用默认 URL；自定义 OpenAI 兼容服务请选择 OpenAI-compatible。API 密钥留空可使用环境变量中的凭证。获取模型列表失败时，可以修改连接、重试或手动输入模型 ID。连接检查只获取模型列表，不发起模型生成请求。选择 Codex 时会跳过模型发现，直接手动输入模型。收集到的配置会替换 ~/.bub/config.yml；已有配置会作为本轮交互的默认值，未更新的字段会保留。插件可通过 onboard_config hook 添加自己的交互提示。
bub onboard配置文件默认位于 ~/.bub/config.yml。BUB_HOME 单独指定运行时数据目录，用于保存命令历史、Tape 和托管插件项目。嵌入 Bub 且需要不同配置路径时，请使用 BubFramework(config_file=...)。
2. 检查配置文件
Section titled “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。每个渠道的子键（如 telegram:）对应该渠道的 Settings 子类。
3. 用环境变量在运行时覆盖
Section titled “3. 用环境变量在运行时覆盖”可以用环境变量覆盖应用设置。常用设置采用 BUB_<UPPERCASE_KEY> 形式：
| 变量 | 用途 |
|---|---|
BUB_MODEL |
模型标识，如 openrouter:openrouter/free 或 codex:<model>。 |
BUB_API_KEY |
当前提供商的 API 密钥。使用 bub login codex 时保持未设置。 |
BUB_API_BASE |
覆盖提供商的基础 URL。保持未设置可使用所选提供商的默认端点。 |
BUB_HOME |
Bub 的运行时数据目录（命令历史、Tape、托管插件项目）。默认 ~/.bub；不会移动默认配置文件。 |
BUB_<PROVIDER>_API_KEY |
单个提供商的密钥，如 BUB_OPENROUTER_API_KEY。 |
BUB_<PROVIDER>_API_BASE |
单个提供商的基础 URL。 |
Republic 从 $CODEX_HOME/auth.json 或 ~/.codex/auth.json 读取并刷新 Codex 文件凭据。新登录需要安装 Codex CLI，然后选择 codex:<model> 并保持 BUB_API_KEY 未设置。OpenAI API 访问使用 openai:<model> 和 API 凭据。
公司代理、中转站或第二个账号可在 providers 下单独命名，再使用该名称作为模型前缀，见自定义提供商。
完整变量表（包括渠道防抖参数和高级模型客户端设置）见 设置参考。
4. 配置渠道凭据
Section titled “4. 配置渠道凭据”每个渠道有自己的设置前缀。内置 Telegram 渠道读取 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。
使用配置好的模型运行一轮对话：
bub run "say hi"命令会先打印路由标记 [<channel>:<chat_id>]，再显示响应正文。需要确认配置插件是否加载时，可以使用 bub hooks。