hanafubuki-agent

配置

配置目录、三个配置文件,以及用 config path、get、set、edit 查看和修改配置。

独立运行的 Agent 把配置保存在配置目录中,默认是 Linux 的 ~/.config/hanafubuki-agent/、macOS 的 ~/Library/Application Support/hanafubuki-agent/ 和 Windows 的 %APPDATA%\hanafubuki-agent\。设置 HANAFUBUKI_AGENT_HOME 后,配置和数据都放在这一个目录中。完整说明见数据目录。

嵌入 Agent 的应用(例如 Hanafubuki)使用自己指定的配置目录,并且只读取用户文件,不使用配置档、项目配置和 -c 覆盖,通常由应用自己的设置页面来修改。

三个文件

文件内容分层权限
config.toml设置:权限模式、沙箱、记忆、插件、网页工具、压缩策略、代理、日志级别、终端界面;配置档;受信任的项目有普通
providers.toml模型 Provider、它们的令牌,以及模型策略(模型、推理强度、压缩)无仅自己可读(0600)
mcp.tomlMCP 服务器及其凭据无仅自己可读(0600)

文件在需要时才创建:第一次 config set 时创建 config.toml,第一次 providers add 时创建 providers.toml,依此类推。没有文件时使用默认值。所有键使用 camelCase。每个键的类型和默认值见配置参考。

providers.toml 和 mcp.toml 通常用 providers 和 mcp 命令修改,也可以直接编辑。

它们旁边的 agents/ 目录存放你的角色文件,config.toml 中的 [agents] 条目也可以定义角色。

查看配置

hanafubuki-agent config path            # 各个文件和目录的位置
hanafubuki-agent config get             # 应用所有分层后的全部设置
hanafubuki-agent config get logLevel    # 一个键的值
hanafubuki-agent config get memory      # 一个表

config get 输出的是最终生效的值,即默认值、用户文件、配置档、项目配置和 -c 叠加之后的结果。字符串原样输出,其他值输出为 TOML。代理 URL 中的用户名和密码显示为 ***。没有设置的可选键不输出任何内容。

修改配置

hanafubuki-agent config set logLevel debug
hanafubuki-agent config set memory.enabled true
hanafubuki-agent config set sandboxMode read-only
hanafubuki-agent config set network.proxy http://127.0.0.1:7890
hanafubuki-agent config set tui.alternateScreen never
hanafubuki-agent config set profiles.review.permissionMode auto_review
hanafubuki-agent config set "projects.'$PWD'.trustLevel" trusted

config set 把一个键写入用户的 config.toml。键是 TOML 的点分键,包含特殊字符的部分要加引号(如上面的项目路径)。值按 TOML 解析,不是合法 TOML 时作为字符串,所以 debug 不需要加引号。

config set 接受:

  • 任何设置的键,见配置参考;
  • 配置档中的键:profiles.名字.键;
  • 项目的信任级别:projects."路径".trustLevel,值为 trusted 或 untrusted;
  • 插件的选项:pluginOptions.名字.键,按插件的选项检查(插件选项);config get pluginOptions.名字.键 打印它的值,没有设置时打印默认值。

它会拒绝不认识的键和 Agent 无法使用的值。设置的值先按该设置接受的内容(类型、范围、可选值)检查,再带着它重新读取文件,所以违反设置之间规则的值也会被拒绝(如 webSearchProvider = "searxng" 而没有 searxngBaseUrl),例如:

error: `nosuch` is not a setting of config.toml
error: `memory.maxUnusedDays` cannot take this value: it is between 1 and 3650

写入只修改这一个键,保留文件中的注释和其他内容。config set 不能删除一个键;要删除,请编辑文件,或在 /config 中重置该设置(r)。

终端界面的 /config 是设置中心:Agent 的设置目录中的所有设置分标签页显示,每个值按 config set 的方式检查,改动即保存,写入用户的 config.toml(Provider、模型策略和模型覆盖写入 providers.toml,MCP 服务器写入 mcp.toml)。每一行会标出你的文件之上设置了它的那一层,保存时如果配置档、项目文件或 -c 替换了写入的值,也会说明。设置旁边是各个集合(Provider、MCP 服务器、插件、钩子、角色、配置档、项目……)以及 /theme、/statusline 和 /title、/keymap、/presets、/plugins、/hooks 和 /memories 打开的页面;/tui 打开它的 [tui] 设置,/raw 以同样的方式写入 tui.rawOutput。自定义高亮主题不在配置目录中:它们是数据目录 themes/ 下的 .tmTheme 文件。

设置中心还提供以下管理操作:

  • Skills(也可用 /skills):查看来源与指令、启用/禁用、从本地目录安装并显式选择是否覆盖,以及删除用户安装的 Skill;受保护的来源保持受保护。
  • Hooks:新增、编辑和删除用户定义,包括事件、匹配器、命令、超时和状态文本。编辑后需重新信任;不写入项目或插件定义。Hook review 仍负责所有来源的信任与启停。
  • Roles / Role source files:关联 configFile、查看来源、创建并编辑用户 agents/ 中的文件,或复制为继承原指令与限制的新用户角色。内置、插件、项目和外部源文件在此保持只读。
  • Profiles / Configuration layers:显式选择配置档、用户或已信任的当前项目;表单包含角色覆盖和已注册的已安装插件设置,隐藏密钥值、保留未知存储字段,并说明保存路径与优先级。坏字段会告警,不隐藏有效字段;无效的新提交整组拒绝。
  • Providers / Model overrides:测试连通性,按 Provider 或模型覆盖条目清理学习到的模型信息,保留手动覆盖。
  • Sandbox status and repair:显示可用状态或失败原因;Windows 上可显式初始化/修复提升沙箱。UAC 异步执行,成功后才保存设置。
  • Updates and diagnostics(也可用 /maintenance):显示当前版本、检查更新、安装最新版或运行 doctor。操作由独立 CLI 负责;终端报告显示后按 Enter 返回 TUI。更新后需重启 Agent。

编辑文件

hanafubuki-agent config edit

用 $VISUAL 或 $EDITOR 打开用户的 config.toml(目录不存在时先创建)。编辑器可以带参数,例如 EDITOR="code --wait"。

手动编辑的内容在下一次启动 Agent 时读取。如果文件中有无法使用的值,Agent 会修复它,并先把原文件复制到 .recovery/,见配置恢复。

压缩

会话的上下文随每个回合增长;compaction.strategy 决定如何让它保持在模型的窗口之内。每个会话在下一个回合采用该策略。

策略如何缩减上下文
"standard"默认值。上下文用到窗口的 autoCompactThresholdPercent 时,在回合之前或回合之中把较早的对话写成摘要(上下文窗口与压缩)
"background"同样的摘要,但更早开始(compaction.background.thresholdPercent,默认 65%),并在会话继续进行时于后台写成;它在下一次请求之前安装。只有上下文已无空间时,会话才会等待它
"hierarchical"模型把自己历史中的片段折叠成它写的摘要,并可以再次展开;保存的历史从不改变。只有已没有可折叠的内容时才运行标准压缩
hanafubuki-agent config set compaction.strategy hierarchical
hanafubuki-agent config set compaction.hierarchical.contentStore true

终端界面中的 /config 可以切换策略;在 hierarchical 下,/compression 显示模型折叠出的块及其节省的量。每种策略都以标准压缩为底线:/compact 和 Provider 报告上下文窗口错误之后的重试都会运行它。[compaction] 的每个键以及各策略的细节见配置参考。

hierarchical 策略是 billion-context 的算法:hanafubuki-agent 使用了 ranxianglei 的 acp-kernel 和 billion-context,采用 MIT 许可证并附加一项署名条款(许可证)。

钩子

钩子是你配置的命令,在 Agent 触发某个事件时运行:工具调用之前或之后、会话开始时、你提交消息时、轮次结束之前。格式与 Codex 相同,所以它的 hooks.json 文件和 [hooks] 表可以原样使用。钩子只有在你信任之后才会运行。

它们从两个地方读取,每处都可以写成 hooks.json 或 config.toml 的 [hooks] 表(两者选其一),然后从启用的已安装插件读取(插件的钩子):

  • 配置目录,即用户自己的钩子;
  • 项目的 .hanafubuki-agent/,在读取项目配置时:用户的 config.toml 信任该项目(配置层),并且项目有 .hanafubuki-agent/config.toml。

每个轮次开始时都会重新读取,所以修改从下一个轮次起生效,不需要重启。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|exec_command",
        "hooks": [{ "type": "command", "command": "~/bin/check-command.sh", "timeout": 30 }]
      }
    ],
    "Stop": [{ "hooks": [{ "type": "command", "command": "~/bin/tests-pass.sh" }] }]
  }
}

在 config.toml 中写法相同:

[[hooks.PreToolUse]]
matcher = "Bash|exec_command"

[[hooks.PreToolUse.hooks]]
type = "command"
command = "~/bin/check-command.sh"
timeout = 30
事件时机matcher 匹配钩子可以
PreToolUse工具调用的审批之前工具名(exec_command 也作为 Bash,apply_patch 也作为 Write、Edit)拒绝调用:以退出码 2 退出并把原因写到 stderr,或输出 {"hookSpecificOutput": {"permissionDecision": "deny", "permissionDecisionReason": "…"}}(或 {"decision": "block", "reason": "…"});模型把原因读作调用的错误
PostToolUse调用运行之后工具名,同上为模型添加上下文:{"hookSpecificOutput": {"additionalContext": "…"}},或以退出码 2 退出并写到 stderr
SessionStart会话的第一个轮次(Agent 运行期间每个会话一次)startup为会话添加上下文:stdout 上的纯文本,或 additionalContext
UserPromptSubmit你提交消息时(不使用)为轮次添加上下文:stdout 上的纯文本,或 additionalContext;不能阻止消息
Stop模型给出最终回答时(不使用)让轮次继续:{"decision": "block", "reason": "…"} 或退出码 2,原因作为模型的下一条指示;{"continue": false} 结束轮次
  • matcher 为空或 * 时匹配一切;用 | 连接的名字精确匹配其中之一;其他写法是正则表达式。
  • 命令通过你的 shell 运行($SHELL -lc,Windows 上为 %COMSPEC% /C),工作目录是当前工作目录,事件以 JSON 写到它的 stdin:session_id、turn_id、cwd、hook_event_name 和事件自己的字段(tool_name、tool_input、tool_use_id 与 tool_response;prompt;source;stop_hook_active 与 last_assistant_message)。Windows 上用 commandWindows 代替它。timeout 以秒计(默认 600);statusMessage 在运行时显示。
  • 退出码 0 且 stdout 为空表示什么都不做。其他退出码、超时或无法读取的 JSON 是钩子的失败:会被记录且不起作用,所以坏掉的钩子从不让调用或轮次停下。钩子的输出按宽松方式读取:Agent 不用的字段被忽略。
  • 同一事件的钩子按配置顺序依次运行(用户的在前);PreToolUse 遇到第一个拒绝就结束。
  • 不支持 Codex 的其他事件(PermissionRequest、PreCompact、PostCompact、SessionEnd、SubagentStart、SubagentStop、PreModelRequest、PostModelRequest、Interrupt)、它的 mcp_tool、prompt 与 agent 钩子,以及 async 命令:它们会被报告,从不运行(SubagentStart 和 SubagentStop 是因为 Agent 在子代理开始或停止时不运行钩子)。文件中无法使用的内容逐项跳过;其余照常加载。

信任

钩子只有在你信任之后、并且处于启用状态时才会运行。每个钩子有一个键 <文件>:<事件>:<组>:<钩子>(/home/me/.config/hanafubuki-agent/hooks.json:pre_tool_use:0:0),信任它会记录它定义的哈希(事件、matcher、命令、超时和状态消息)。定义改变了的钩子是 modified,在你再次信任之前不会运行。基于 Agent 的应用通过门面的钩子调用列出钩子及其信任状态、信任它们并开关它们(功能调用);在终端界面中由 /hooks 完成(终端界面),界面启动时还会说明有几个钩子需要审查。信任与启用状态保存在数据目录的 hooks-state.json 中,而不是 config.toml;Codex 的 [hooks.state] 被忽略。

插件的钩子

启用的 Codex、Claude Code 或 Cursor 格式的已安装插件带来它的钩子:清单的 hooks 指定的文件(或写在清单中的钩子文件),否则是 hooks/hooks.json。它们排在用户和项目的钩子之后,随插件出现和消失。与 Codex 相同,Agent Plugins 包的钩子从不运行。

  • 插件钩子的键写明插件和插件内的文件:<plugin>@<marketplace>:<路径>:<事件>:<组>:<钩子>(demo@my-mkt:hooks/hooks.json:pre_tool_use:0:0;写在清单中的钩子是 plugin.json#hooks[N]),所以它的状态在插件更新后仍然保留。
  • 信任它会记录它定义的哈希和它整个包的内容哈希(不计 __pycache__、.venv、*.pyc 和 *.egg-info);它的哈希显示为 <定义>/<内容>。每次运行它的钩子之前都会重新计算包的哈希:包中任何内容改变后,它的钩子就是 modified,不会运行,并以 "plugin contents changed; hook approval required" 失败,直到你再次信任它们。
  • 它运行时 PLUGIN_ROOT 和 CLAUDE_PLUGIN_ROOT 设为包的目录,PLUGIN_DATA 和 CLAUDE_PLUGIN_DATA 设为它自己的数据目录,所以写成 ${CLAUDE_PLUGIN_ROOT}/hooks/check.sh 的命令运行的是包里的脚本。
  • 插件同样只运行上面五个事件;其他事件和你自己的钩子一样被报告。/hooks 列出插件的钩子及其插件。

示例

# ~/.config/hanafubuki-agent/config.toml
permissionMode = "manual"
sandboxMode = "workspace-write"
logLevel = "info"

[sandboxWorkspaceWrite]
writableRoots = ["/home/me/.cargo"]
networkAccess = true

[memory]
enabled = true

[network]
proxy = "http://127.0.0.1:7890"

[tui]
fullscreenTranscript = true
rawOutput = false
theme = "catppuccin-mocha"
statusLine = ["model-with-reasoning", "git-branch", "context-remaining"]
terminalTitle = ["activity", "project-name"]

[tui.keymap.global]
open_transcript = "ctrl-q"

[tui.presets.1]
input = "/statusline git-branch context-remaining --colors"
label = "Branch and context"

# hanafubuki-agent -p review
[profiles.review]
permissionMode = "auto_review"
sandboxMode = "read-only"

[projects."/home/me/src/my-project"]
trustLevel = "trusted"

配置档、项目配置和 -c 如何叠加,见配置分层。

本页目录