配置项
这些设置属于 Bub 应用；bub.core.Agent 不读取 YAML 或 BUB_*。插件可以注册自己的配置 section。
| 优先级 | 来源 | 说明 |
|---|---|---|
| 1 | 环境变量 | 设置类实例化时读取 |
| 2 | 当前目录 .env |
find_dotenv(usecwd=True)；不覆盖已有环境变量 |
| 3 | YAML 文件 | 默认 ~/.bub/config.yml，由 configure.load 载入 |
| 4 | 字段默认值 | 代码中的默认值 |
--workspace、--project、--enable-channel 是命令参数，不属于统一设置层。
设置实例在进程内缓存；首次 ensure_config() 后修改 os.environ，通常不会影响已创建的实例。
| 路径 | 来源 |
|---|---|
~/.bub/config.yml |
默认配置文件 |
BubFramework(config_file=Path(...)) |
构造参数，解析为绝对路径 |
BUB_HOME 只改变历史、Tape、插件项目和代码模式文件等运行时路径，不移动默认配置文件。
| 变量 | 默认值 | 说明 |
|---|---|---|
BUB_HOME |
~/.bub |
bub.home；也可在 .env 中设置 |
BUB_PROJECT |
<BUB_HOME>/bub-project |
bub install / uninstall / update 的项目目录 |
默认项目目录不存在时会自动创建；显式指定的其他目录必须已存在。
AgentSettings
Section titled “AgentSettings”平铺字段写在 YAML 顶层。
| 环境变量 | YAML | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
BUB_MODEL |
model |
str |
openrouter:openrouter/free |
provider:model |
BUB_COMMAND_PREFIX |
command_prefix |
str |
, |
非空、无空白，可以多字符 |
BUB_FALLBACK_MODELS |
fallback_models |
list[str] | null |
null |
JSON 数组；只用于配置的默认模型 |
BUB_API_KEY |
api_key |
str | dict | null |
未设置 | 通用密钥或提供商映射 |
BUB_API_BASE |
api_base |
str | dict | null |
未设置 | 通用地址或提供商映射 |
BUB_PROVIDERS |
providers |
dict |
{} |
JSON 对象，定义自定义提供商 |
BUB_MAX_STEPS |
max_steps |
int |
sys.maxsize |
单次 Run 的模型 Step 上限；须为正整数 |
BUB_MAX_TOKENS |
max_tokens |
int |
16384 |
默认输出上限；Codex 调用不传 |
BUB_SUBAGENT_MAX_CONCURRENCY |
subagent_max_concurrency |
int |
4 |
进程内同时运行的子 Agent 上限，超出的排队等待 |
BUB_SUBAGENT_TIMEOUT_SECONDS |
subagent_timeout_seconds |
int | null |
null |
单个子 Agent 运行的默认时限；null 表示不限 |
BUB_MODEL_TIMEOUT_SECONDS |
model_timeout_seconds |
int | null |
null |
一次模型调用（含流式）的秒数 |
BUB_CLIENT_ARGS |
client_args |
dict |
{} |
JSON 对象，传给模型客户端 |
BUB_COMPLETION_ARGS |
completion_args |
dict |
{} |
JSON 对象，传给每次生成 |
BUB_VERBOSE |
verbose |
int |
0 |
0 为 INFO，1 为 DEBUG，2 为 TRACE |
client_args 或 completion_args 为 null 时按 {} 处理。
| 配置 | 命令示例 |
|---|---|
, |
,help、,tape.info |
! |
!help |
/ |
Telegram 中使用 /bub /help |
CLI 和 Telegram 的命令解析器不同。
调用模型时按顺序取第一个非空值：
| 顺序 | 来源 |
|---|---|
| 1 | providers.<name>.api_key / .api_base |
| 2 | api_key / api_base 中对应提供商的映射值，或字段本身的字符串值 |
| 3 | 无 BUB_ 前缀的 <PROVIDER>_API_KEY / <PROVIDER>_API_BASE |
BUB_<PROVIDER>_API_KEY 和 BUB_<PROVIDER>_API_BASE 在启动时写入设置映射，优先级低于 BUB_API_KEY / BUB_API_BASE 和 YAML。
通用 api_key / api_base 为字符串时应用于所有提供商，并阻止映射和第 3 步回退；按提供商分设时使用映射或 BUB_<PROVIDER>_…。
模型与 fallback
Section titled “模型与 fallback”model 前缀 |
提供商或协议 |
|---|---|
openai: |
OpenAI 或 OpenAI 兼容端点 |
codex: |
ChatGPT 套餐登录 |
openrouter: |
OpenRouter |
anthropic: / google: / azure-openai: |
各提供商原生协议 |
ollama: / magpie: |
本地服务 |
完整提供商列表见 Republic providers。
fallback_models 只在当前模型与配置的 model 相同时生效。fallback 依次尝试打开请求；流开始消费后不再重试。
client_args
Section titled “client_args”| 键 | 行为 |
|---|---|
headers |
与默认 User-Agent: bub/<version> 合并；显式值优先 |
api_format |
OpenAI 兼容的 Chat Completions 端点通常设为 chat |
env_prefix |
默认 BUB_<PROVIDER>，供客户端读取提供商专用环境变量 |
timeout / max_retries |
传给底层客户端；总调用超时由 model_timeout_seconds 控制 |
api_key / api_base |
由 Bub 覆盖，不从 client_args 读取 |
注入的 HTTP 客户端必须为 httpx2.AsyncClient，生命周期由调用方管理。
completion_args
Section titled “completion_args”| 键 | 规则 |
|---|---|
max_tokens |
由 BUB_MAX_TOKENS 或调用级 max_tokens 覆盖；Codex 会移除 |
reasoning_effort |
会话或单次 Turn 的值覆盖此配置 |
tools |
由 Agent 根据当前 Step 填入 |
extra_body |
原样交给提供商；Anthropic 默认加入临时 cache control |
调用级 options 覆盖 completion_args 中的同名生成项。
自定义提供商
Section titled “自定义提供商”自定义提供商名称用作 model 的提供商前缀。
| 字段 | 必填 | 说明 |
|---|---|---|
type |
是 | 模仿的 Republic 提供商；未注册时配置校验失败 |
api_base |
否 | 缺省时回退到通用 api_base 或 BUB_<NAME>_API_BASE |
api_key |
否 | 缺省时回退到通用 api_key 或 BUB_<NAME>_API_KEY |
ChannelSettings
Section titled “ChannelSettings”平铺字段写在 YAML 顶层。
| 环境变量 | YAML | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
BUB_ENABLED_CHANNELS |
enabled_channels |
str |
all |
逗号分隔、all 或 !name |
BUB_DEBOUNCE_SECONDS |
debounce_seconds |
float |
1.0 |
每条活跃消息后重置的批次等待 |
BUB_MAX_WAIT_SECONDS |
max_wait_seconds |
float |
10.0 |
非活跃跟进消息的批次等待；不是总上限 |
BUB_ACTIVE_TIME_WINDOW |
active_time_window |
float |
60.0 |
最后一条活跃消息后，非活跃消息可加入的秒数 |
BUB_STREAM_OUTPUT |
stream_output |
bool |
false |
网关是否推送流式事件；bub chat 强制为 true |
只有 needs_debounce=True 的渠道使用缓冲。持续收到活跃消息时，BUB_MAX_WAIT_SECONDS 不会强制结束批次。
渠道选择规则见 CLI › 渠道选择。
TelegramSettings
Section titled “TelegramSettings”字段写在 YAML 的 telegram: section 下。
| 环境变量 | YAML | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
BUB_TELEGRAM_TOKEN |
token |
str |
"" |
非空时才启用渠道 |
BUB_TELEGRAM_ALLOW_USERS |
allow_users |
str | null |
未设置 | 用户 ID 或用户名，逗号分隔；空表示不限 |
BUB_TELEGRAM_ALLOW_CHATS |
allow_chats |
str | null |
未设置 | 聊天 ID，逗号分隔；空表示不限 |
BUB_TELEGRAM_PROXY |
proxy |
str | null |
未设置 | HTTP 或 SOCKS5 代理 URL |
| 条件 | 普通消息 | /start |
|---|---|---|
聊天 ID 不在 allow_chats |
静默忽略 | 回复固定拒绝文本 |
用户 ID 和用户名都不在 allow_users |
回复 Access denied. |
不检查用户 |
| 两者同时配置 | 必须同时满足 | 只检查聊天 |
SpillSettings
Section titled “SpillSettings”字段写在 YAML 的 spill: section 下。
| 环境变量 | YAML | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
BUB_SPILL_THRESHOLD |
threshold |
int |
4096 |
估算 token 上限，按 4 字符/token 计算；0 关闭新 spill |
工具结果超过阈值时写入 spill sidecar，模型收到预览和读取句柄。负数无法通过配置校验。
| 情形 | 行为 |
|---|---|
当前工具集没有 spill.read |
不创建新 spill，原样返回结果 |
结果已经是 spill.read 输出 |
不再 spill |
阈值为 0 |
停止创建新 spill，已有 sidecar 仍可读 |
第三方登录变量
Section titled “第三方登录变量”| 变量 | 默认值 | 读取方 | 说明 |
|---|---|---|---|
CODEX_HOME |
~/.codex |
bub login codex |
auth.json 所在目录；--codex-home 可覆盖 |
完整配置示例
Section titled “完整配置示例”以下示例包含所有内置 YAML 字段；不需要的字段可以省略。
model: openrouter:openrouter/freecommand_prefix: ","fallback_models: - openai:gpt-5.5api_key: openrouter: sk-or-...api_base: openrouter: https://openrouter.ai/api/v1providers: proxy: type: openai api_base: https://llm-proxy.example.com/v1 api_key: "your-provider-api-key"max_steps: 100max_tokens: 16384model_timeout_seconds: 120client_args: timeout: 60 max_retries: 2completion_args: reasoning_effort: mediumverbose: 0
enabled_channels: alldebounce_seconds: 1.0max_wait_seconds: 10.0active_time_window: 60.0stream_output: false
spill: threshold: 4096
telegram: token: "your-telegram-bot-token" allow_users: "123456789,your_username" allow_chats: "-1001234567890" proxy: socks5://127.0.0.1:7890