配置分层
默认值、用户文件、配置档、受信任项目的配置和 -c 覆盖如何叠加,以及选项的优先级。
config.toml 中的设置分层读取,从低到高。每一层只设置它写出的键;没写的键保留下一层的值。以安装和添加的内容为键的两个表 [plugins] 和 [marketplaces] 按条目合并:某一层的 [plugins."demo@my-mkt"] 只改变这个包中它写出的键,其他条目保持不变。[pluginOptions] 同样按插件和键合并(插件选项)。只有 config.toml 分层,providers.toml 和 mcp.toml 没有分层。
- 默认值
- 用户的
config.toml - 配置档:
-p 名字选择的[profiles.名字] - 项目配置:受信任项目中的
.hanafubuki-agent/config.toml -c 键=值覆盖,按给出的顺序;然后是--permission-mode和--log-level
hanafubuki-agent config get 显示叠加后的结果,hanafubuki-agent doctor 的 config 行列出读取了哪些层。
配置档
配置档是用户 config.toml 中的一个表,可以包含任何设置的键:
[profiles.review]
permissionMode = "auto_review"
logLevel = "debug"
[profiles.offline]
disabledPlugins = ["web"]hanafubuki-agent -p review
hanafubuki-agent -p offline exec "整理这个目录下的笔记"选择文件中不存在的配置档会报错。配置档中的列表(如 disabledPlugins)会替换下一层的列表,而不是合并。
设置中心的配置档也提供所有内置插件和宿主插件注册的 pluginOptions.<插件>.<选项>,复用插件声明的类型、范围和密钥编辑方式,不给新配置档填入默认值。保存时先校验整批值,再一起写入;删除某个选项就恢复使用下一层的值。
表单还提供角色覆盖和已安装插件注册的设置。Configuration layers 编辑用户文件或当前项目文件,Profiles 编辑指定配置档。每个目标显示保存位置和优先级,保存后提示更高层的覆盖。已有字段损坏时显示警告,其余有效字段仍可编辑;未知字段及无关的损坏值予以保留。
终端界面的设置中心编辑配置档(Advanced 标签页中的 Profiles):a 添加一个,每个键改动时即保存,r 把它从配置档中删除,Delete 删除整个配置档,但 Agent 当前使用的那个除外。
项目配置
项目是工作目录(-C,默认为当前目录)所在的 Git 仓库根目录;不在仓库中时就是工作目录本身。项目可以有自己的配置文件 <项目>/.hanafubuki-agent/config.toml,内容与用户文件的设置相同。
项目配置只有在用户的 config.toml 信任这个项目时才会读取,因为它来自仓库,可能是别人写的:
[projects."/home/me/src/my-project"]
trustLevel = "trusted"或者在项目目录中运行:
hanafubuki-agent config set "projects.'$PWD'.trustLevel" trusted- 路径按实际位置比较,而不是按文本比较:符号链接或同一目录的不同写法都能匹配。
- Windows 上用 TOML 的字面字符串书写路径,反斜杠不需要转义:
[projects.'C:\Users\me\src\my-project']。 trustLevel不是"trusted"的值(例如"untrusted")都表示不信任;config set ... untrusted可以撤销信任。- 读取时不会修复或改写项目配置,其中无法使用的值会告警并跳过。在 Configuration layers 中显式编辑时,可以创建或更新受信任的当前项目配置;提交的字段经校验后原子保存。
- 项目配置中不能写
profiles和projects。
-c 覆盖
-c 键=值 只在本次运行中覆盖一个键,可以重复,后面的优先:
hanafubuki-agent -c memory.enabled=true -c 'disabledPlugins=["titles"]'
hanafubuki-agent -c logLevel=debug exec "..."- 键是点分路径,例如
memory.enabled、network.proxy。每一段按.拆分,不支持引号。 - 值按 TOML 解析(
true、7、"full_access"、["a", "b"])。不是合法 TOML 时作为字符串,并去掉两端的引号,所以-c logLevel=debug不需要引号。 - 缺少
=或键为空时,命令以退出码 2 退出。 - 不认识的键(包括
profiles.*、projects.*以及providers.toml、mcp.toml的键)不会报错,只会记录到日志并忽略。
选项的优先级
--permission-mode 和 --log-level 相当于追加在所有 -c 之后的覆盖,所以总是最终生效:
hanafubuki-agent -c permissionMode=manual --permission-mode full-access config get permissionMode
# full_access-m、-C、--add-dir 和 --data-dir 不是 config.toml 的键,不参与分层。
角色
角色在设置之外有自己的分层:用户的(用户 config.toml 旁边的 agents/ 目录及其中的 [agents])、配置档的 [profiles.名字.agents],以及受信任项目的(.hanafubuki-agent/agents/ 和其配置文件中的 [agents];只在项目受信任时读取,即使项目没有 config.toml)。它们不按键合并:较高层的角色整体替换下一层的同名角色,角色要在另一个角色之上构建时使用 extends(角色的来源)。-c 覆盖中没有角色。
无法使用的值
一层中无法使用的值不会生效,通常保留下一层的值。有两个例外:
disabledPlugins不是数组时,结果是空列表(所有插件都启用),而不是下一层的值。webSearchProvider = "searxng"但这一层及以下都没有可用的searxngBaseUrl时,使用"auto"。
用户文件中的问题会被修复,见配置恢复。
示例
用户文件:
# ~/.config/hanafubuki-agent/config.toml
logLevel = "info"
[network]
proxy = "http://127.0.0.1:7890"
[profiles.review]
permissionMode = "auto_review"
[projects."/home/me/src/my-project"]
trustLevel = "trusted"项目配置:
# /home/me/src/my-project/.hanafubuki-agent/config.toml
webSearchProvider = "duckduckgo"
[memory]
enabled = false在 /home/me/src/my-project/crates/core 中运行 hanafubuki-agent -p review -c logLevel=debug 时:权限模式是 auto_review(配置档),记忆关闭(项目),网页搜索用 DuckDuckGo(项目),代理是 http://127.0.0.1:7890(用户文件),日志级别是 debug(-c)。
Agent 写入什么
普通的全局设置写入和 config set 编辑用户的 config.toml。设置中心还支持明确选择目标:Profiles 编辑选中的配置档表,Configuration layers 可以编辑用户文件或受信任的当前项目文件;其来源操作会显示保存路径和优先级。写入保留注释和未知键,不会隐式把高层的生效值复制到其他层。保存后仍可能被更高优先级的层覆盖。