人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载本篇基于 IronClaw 仓库中的 Reborn 合同冻结草稿 settings-config.md 展开系统讲解 IronClaw Agent OS 中设置/配置作为结构化控制面状态的设计契约。读完后你将理解 IronClaw 如何用类型化配置仓库取代散落的 JSON 文件、配置的五层分层与优先级模型、Scope 作用域继承规则、文件投影projection的三种写回模式以及配套的事件审计与验收测试清单。1. 契约定位设置是控制面状态不是任意记忆该契约状态Contract-freeze draft日期 2026-04-25开宗明义Settings/configuration is structured control-plane state, not arbitrary memory. 设置/配置是结构化的控制面状态而不是任意记忆。生产环境 Reborn 的**唯一事实来源source of truth**是typed settings repositories即类型化的设置仓库而不是配置文件本身。文件形态的投影projection可以存在于/system/settings /system/extensions /system/skills但这些投影不构成规范存储模式canonical storage schema除非某个领域契约明确说明。该契约依赖同目录下的四份姊妹契约阅读时可交叉参考storage-placement.md —— 存储放置规则secrets.md —— 秘密材料存储规则extensions.md —— 扩展契约filesystem.md —— 文件系统契约仓库中可以直接看到这份类型化设置仓库取代 JSON 文件原则的落地证据数据库迁移 V8__settings.sql 的头部注释明确写道该表取代了~/.ironclaw/settings.json、session.json和mcp-servers.json三个散落文件键采用点分路径约定如agent.name、sandbox.enabled、mcp_servers与既有Settings.get()/set()约定保持一致每行一个设置以便原子更新单个值CREATE TABLE IF NOT EXISTS settings ( user_id TEXT NOT NULL, key TEXT NOT NULL, value JSONB NOT NULL, updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), PRIMARY KEY (user_id, key) );注意其value列是JSONB类型——这正是契约第 4 节values are JSON values validated by schema在持久层的对应实现。2. 配置分层五个必须保持独立的层契约第 2 节要求保持以下分层互不混淆每层有各自的事实来源层用途事实来源Bootstrap config进程启动、DB URL、初始 provider 提示、部署模式操作员控制的环境变量/文件DB-backed settings用户/管理员/运行时产品设置类型化设置仓库Secrets凭据与秘密材料类型化加密秘密仓库Extension config扩展专属的已校验配置类型化扩展配置仓库File projections诊断/编辑/导入导出视图基于类型化状态的生成投影这四条硬性规则值得逐条强调秘密绝不存入设置值secrets are never stored in settings values设置只能引用SecretHandle绝不直接携带SecretMaterial——这是设置层与 secrets.md 契约的接缝设置里放的是句柄材料在加密秘密仓库里Bootstrap 配置在 setup 完成后不会静默覆盖DB 中的运行时设置除非优先级规则明确允许秘密就绪后的 LLM/provider 解析必须重新解析——即后补密钥的 LLM 供应商配置必须在密钥可用后再次执行解析流程而不能沿用启动期的降级状态。从仓库结构看Bootstrap 层对应操作员侧的部署文件profiles/目录下的 local.toml、server.toml、server-multitenant.toml 等部署档案以及 deploy/env.example 中的环境变量模板都属于操作员控制的环境/文件这一层而非产品设置。3. Scope 模型作用域与优先级3.1 七种作用域设置可以按以下维度定作用域system/global tenant user project agent extension skill3.2 每个设置契约必须声明的五件事契约要求每个设置项的契约文本都必须说明允许的作用域allowed scopes默认作用域default scope继承/覆盖顺序inheritance/override order管理员专属 vs 用户可写admin-only vs user-writable是否允许 project/agent 层覆盖。3.3 推荐优先级链运行时设置的推荐优先级从高到低为explicit invocation override # 显式调用级覆盖 agent/project setting # agent/project 层设置 user setting # 用户层设置 tenant setting # 租户层设置 system default # 系统默认 bootstrap fallback # 引导配置兜底最后一条审计要求每次设置写入必须记录 actor scope执行者的作用域用于审计与溯源provenance。对照 V8__settings.sql 的表结构可以推断当前 DB 实现以user_id作为第一主键维度承载作用域tenant/project 等上层作用域的完整 scope chain 由上层契约storage-placement约束——契约文本也要求PostgreSQL/libSQL repository parity where settings are DB-backed即 DB 支撑的设置必须在 PostgreSQL 与 libSQL 两种后端保持行为一致。4. 类型化仓库契约操作面与规则4.1 仓库应暴露的操作get(scope, key) set(scope, key, value, actor) delete(scope, key, actor) list(scope, prefix) resolve(scope_chain, key) watch/emit change event注意set/delete都强制携带actor参数——这与第 3 节写入必须记录 actor scope的要求呼应审计信息是写路径的一等输入而非事后补记。4.2 五条操作规则键是校验过的路径相邻标识符path-adjacent identifier值是 JSON 值在已知 schema 时按 schema 校验未知键仅允许在明确标记为可扩展extensible的命名空间中写入按元数据/脱敏值审计包含疑似秘密材料的值应被拒绝或要求显式走秘密迁移流程。其中键校验直接映射到验收测试中的key validation rejects path traversal/control characters——键的点分路径格式如tool_permissions.shell天然需要防止路径穿越与控制字符注入。5. Schema 校验与 llm_config 产品视图5.1 需要 JSON Schema 的已知设置键llm_backend selected_model llm_custom_providers tool_permissions.shell workspace_search embedding_provider extension enabled/config state5.2 校验规则schema 校验发生在持久化之前尽可能一次性报告全部相关错误而非遇到第一个就返回schema 错误信息必须稳定且可指导用户操作user-actionableschema 定义与所属领域一起版本化投影回写projection write-back使用同一套 schema——即文件投影写回时不能走更宽松的校验路径。5.3 llm_config 是规范读入口契约第 5 节末尾规定LLM provider 设置快照以 descriptor 支撑的 ProductSurface 查询视图llm_config暴露旧的get_llm_configfacade 方法只是该视图上的兼容包装ProductSurface 视图才是规范读通道。仓库中的实现印证了这一点product_surface.rs 中组合根在装配阶段构造llm_config服务并挂到 API 上// crates/app/ironclaw_composition/src/product_surface.rs节选 if let Some(llm_config) build_llm_config_service(runtime) { api api.with_llm_config_service(llm_config); } pub(crate) fn compose_llm_config_service(/* boot, keys */) { // ... let mut llm_config ironclaw_operator::RebornLlmConfigService::new(boot.clone(), keys.clone()) // ... 依 boot/keys 组装 provider 解析能力 Some(Arc::new(llm_config)) }从源码结构看RebornLlmConfigService接收 bootstrapboot与密钥句柄keys两个输入组装——恰好对应契约第 2 节secret 就绪后重新解析 provider的语义服务持有句柄而非秘密材料解析在读取时发生。6. 文件投影契约路径、模式与规则6.1 投影路径约定类型化设置可以投影到/system/settings/{scope}/{key}.json /system/extensions/{extension}/config.json /system/skills/{skill}/manifest.json6.2 三种投影模式模式含义read-only文件读反映类型化仓库写被拒绝validated write-back文件写先做 schema 校验再调用类型化仓库export-only生成快照不挂载为可写每个投影必须声明自己的模式——不允许默认即可写这种模糊状态。6.3 投影规则投影路径绝不能绕过类型化仓库的授权检查投影写回必须调用类型化仓库而不是直接改动投影存储本身投影不暴露秘密材料投影包含足够的元数据/溯源信息便于调试来源作用域同时不泄漏私有值。仓库中/system/settings、/system/extensions、/system/skills这组投影路径大量出现在运行时装配源码里例如 filesystem_assembly.rs、host_access_assembly.rs 以及 production.rs——这些装配点正是把投影文件系统挂载进运行时、并按模式决定读/写权限的位置。7. 扩展与 Skill 配置扩展/skill 配置的事实来源是扩展/skill 服务持有的类型化状态而非文件。最小生命周期状态集discovered installed authentication_required authenticated configured active disabled removed upgrade_required failed两条配置规则配置写入在扩展/skill声明了 schema 时必须按其校验扩展可以拥有私有的 state、config、cache 根目录但绝不允许把跨扩展或全局设置存到自己的命名空间之外。这套生命周期与 extensions.md 契约配合使用仓库中扩展注册/生命周期实现位于 ironclaw_extension_registry 与 ironclaw_extension_manager。8. 事件与审计脱敏优先设置变更必须发出**脱敏redacted**事件/审计记录事件族包括settings.changed settings.deleted settings.validation_failed extension.configured skill.configured审计规则事件载荷包含key、scope、actor、version/revision 以及脱敏摘要默认不发出完整的 old/new 值——避免把敏感配置内容写进事件流秘密句柄可以以 handle 形式发出但绝不能发出材料本身投影回写事件必须同时记录投影路径与类型化键使审计能双向关联文件视图与仓库状态。9. 必需验收测试清单契约最后给出 10 条必需验收测试这是实现该契约的最低验证基线键校验拒绝路径穿越/控制字符schema 校验在持久化前拒绝畸形值优先级解析选择最近的允许作用域tenant/user/project/agent 隔离性投影读反映类型化仓库投影写回完成校验并更新类型化仓库投影不能绕过授权疑似秘密值按策略被拒绝或转换为句柄设置变更发出脱敏事件/审计元数据当设置为 DB 支撑时PostgreSQL 与 libSQL 仓库行为一致repository parity。小结一条清晰的数据流把九个章节串起来IronClaw 的设置系统形成一条单向数据流操作员 bootstrapprofiles/*.toml、环境变量 ↓ 仅启动期 类型化设置仓库DB-backedschema 校验actor 审计 ↓ 按声明模式 文件投影/system/settings、/system/extensions、/system/skills ↓ 事件流 脱敏审计事件settings.changed / settings.validation_failed / ...核心不变量只有四条秘密只走句柄、写路径必须带 actor、文件投影永不绕过仓库授权、schema 在持久化前生效。这四条不变量加上第 9 节的十项验收测试构成了该契约从设计到实现的完整闭环。赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐IronClaw Reborn 启动配置契约深度解析ironclaw_config 的 config.toml 模式、秘密护栏与配置退役机制IronClaw Reborn 启动配置契约深度解析ironclaw_config 的 config.toml 模式、秘密护栏与配置退役机制 本文以 iron人工智能AI 应用交互助手AI AgentIronClaw Reborn 启动配置契约全解析ironclaw_config 与 config.toml 操作指南IronClaw Reborn 启动配置契约全解析ironclaw_config 与 config.toml 操作指南 本文围绕 IronClaw 开源仓库中人工智能AI 应用交互助手AI AgentIronClaw Hooks 框架深度解析四层信任模型、类型级权限约束与 Reborn 循环的钩子调度契约IronClaw Hooks 框架深度解析四层信任模型、类型级权限约束与 Reborn 循环的钩子调度契约 本篇技术指南以 IronClaw 开源仓库中 cr人工智能AI 应用交互助手AI Agent上一篇5分钟上手Jinja2模板网络工程师的自动化提效指南下一篇Ant Design表单文件上传多文件上传与进度展示创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考