设置

本页列出 Bub 读取的全部 BUB_* 环境变量、它们在 ~/.bub/config.yml 中的 YAML 字段，以及定义它们的 pydantic-settings 类。部署示例见运维 › 配置。

优先级

Bub 按以下顺序解析配置值,优先级从高到低:

CLI 参数(例如 --workspace、--project、--enable-channel)。
环境变量(BUB_*)。
.env 值，来自 CLI 启动阶段的加载，或声明了 env_file=".env" 的 settings class。
~/.bub/config.yml 中的字段,由 bub.configure.load 加载。
字段默认值,在 Settings 子类中声明。

通过 src/bub/configure.py 中的 Settings.settings_customise_sources 验证:它返回 (env_settings, dotenv_settings, init_settings, file_secret_settings) —— env 高于 .env,两者均高于 ensure_config(...) 调用 model_validate 时传入的 YAML dict。

配置文件位置

路径	来源
`~/.bub/config.yml`	`src/bub/framework.py` 中的 `DEFAULT_CONFIG_FILE`。
通过 `BubFramework(config_file=...)` 覆盖	构造函数参数。

~/.bub/ 同时是 bub.home 的默认取值，由 BUB_HOME 环境变量控制（src/bub/__init__.py）。BUB_HOME 影响 history、tapes 与托管插件项目等 bub.home 使用方；默认配置文件路径仍是 ~/.bub/config.yml，除非嵌入方显式传入 BubFramework(config_file=...)。

Framework —— 运行时路径

环境变量	默认值	YAML 字段	读取方	描述
`BUB_HOME`	`~/.bub`	—	`bub.home` (`bub/__init__.py`)	history、tape store 与托管插件项目的根目录；不会移动默认配置文件。
`BUB_PROJECT`	`BUB_HOME/bub-project`；未设置 `BUB_HOME` 时为 `~/.bub/bub-project`	—	`bub install` / `uninstall` / `update` 的 `--project` 选项	插件项目目录;首次 `install` 时通过 `uv init` 创建。

Agent —— `AgentSettings`

定义于 src/bub/builtin/settings.py:

class AgentSettings(Settings):
    model_config = SettingsConfigDict(env_prefix="BUB_", env_parse_none_str="null", extra="ignore")
    model: str = DEFAULT_MODEL  # "openrouter:openrouter/free"
    command_prefix: str = ","
    fallback_models: list[str] | None = None
    api_key: str | dict[str, str] | None = None
    api_base: str | dict[str, str] | None = None
    providers: dict[str, CustomProvider] = Field(default_factory=dict)
    max_steps: int = Field(default=sys.maxsize, gt=0)
    max_tokens: int = DEFAULT_MAX_TOKENS  # 16384
    model_timeout_seconds: int | None = None
    client_args: dict[str, Any] = Field(default_factory=dict)
    completion_args: dict[str, Any] = Field(default_factory=dict)
    verbose: int = Field(default=0, ge=0, le=2)

加载到 YAML 根节点。

环境变量	默认值	YAML 字段	描述
`BUB_MODEL`	`openrouter:openrouter/free`	`model`	默认模型标识 (`provider:model_name`)。
`BUB_COMMAND_PREFIX`	`,`	`command_prefix`	内置 Agent 与 channel 的命令前缀。不能为空或包含空白字符，支持多字符前缀。
`BUB_FALLBACK_MODELS`	`null`	`fallback_models`	可选的回退模型标识列表。
`BUB_API_KEY`	unset	`api_key`	默认 API key;也可以是按 provider 索引的 JSON object。
`BUB_API_BASE`	unset	`api_base`	默认 API base URL,或按 provider 索引的映射。
`BUB_<PROVIDER>_API_KEY`	unset	—	按 provider 划分的 API key,例如 `BUB_OPENAI_API_KEY`。
`BUB_<PROVIDER>_API_BASE`	unset	—	按 provider 划分的 API base URL,例如 `BUB_OPENROUTER_API_BASE`。
`BUB_PROVIDERS`	`{}`	`providers`	自定义命名的端点,每个用 `type` 指定走哪个 Republic provider 的协议,并有自己的 `api_base` 和 `api_key`。见自定义 provider。
`BUB_MAX_STEPS`	不限制	`max_steps`	单次 turn 内 agent 循环的最大步数；配置时必须为正整数。
`BUB_MAX_TOKENS`	`16384`	`max_tokens`	单次模型调用的最大 token 数。
`BUB_MODEL_TIMEOUT_SECONDS`	`null`	`model_timeout_seconds`	单次调用的超时秒数。
`BUB_CLIENT_ARGS`	`{}`	`client_args`	传递给底层模型 client 的额外 kwargs(JSON / dict)。
`BUB_COMPLETION_ARGS`	`{}`	`completion_args`	传递给每次 completion 调用的额外 kwargs,例如 `{"reasoning_effort":"high"}`;工具和 token 上限由 Bub 提供，优先级见下文。
`BUB_VERBOSE`	`0`	`verbose`	日志详细级别(`0`–`2`)。

例如，配置 command_prefix: "!" 后，内置 channel 使用 !help，,help 按普通文本处理。 CLI 控制命令（quit、exit、thinking）、补全和 shell 模式使用同一前缀。 Telegram 保留现有的原生斜杠命令过滤；前缀设为 / 时，使用 /bub /help。

启动时 ProviderSpecificEnvSource 会扫描 os.environ 中匹配 ^BUB_(.+)_(API_KEY|API_BASE)$ 的变量，并将环境变量前缀解析为 Republic provider 名称，例如 AZURE_OPENAI → azure-openai。

Bub 使用 Republic 发起模型请求。ChatGPT 套餐访问使用 codex:<model>，OpenAI API 访问使用 openai:<model>。本地 Codex 登录不会改变 openai: 路由。provider 标识使用 Republic 的名称，例如 google: 和 azure-openai:。

client_args 接受 Republic provider 参数，例如 headers、api_format、timeout 和 max_retries。Bub 提供解析后的连接设置（api_key、api_base），其他参数原样传递。协议默认值遵循 Republic。Chat Completions 端点需显式设置 api_format: chat。注入的 HTTP client 必须是 httpx2.AsyncClient，生命周期由调用方管理。

completion_args 接受 Republic chat 参数。Bub 提供 tools 和运行时 token 上限；会话中的 reasoning_effort 覆盖配置中的同名 chat 参数。Codex 端点不支持 token 上限，因此不附加运行时的该参数。Republic 负责协议转换，Anthropic 请求开启 prompt caching。

提供商专用字段放入 extra_body，client_args 和 completion_args 都支持它。Republic 将 provider 默认值与请求级 extras 深合并，请求级值优先，再覆盖编码后的请求体。这些显式协议字段可覆盖 reasoning、token 上限等 chat 参数；Bub 原样传递。

Provider 名称和协议能力以 Republic provider 目录为准。自定义 provider 实现需注册到 Republic。

自定义 provider

模型前缀通常是 Republic 的 provider 名,api_key / api_base 每个 provider 只能放一个值。如果某个端点说的是 Republic 已支持的协议,但需要单独起名,就用 providers:比如公司代理、中转站或本地网关、自建服务,或同一厂商的第二个账号。每个名字都可以当模型前缀用,type 指定它走哪个 Republic provider 的协议:

model: proxy:gpt-5.5
fallback_models:
  - openai:gpt-5.5
  - relay:claude-sonnet-5
providers:
  proxy:
    type: openai
    api_base: https://llm-proxy.example.com/v1
    api_key: sk-proxy-...
  relay:
    type: anthropic
    api_base: https://relay.example.com
    api_key: sk-relay-...

这里 proxy:gpt-5.5 和 openai:gpt-5.5 都走 OpenAI 协议,但发往不同的地址、用不同的 key;openai: 仍使用它自己的 api_key / api_base。条目里没写的字段会回退到 api_key / api_base 以及 BUB_<NAME>_API_KEY / BUB_<NAME>_API_BASE。type 不是已知 provider 时,加载配置会直接报错。

Spill sidecar —— `SpillSettings`

定义于 src/bub/builtin/spill.py，由 builtin sidecar 插件注册：

@config(name="spill")
class SpillSettings(Settings):
    model_config = SettingsConfigDict(env_prefix="BUB_SPILL_", extra="ignore", env_file=".env")
    threshold: int = Field(default=4096, ge=0)

从 YAML 的 spill: section 加载。

仅当本次模型调用的工具集合包含 spill.read 时，才会对新结果启用 spill；否则返回完整结果。

环境变量	默认值	YAML 字段（`spill.*`）	描述
`BUB_SPILL_THRESHOLD`	`4096`	`threshold`	渲染后的工具结果（包括失败结果）超过该估算 token 数（每 token 按 4 字符估算）时写入 spill sidecar。设为 `0` 会停止产生新 spill，但 sidecar 仍保持挂载，已有 handle 和生命周期操作不受影响。

Channels —— `ChannelSettings`

定义于 src/bub/channels/manager.py:

class ChannelSettings(Settings):
    model_config = SettingsConfigDict(env_prefix="BUB_", extra="ignore", env_file=".env")
    enabled_channels: str = "all"
    debounce_seconds: float = 1.0
    max_wait_seconds: float = 10.0
    active_time_window: float = 60.0
    stream_output: bool = False

加载到 YAML 根节点。

环境变量	默认值	YAML 字段	描述
`BUB_ENABLED_CHANNELS`	`all`	`enabled_channels`	逗号分隔的 channel 名、`all`，或前缀为 `!` 的排除项。默认运行时集合包含所有已启用且不是 `Interface` 的 channel；显式列出且包含非 `Lifecycle` channel 时，也会附着已启用的 `Lifecycle` 服务，除非被排除。可被 `bub gateway --enable-channel` 单次覆盖。
`BUB_DEBOUNCE_SECONDS`	`1.0`	`debounce_seconds`	channel 设置 `needs_debounce=True` 时,同一 channel 两次消息之间的最小间隔。
`BUB_MAX_WAIT_SECONDS`	`10.0`	`max_wait_seconds`	防抖等待的硬上限。
`BUB_ACTIVE_TIME_WINDOW`	`60.0`	`active_time_window`	会话保持“活跃”以接受缓冲处理的窗口秒数。
`BUB_STREAM_OUTPUT`	`false`	`stream_output`	是否实时把模型输出流式推送给 channel。`bub chat` 强制为 `True`;`bub gateway` 遵循该配置。

Telegram —— `TelegramSettings`

定义于 src/bub/channels/telegram.py:

@config(name="telegram")
class TelegramSettings(Settings):
    model_config = SettingsConfigDict(env_prefix="BUB_TELEGRAM_", extra="ignore", env_file=".env")
    token: str = ""
    allow_users: str | None = None
    allow_chats: str | None = None
    proxy: str | None = None

加载到 YAML 的 telegram: 段。

环境变量	默认值	YAML 字段 (`telegram.*`)	描述
`BUB_TELEGRAM_TOKEN`	`""`	`token`	Telegram bot token。启用该 channel 必填。
`BUB_TELEGRAM_ALLOW_USERS`	unset	`allow_users`	逗号分隔的允许 Telegram 用户 ID 列表。留空表示不限制。
`BUB_TELEGRAM_ALLOW_CHATS`	unset	`allow_chats`	逗号分隔的允许 Telegram chat ID 列表。留空表示不限制。
`BUB_TELEGRAM_PROXY`	unset	`proxy`	访问 Telegram API 的代理 URL,例如 `http://user:pass@host:port` 或 `socks5://host:port`。

部署细节见运维 › Channels › Telegram。

bub login codex 读取一个非 BUB_* 环境变量:

环境变量	默认值	读取方	描述
`CODEX_HOME`	`~/.codex`	`bub login codex`(`src/bub/builtin/auth.py`)	Codex OAuth `auth.json` 的存放目录。可被 `--codex-home` 覆盖。

插件自定义配置

插件可以通过 @config(name="...") 装饰器注册自己的 Settings 子类（参见构建 › 插件）。装饰器把类记录进 CONFIG_MAP[name]，然后由 configure.validate 验证、ensure_config 读取。YAML key 与注册名一致；环境变量遵循子类声明的 env_prefix。

设置

优先级

配置文件位置

Framework —— 运行时路径

Agent —— AgentSettings

自定义 provider

Spill sidecar —— SpillSettings

Channels —— ChannelSettings

Telegram —— TelegramSettings

Login —— 第三方环境变量

插件自定义配置

Agent —— `AgentSettings`

Spill sidecar —— `SpillSettings`

Channels —— `ChannelSettings`

Telegram —— `TelegramSettings`