IronClaw Reborn 启动配置契约全解析:ironclaw_config 与 config.toml 操作指南
IronClaw Reborn 启动配置契约全解析:ironclaw_config 与 config.toml 操作指南
本文围绕 IronClaw 开源仓库中负责独立二进制启动配置的叶子 crate —— ironclaw_config(路径 crates/app/ironclaw_config)展开,系统讲解 Reborn home 解析、启动 profile 契约、config.toml 完整模式、内联密钥拒绝、退役小节兼容窗口与预算默认值等机制。读完你将掌握:如何正确设置 IRONCLAW_REBORN_HOME / IRONCLAW_REBORN_PROFILE 环境变量、如何编写一份可被严格校验的稀疏 config.toml、如何安全地退役一个配置小节而不破坏既有操作员文件,以及如何用 cargo test -p ironclaw_config 验证配置契约。
一、ironclaw_config 的定位与职责边界
ironclaw_config 是 IronClaw Reborn(独立 standalone 二进制的运行时代称)的启动配置契约 crate。根据其 CLAUDE.md 与 README.md,它承载四类启动期职责:
- Reborn home / profile / 配置文件 / doctor / secrets-guard 的类型与校验:即
home.rs、profile.rs、boot.rs、config_file.rs、doctor.rs、secrets_guard.rs、retired_sections.rs这几个区域文件; - 独立 Reborn 二进制的启动配置契约;
- 可被 CLI 与 composition 共享的纯配置解析/校验辅助逻辑;
- 首次运行配置播种(
config_seed.rs)。
两个重要的"不"边界
- 零工作区依赖(zero workspace dependencies):该 crate 是纯叶子节点,机器强制约束(由
ironclaw_architecture_tests的边界测试reborn_dependency_boundaries.rs钉死)。这决定了它解析时只能得到字符串形态的字段(如TenantId、UserId、ApprovalPolicy等),真正的类型提升与语义校验发生在 composition 根——"该 crate] 只强制形状(小节存在、字段 TOML 类型正确、无内联密钥)"(见 [config_file.rs 顶部文档)。 - 禁止新增 per-vendor 的
config.toml小节:扩展的实时配置归扩展包自身所有(由其 manifest 的<a href="https://link.gitcode.com/i/23b3f8c867ad635882e0783a76268c4b" target="_blank">admin_configuration]声明)。RebornConfigFile不命名任何 vendor,扩展特异性门禁([reborn_extension_specificity.rs)是"只收缩"(shrink-only)的,新增 vendor 小节需要基线提升与评审豁免。该 crate 唯一允许持有的 vendor 令牌是retired_sections.rs中的退役表名。
从 lib.rs 的导出可见其完整公开面:RebornBootConfig、RebornHome/REBORN_HOME_ENV、RebornProfile/REBORN_PROFILE_ENV、RebornConfigFile 及全部小节类型、RebornDoctorReport、reject_inline_secret/InlineSecretError、RetiredSections/retired_config_key_guidance、BudgetDefaults 及全部 *_ENV 常量。按 README 的测量,消费方为 4 个 crate:ironclaw(二进制)、ironclaw_composition、ironclaw_operator、ironclaw_extension_host。
二、启动三板斧:Home、Profile 与 RebornBootConfig
进程启动的第一件事是解析"状态根"与"启动画像",两者合成为 RebornBootConfig。
2.1 Reborn home:IRONCLAW_REBORN_HOME
RebornHome 由环境变量 IRONCLAW_REBORN_HOME 选择(见 home.rs)。解析规则非常严格,逐条校验(home.rs):
| 校验 | 说明 |
|---|---|
| 非空 | 变量为空直接报 EmptyPath |
| 绝对路径 | 相对路径报 RelativePath |
| 无父目录组件 | 含 .. 报 ParentPath |
| 非文件系统根 | 根路径报 RootPath |
| 不得指向 v1 状态根 | 与 ~/.ironclaw(由 HOME/USERPROFILE 推导)或 IRONCLAW_BASE_DIR 推导的 v1 根重叠时报 V1StateRoot,防止 Reborn 与 v1 状态混用 |
| 未设置时回退 | 依次尝试 $HOME/.ironclaw/reborn 与 $USERPROFILE/.ironclaw/reborn;两者都失败报 MissingHome |
从 home.rs 可以看到 home 下有两个关键文件路径访问器:
config_file_path()→$IRONCLAW_REBORN_HOME/config.toml(可选:不存在时RebornConfigFile::load返回Ok(None),运行时回退到编译期默认值);providers_file_path()→$IRONCLAW_REBORN_HOME/providers.json(LLM 供应商目录,与 v1 的~/.ironclaw/providers.json同形状;加载由 composition 根经ironclaw_llm::ProviderRegistry完成)。
2.2 Reborn profile:IRONCLAW_REBORN_PROFILE
RebornProfile 由 IRONCLAW_REBORN_PROFILE 选择,未设置时默认 Standalone(单独调用二进制时的安全默认,见 profile.rs)。共 8 个合法取值(线名稳定,profile_contract.rs 有对应断言):
| 线名 | 枚举 | 含义 |
|---|---|---|
local-dev |
Standalone |
独立单用户运行时(默认) |
local-dev-yolo |
StandaloneUnrestricted |
显式确认无限制主机访问,绝不默认选择 |
hosted-single-tenant |
HostedSingleTenant |
托管单租户,本地运行时产品面 + 持久化 PostgreSQL |
hosted-single-tenant-volume |
HostedSingleTenantVolume |
单租户托管预览,基于持久卷的本地运行时 substrate |
hosted-single-tenant-volume-sandboxed |
HostedSingleTenantVolumeSandboxed |
卷模式 + 每用户 Docker 沙箱 shell/进程通道 |
hosted-single-tenant-volume-sandboxed-railway |
HostedSingleTenantVolumeSandboxedRailway |
卷模式 + Railway Sandboxes 提供沙箱生命周期 |
production |
Production |
生产启动;缺少必需持久化服务时必须 fail closed |
migration-dry-run |
MigrationDryRun |
校验生产形态的启动/配置,但不接生产流量、不做迁移副作用 |
非法值返回 RebornConfigError::InvalidProfile,错误信息会列出全部合法取值(home.rs)。RebornProfile 还提供若干谓词辅助 composition 决策:starts_hosted_single_tenant_listener(是否启动托管单租户监听)、uses_standalone_local_runtime_volume、local_runtime_storage_subdir(本地运行时存储子目录)等。
2.3 合成:RebornBootConfig
RebornBootConfig::resolve_from_env() 同时解析 home 与 profile 并合成(boot.rs)。测试 profile_contract.rs 验证了:给定 IRONCLAW_REBORN_HOME 与 IRONCLAW_REBORN_PROFILE=production 能正确解析;profile 缺失时默认 Standalone;非法或空 profile 都会在调用方配置路径上报错。
三、config.toml:操作员侧的选择层
config.toml 是操作员编辑的 TOML 文件($IRONCLAW_REBORN_HOME/config.toml),进程启动时由 ironclaw-reborn run 读取一次。它位于三层配置模型的中间层(见 config_file.rs):
- Catalog(目录):
providers.json—— 供应商定义(内置 + 用户覆盖); - Selection(选择):
config.toml—— "default LLM 槽位用供应商 X、模型 Y"; - Runtime config(运行时配置):composition 根把选择对目录解析后派生。
每个字段的优先级严格固定(源码中的注释原文):
compiled defaults < this file < env vars < CLI flags
3.1 两个支柱性设计
deny_unknown_fields:RebornConfigFile及每个小节结构体都标了#<a href="https://link.gitcode.com/i/9abd9b75de5d0c4fdcf14009592646d1" target="_blank">serde(deny_unknown_fields)]([config_file.rs)。拼错键名会立刻得到未知字段错误——这是该 crate 刻意保留的"防手滑"性质,也是退役小节不能直接删除的根本原因(见第六节)。- API 版本门禁:
api_version形如ironclaw.runtime/v1(常量REBORN_CONFIG_API_VERSION)。校验规则为 major fail-closed、minor 兼容:所有v1.x启动文件对本版本有效,其他 major 一律拒绝(validate_api_version,config_file.rs)。文件缺失该字段时按当前 major 假定。
3.2 稀疏文件哲学
RebornConfigFile 的每个小节都是可选的(全部 Option/Vec 默认值),操作员可以只覆盖关心的字段,其余保持 composition 里 CLI 形态的编译默认。load() 在文件不存在时返回 Ok(None) 而不是报错——"稀疏配置是合法的,操作员用默认值启动"是显式设计(config_file.rs)。
四、config.toml 全部小节逐字段详解
以下字段与默认值均以 config_file.rs 的源码文档为准,并参照真实示例 docker/reborn/config.toml。
4.1 [boot]
| 字段 | 类型 | 说明 |
|---|---|---|
profile |
string | composition profile 名,如 standalone、local-dev-yolo、hosted-single-tenant、production 等;composition 校验其与 RebornCompositionProfile 匹配 |
4.2 [identity]
| 字段 | 说明 |
|---|---|
tenant |
租户标识 |
default_agent |
默认 Agent id |
default_owner |
默认 Owner id |
default_project |
默认 Project id |
示例中:default_owner = "reborn-cli"、tenant = "reborn-cli"、default_agent = "reborn-cli-agent"。
4.3 [policy]
| 字段 | 说明 |
|---|---|
deployment_mode |
local_single_user / hosted_multi_tenant / enterprise_dedicated,与 ironclaw_host_api::runtime_policy::DeploymentMode 匹配 |
default_profile |
RuntimeProfile 变体的 snake_case |
default_approval_policy |
ask_always / ask_writes / ask_destructive / org_policy / minimal,与 ApprovalPolicy 匹配 |
4.4 [drivers]
| 字段 | 说明 |
|---|---|
default |
默认驱动名:text_only / planned,与 RebornDriverChoice 匹配 |
additional |
额外注册的驱动列表,供逐 turn 的 requested_run_profile 选择 |
4.5 [harness]
| 字段 | 说明 |
|---|---|
id |
活动 harness id;composition 启动时记录该值,harness substrate 落地后生效(epic #3036) |
4.6 [runner] —— 并发与轮询参数
| 字段 | 类型 | 默认/约束 |
|---|---|---|
heartbeat_interval_secs |
u64 | 心跳间隔(秒) |
poll_interval_ms |
u64 | 轮询间隔(毫秒) |
worker_count |
usize | 并发 turn-runner 槽位(调度器信号量许可)。缺省 → 编译默认 16;0 → 不限;超过 Semaphore::MAX_PERMITS 的值会被拒绝(否则信号量构造会 panic)。运行时可用 IRONCLAW_REBORN_RUNNER_WORKER_COUNT 覆盖 |
max_concurrent_runs_per_user |
u32 | 每个 (tenant_id, owner user_id) 的 TurnStatus::Running 上限;缺省或 0 = 不限 |
max_concurrent_trigger_runs |
u32 | ScheduledTrigger 来源上限;缺省或 0 = 不限 |
max_concurrent_conversation_runs |
u32 | Inbound/WebUi 来源上限;缺省或 0 = 不限 |
max_concurrent_unbound_runs |
u32 | unbound(预构建上下文)类上限;缺省或 0 = 不限 |
4.7 [skills]
| 字段 | 类型 | 说明 |
|---|---|---|
regex_activation_enabled |
bool | 为 false 时正则激活条件不再自动加载完整技能上下文;关键词/标签激活与显式技能提及仍有效 |
4.8 [storage] —— 生产持久化选择
| 字段 | 说明 |
|---|---|
backend |
存储后端名,当前生产切片仅支持 "postgres";未知名会报错,URL 形状的值会被拒绝 |
url_env |
环境变量名(不是 URL 值!)——含 PostgreSQL 连接 URL |
secret_master_key_env |
环境变量名——含 Reborn secret 主密钥 |
pool_max_size |
连接池大小,默认 2,必须 > 0 |
注意:url_env 与 secret_master_key_env 是环境变量名称,解析器会拒绝原始 URL 形状的值,防止凭据被粘贴进 config.toml(validate_env_var_reference 强制变量名只能由 ASCII 字母/数字/下划线组成)。
4.9 [llm.<slot>] —— 逐槽位 LLM 选择
槽位名是 TOML 表键(典型为 default 与 mission)。每个槽位:
| 字段 | 说明 |
|---|---|
provider_id |
来自 providers.json(内置或用户目录)的供应商 id |
model |
覆盖供应商 default_model,可选 |
api_key_env |
必须是环境变量名(如 "OPENAI_API_KEY"),绝不可是值本身 |
base_url |
覆盖供应商 default_base_url,可选 |
目前 composition 只接 default 槽位;mission 槽位在计划中的 driver 落地后生效,操作员可以提前填充。
4.10 [webui] —— WebChat v2 HTTP 网关
| 字段 | 默认 | 说明 |
|---|---|---|
listen_host |
127.0.0.1 |
监听 IP;默认仅回环,暴露网关必须显式选择 0.0.0.0 或具体网卡 |
listen_port |
3000 |
TCP 端口;0 仅在 CLI 显式 --port 0(测试用)时接受 |
env_token_var |
IRONCLAW_REBORN_WEBUI_TOKEN |
承载 host 安装 bearer token 的环境变量名 |
env_user_id_var |
IRONCLAW_REBORN_WEBUI_USER_ID |
env-bearer 认证调用方映射到的 UserId 的环境变量名 |
allowed_origins |
空 | CORS 允许来源列表;默认为空时 composition 对所有跨域预检 fail closed,绝不回显攻击者提供的 Origin |
csp_header_override |
无 | 覆盖默认 CSP:default-src 'self'; object-src 'none'; frame-ancestors 'none'; base-uri 'self' |
max_body_bytes_fallback |
14 MiB | 未匹配 v2 描述符路径(404 回退路径)的单请求体上限;0 被拒绝;v2 路由各自从 BodyLimitPolicy 描述符单独设限,严格更紧 |
canonical_host |
无 | 监听器的规范主机(如 app.example.com 或 127.0.0.1:3000)。设置后 WS 同源中间件用该操作员信任值对比请求 Origin,而非信任客户端提供的 Host 头——反代场景下防伪造 Host 的关键 |
4.11 [google] —— Google OAuth 公开标识
| 字段 | 说明 |
|---|---|
client_id |
OAuth 客户端 id(公开标识) |
redirect_uri |
重定向 URI |
hosted_domain_hint |
托管域提示 |
client secret 在 config.toml 中刻意没有表示——它只存在于 secret store。
4.12 [budget] —— 成本预算(详见第八节)
字段包括 user_daily_usd(默认 5.00)、project_daily_usd(默认 2.00)、mission_per_tick_usd(0.50)、heartbeat_per_tick_usd(0.05)、routine_lightweight_usd(0.02)、routine_standard_usd(0.10)、background_job_default_usd(1.00)、default_tz(UTC)、warn_at(0.75)、pause_at(0.90)、overestimate_factor(1.20)。任何维度设为 0 = 不限。
4.13 [trigger_poller] —— 触发器轮询器
| 字段 | 默认 | 约束(CLI 设置层启动时强制,越界即致命错误) |
|---|---|---|
enabled |
false | 必须显式 enabled = true 才激活 |
poll_interval_secs |
30 | 范围 1..=3600 |
fires_per_tick |
32 | 范围 1..=1000 |
max_concurrent_fires_per_trigger |
1 | V1 不变量:必须等于 1 |
startup_jitter_max_secs |
0 | 范围 0..=3600,首次 tick 前随机抖动上界 |
tick_jitter_max_secs |
0 | 范围 0..=3600,每次 tick 间隔附加随机抖动上界 |
环境变量 IRONCLAW_TRIGGER_POLLER_* 覆盖该节。
4.14 [memory] —— 记忆能力绑定(issue #3537)
| 字段 | 说明 |
|---|---|
provider |
记忆提供方扩展 id:ironclaw.memory(原生,默认)、memory.disabled 或第三方 id(如 mem0)。compose 时选定、运行时不可换 |
admin_overrides |
授权生产绑定的管理覆盖,作用域 (extension_id, deployment_profile);deployment_profile 可为具体线名或 * |
mem0_base_url |
第三方记忆提供方连接基址(mem0 为自托管 OSS 服务器 URL,绝不可是托管云);绑定但未设 URL 会 fail closed;API key 可选,需要时经 MEMORY_MEM0_API_KEY 环境变量提供 |
curation_interval_turns |
周期记忆整理(后台 "dreaming" 任务)间隔(完成用户 turn 数)。可选开启:省略 = 不运行;0 被拒绝(不允许哨兵语义);最小 2(每 turn 一次会翻倍每次对话成本);要求绑定的提供方在 manifest 中声明了 after_turn 调度操作,否则启动失败而非静默 |
4.15 完整示例配置
综合 docker/reborn/config.toml 与上述字段,一个可运行的稀疏配置大致如下:
api_version = "ironclaw.runtime/v1"
[boot]
profile = "local-dev"
[identity]
default_owner = "reborn-cli"
tenant = "reborn-cli"
default_agent = "reborn-cli-agent"
[runner]
heartbeat_interval_secs = 15
poll_interval_ms = 200
[skills]
regex_activation_enabled = true
[webui]
env_token_var = "IRONCLAW_REBORN_WEBUI_TOKEN"
env_user_id_var = "IRONCLAW_REBORN_WEBUI_USER_ID"
[llm.default]
provider_id = "openai"
model = "gpt-4o-mini"
api_key_env = "OPENAI_API_KEY"
[storage]
backend = "postgres"
url_env = "DATABASE_URL"
secret_master_key_env = "IRONCLAW_REBORN_SECRET_MASTER_KEY"
pool_max_size = 2
[budget]
user_daily_usd = 10.0
warn_at = 0.75
pause_at = 0.90
[trigger_poller]
enabled = true
poll_interval_secs = 30
注意 docker/reborn/config.toml 刻意不内置 [llm.default]:配置文件中 [llm.default] 是唯一事实来源,而 Railway 环境变量(NEARAI_API_KEY 等)已完整,环境回退即可解析 LLM,无需槽位。
五、内联密钥拒绝:secrets_guard 的 fail-closed 设计
该 crate 最值得称道的安全机制是解析期拒绝内联密钥(secrets_guard.rs)。核心规则:config.toml 中的密钥只能以不透明句柄(环境变量名、secret-store 键)形式引用,把原始 token 粘贴进文件会在第一次 ironclaw-reborn run 时被响亮拒绝。
检测基于高信号形状的保守模式匹配(宁可误报、不可漏报——最坏失败模式是一个指向违规键的解析错误,而不是泄漏的凭据):
- 前缀标记:
sk-(OpenAI/Anthropic)、sk_live_/sk_test_(Stripe)、xoxb-/xoxp-/xapp-(Slack)、ghp_/gho_/ghu_/ghs_/ghr_/github_pat_(GitHub)、AKIA/ASIA(AWS)、AIza/ya29.(Google)、hf_(HuggingFace)、nai-sess-(NEAR AI); - JWT 形状:
xxx.yyy.zzz三段 base64url 且每段 > 8 字符; - 长 hex 串:≥ 32 个十六进制字符。
配套的防误报设计:
- 长度下限:空值或字符数 < 12(按字符计数而非字节,Unicode 同理)直接放行——
model = "gpt-4o-mini"这类合法值不会误伤; - 短前缀边界匹配:≤ 4 字符的前缀(如
sk-、AKIA)要求 token 边界(前面不能是标识符字符),因此shelf_layout、risk-mitigation这类普通标识符不会误触; - URL 内嵌密钥:
https://proxy.example/v1?key=sk-proj-...也会被拒(contains_secret_prefix对长前缀用contains匹配)。
secrets_guard.rs 的单元测试覆盖了各类拒绝与放行场景:拒绝 OpenAI sk- 前缀、Slack bot token、JWT 形状、长 hex、带空白包裹的密钥、URL 内嵌密钥;放行短前缀在标识符内部、环境变量引用串(OPENAI_API_KEY 等)、正常配置值(openai、gpt-4o-mini、https://api.openai.com/v1、模型串 anthropic/claude-3.5-sonnet-20250620)。
另外,退役小节跳过类型化 schema,所以会绕过上述逐字段检查;RetiredSections::string_values() 会显式走一遍退役小节的全部字符串值,形成比原九个 Slack 键更宽的安全网。
六、退役小节与兼容窗口:RETIRED_SECTIONS 表
这是 CLAUDE.md 重点强调的操作规程。为什么不能直接删除一个小节?因为 RebornConfigFile 是 deny_unknown_fields——删除会让每一个现有操作员文件解析失败。正确的做法是退役而非删除(retired_sections.rs 顶部文档)。
6.1 两级处理
退役小节并不自动报错(让原本能启动的配置启动失败比忽略一个过期键更糟):
- Rejected keys(拒绝键):操作员在遵循已退役的 setup 指令。值会被静默忽略,因此启动 fail closed 并给出迁移指引(
RetiredSectionError); - 小节内其余内容(inert):启动继续,但发出弃用通知——让设置了"已宣传但无人读取"标志的操作员知道它不生效,而不是误以为已生效。
6.2 当前退役表
| 小节 | 拒绝键 | 迁移指引 |
|---|---|---|
[slack] |
installation_id、team_id、api_app_id、slack_user_id、user_id、shared_subject_user_id、channel_routes、signing_secret_env、bot_token_env |
"Slack 通过安装 Slack 扩展并在 WebUI(/extensions)完成工作区 OAuth 来配置" |
[telegram] |
无(该节历史上只接受 enabled,统一扩展运行时落地后无人读取,整节 inert) |
"Telegram 通过安装 Telegram 扩展并在 WebUI(/extensions)完成 bot 设置来配置" |
6.3 机制闭环
一切由表驱动:解析期 RetiredSections::split_from 先把退役小节从原始文档中剥离(typed schema 因此永远不必命名退役小节,得以保持 deny_unknown_fields);serve 前的拒绝(retired_section_migration);inert 小节的弃用通知(retired_section_notices);以及 config set 的迁移指引(retired_config_key_guidance 对 config set slack.enabled 这类输入返回"该键已退役、不再被读取"的说明,而非通用的"未知配置键")。parse_text 的剥离顺序是刻意的:无退役小节的干净文件(每个新部署、每个完成迁移的旧部署)走 toml::from_str 直路,保留带行列号与脱字符的未知字段诊断;只有携带退役小节的旧文件才降级到 toml::Table 路径。
向未来退役一个小节的全部成本就是往 RETIRED_SECTIONS 加一行。 另据 CLAUDE.md 的实战教训(Slack 退役时在 docs/ 里发现 5 份仍教旧 flag 的操作员文档),退役时不仅要 grep crates/,还要 grep docs/。
七、配置诊断与首次运行播种
7.1 doctor:无副作用快照
RebornDoctorReport(doctor.rs)是无副作用的诊断快照,由 RebornBootConfig 派生,暴露 home 路径、home 来源标签(IRONCLAW_REBORN_HOME 或 default)、profile,以及 v1_state(恒为 "not-used")。doctor_contract 测试组覆盖其契约。
7.2 首次运行播种
seed_default_config_file_if_missing(config_seed.rs)在文件缺失时原子播种一份稀疏的首运行 config.toml(临时文件 + persist_noclobber,天然处理并发首跑竞争——8 线程测试断言恰好 1 个 Seeded、其余 AlreadyPresent)。种子文件刻意比 ironclaw config init 更小:只记录 API 版本与安全默认 boot profile(local-dev),不安装活动 LLM 槽位、不钉死编译默认——从而保留"缺失配置"时由环境变量驱动供应商选择的既有行为。种子文件内还给出指引:完整注释模板运行 ironclaw config init --force。
八、预算默认值:三层合并与校验
预算默认值由三层合并(budget.rs 顶部文档):
- 编译默认(生产调优的安全上限);
[budget]TOML 小节;- 环境变量(最高优先级)。
环境变量清单(常量即变量名):IRONCLAW_BUDGET_USER_DAILY_USD、IRONCLAW_BUDGET_PROJECT_DAILY_USD、IRONCLAW_BUDGET_MISSION_PER_TICK_USD、IRONCLAW_BUDGET_HEARTBEAT_PER_TICK_USD、IRONCLAW_BUDGET_ROUTINE_LIGHTWEIGHT_USD、IRONCLAW_BUDGET_ROUTINE_STANDARD_USD、IRONCLAW_BUDGET_BACKGROUND_JOB_DEFAULT_USD、IRONCLAW_BUDGET_DEFAULT_TZ、IRONCLAW_BUDGET_WARN_AT、IRONCLAW_BUDGET_PAUSE_AT、IRONCLAW_BUDGET_OVERESTIMATE_FACTOR。USD 字段 0 = 不限。
合并后的 BudgetDefaults::validate() 校验规则:所有 USD 上限必须有限且 >= 0;warn_at/pause_at 必须在 [0.0, 1.0] 且 pause_at >= warn_at;overestimate_factor 必须 >= 1.0。测试覆盖:编译默认合法、0 合法(不限)、负数拒绝、pause < warn 拒绝、overestimate < 1 拒绝、小节覆盖编译默认、稀疏小节只覆盖单字段、环境覆盖小节且非数字环境值以 InvalidEnvF64 报错而非静默丢弃(budget.rs 测试模块中环境变更测试经互斥锁串行化)。
九、配置编辑会话与锁
除了直接编辑文件,crate 还提供类型化补丁式编辑,供 CLI 的 config set 类命令使用:
DefaultLlmSlotUpdateSession/begin_default_llm_slot_update:对[llm.default]的provider_id/model/api_key_env/base_url四个字段做Keep/Set/Remove三态补丁;GoogleOauthConfigUpdateSession/begin_google_oauth_config_update:对[google]的client_id/redirect_uri/hosted_domain_hint做同样三态补丁(client_secret无 config.toml 表示,故无更新变体)。
两套会话都持有独占锁文件(config.toml.lock)+ 内存中 toml_edit::DocumentMut,apply() 时通过 parse_text 重新校验后原子写回(临时文件 + persist),保证"保持无关 TOML 不变"的增量编辑语义。
十、验证与测试
按 CLAUDE.md 与 README.md 的验证命令:
# 快速本地检查(含 profile_contract、doctor_contract、home_contract)
cargo test -p ironclaw_config
# 依赖/API 变更后的边界检查
cargo test -p ironclaw_architecture_tests
配套测试目录 crates/app/ironclaw_config/tests 下有 profile_contract.rs(profile 线名稳定性、全部合法值解析、非法值拒绝、boot config 环境解析)、doctor_contract.rs、home_contract.rs 三组契约测试。架构层边界测试(reborn_dependency_boundaries.rs)钉死零依赖与启动文件布局不变量;扩展特异性门禁(reborn_extension_specificity.rs)保证 vendor 小节只减不增。
十一、给 Agent 与操作员的实践要点
- 配置契约必须确定性强、副作用轻(side-effect light);深层辅助函数不要随意读取环境变量,除非测试的正是该契约本身。
- 显式传入 Reborn home/profile 输入,而不是在深层依赖隐式环境。
- 为序列化的配置/profile 形状添加兼容性测试——线名与形状的稳定是该 crate 的一等公民不变量。
- 退役任何配置面都先查
RETIRED_SECTIONS再动手,并且同步 grepdocs/与crates/;新增 vendor 小节需要过扩展特异性门禁,需评审豁免。 - 密钥永不进
config.toml:所有凭据一律环境变量引用;api_key_env、url_env、env_token_var这类字段放的是变量名。
总之,ironclaw_config 用"零工作区依赖 + 严格形状校验 + 解析期密钥拒绝 + 退役兼容窗口"四件套,把 Reborn 的启动配置做成了既对操作员宽容(稀疏文件、增量编辑、清晰迁移指引)、又对错误零容忍(fail closed)的契约层——理解这一层,是深入 IronClaw Reborn 二进制、composition 与 CLI 的起点。