IronClaw Reborn 启动配置契约全解析:ironclaw_config 与 config.toml 操作指南

原创2026-09-22 16:29:461,931 阅读
文章标签:人工智能AI Agent交互助手本地部署Agent 沙箱MCP ClientsAI 技能AI 插件后端认证鉴权CLI前端

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)。

两个重要的"不"边界

  1. 零工作区依赖(zero workspace dependencies):该 crate 是纯叶子节点,机器强制约束(由 ironclaw_architecture_tests 的边界测试 reborn_dependency_boundaries.rs 钉死)。这决定了它解析时只能得到字符串形态的字段(如 TenantId、UserId、ApprovalPolicy 等),真正的类型提升与语义校验发生在 composition 根——"该 crate] 只强制形状(小节存在、字段 TOML 类型正确、无内联密钥)"(见 [config_file.rs 顶部文档)。
  2. 禁止新增 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):

  1. Catalog(目录):providers.json —— 供应商定义(内置 + 用户覆盖);
  2. Selection(选择):config.toml —— "default LLM 槽位用供应商 X、模型 Y";
  3. 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 顶部文档):

  1. 编译默认(生产调优的安全上限);
  2. [budget] TOML 小节;
  3. 环境变量(最高优先级)。

环境变量清单(常量即变量名):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 再动手,并且同步 grep docs/ 与 crates/;新增 vendor 小节需要过扩展特异性门禁,需评审豁免。
  • 密钥永不进 config.toml:所有凭据一律环境变量引用;api_key_env、url_env、env_token_var 这类字段放的是变量名。

总之,ironclaw_config 用"零工作区依赖 + 严格形状校验 + 解析期密钥拒绝 + 退役兼容窗口"四件套,把 Reborn 的启动配置做成了既对操作员宽容(稀疏文件、增量编辑、清晰迁移指引)、又对错误零容忍(fail closed)的契约层——理解这一层,是深入 IronClaw Reborn 二进制、composition 与 CLI 的起点。

登录后查看全文
ironclaw