hanafubuki-agent

故障排查

用 doctor 检查环境,解决常见问题,查看日志和崩溃记录,以及报告问题。

先运行 doctor

hanafubuki-agent doctor
hanafubuki-agent doctor --online
ok    config    /home/me/.config/hanafubuki-agent/config.toml
ok    providers 1 configured; the default provider-1 (https://api.openai.com/v1) runs gpt-5.1
ok    mcp       2 configured, 2 enabled
ok    roles     2 usable (default, explorer)
FAIL  keyring   No default store has been set, so cannot search or create entries
ok    data      /home/me/.local/share/hanafubuki-agent (not in use)
skip  online    the Provider and the MCP servers are reached with --online

每项检查打印一行 ok、FAIL 或 skip,有任何 FAIL 时以退出码 1 退出。

检查内容
config读取了哪些层:用户的 config.toml(或者没有,使用默认值)、配置档、项目配置(以及项目是否受信任)、-c 覆盖。不存在的配置档为 FAIL。还会列出本次运行中修复过的文件,见配置恢复
providersProvider 的数量,以及默认 Provider 的地址和模型。没有默认 Provider 或没有设置模型为 FAIL
mcpMCP 服务器的数量和启用的数量
roles可用的角色(包括开启的已安装插件的角色),以及有几个不可用;然后每个读取或解析时的问题各占一行,插件的问题写明该插件(角色)。不可用的角色不算 FAIL
keyring系统密钥环能否读取
data数据目录能否共享访问;旧版 Agent 或维护操作持有独占锁时为 FAIL
online只在 --online 且数据目录空闲时运行:启动 Agent,列出默认 Provider 的模型(provider 行)及对每个模型所知道的信息(每个模型一行 model,如 gpt-5.1: window 400000 (reported), vision yes (reported)),连接每个启用的 MCP 服务器(mcp 行)

不带 --online 时,doctor 不启动 Agent,可以在另一个 Agent 进程运行时使用。

常见问题

没有默认 Provider

error: No default Agent Provider is configured
FAIL  providers 0 configured, none the default (hanafubuki-agent providers default ID)
FAIL  providers no model is set (hanafubuki-agent providers default ID --model MODEL)

添加一个 Provider,并设置模型:

hanafubuki-agent providers add OpenAI --base-url https://api.openai.com/v1 --api-key-env OPENAI_API_KEY
hanafubuki-agent providers default provider-1 --model gpt-5.1

providers add 报告 the environment variable X is not set 时,先 export 这个变量。见快速开始。终端界面中的 /providers(设置中心)也可以完成这两步,缺少它们时界面会自动打开它(见首次设置)。

Provider 请求失败

error: the turn failed (model_request_retries_exhausted): agent model request retries exhausted after 3 attempt(s): connection failed
原因怎么查
地址或协议错误providers list 检查地址和协议;地址应当是协议路径之前的部分,例如 https://api.openai.com/v1
令牌无效或过期(model_error)编辑 providers.toml 中的 apiToken,或删除后重新添加 Provider
模型名称错误终端界面的 /model 列出 Provider 实际提供的模型
需要代理Provider 请求读取 HTTPS_PROXY 等环境变量,而不是 network.proxy,见网络与日志
网络不通doctor --online 检查默认 Provider 是否能列出模型

回合失败的其他原因(turn_failed 的 reason)见 exec --json 事件。

数据目录被占用

新版 Agent 可以共用数据目录。如果启动提示目录被 exclusively locked,说明旧版 Agent 或维护操作仍持有独占锁。关闭旧进程,或等待维护完成;可以用 ps、任务管理器等定位进程。原来的 only one Agent may use a data directory at a time 提示来自旧版本。

session … is in use by another Agent 表示该会话已有拥有者:可以新建对话,或先关闭拥有该会话的实例,再继续它。共享历史列表仍可查看。进程结束或崩溃后由操作系统释放锁,不要手动删除锁文件。见数据目录。

密钥环不可用

FAIL  keyring   No default store has been set, so cannot search or create entries

系统密钥环(Linux 上的 Secret Service、macOS 的钥匙串、Windows 的凭据管理器)不可用。没有桌面环境的 Linux 服务器和容器上很常见。它只用于 MCP 服务器的 OAuth 令牌,Provider 令牌和 MCP 凭据都保存在配置文件中,所以通常可以忽略这一行。需要时,安装并启动 GNOME Keyring 或 KWallet 等 Secret Service 实现。

MCP 服务器无法连接

hanafubuki-agent mcp connect 服务器ID

mcp connect 打印连接状态和错误。终端界面中的 /mcp 也会显示每个服务器的错误。

症状检查
stdio 程序无法启动程序是否在 PATH 中(或使用绝对路径)、参数、cwd、需要的运行时(Node.js、Python 等)
HTTP 无法连接URL、network.proxy、证书、服务是否在运行
认证失败mcp.toml 中的 credentialEnvironment 或 credentialHeaders 是否指向存在的凭据键;改值后 generation 是否加一
需要 OAuth独立运行的命令行目前没有 OAuth 登录,见 MCP
已连接但模型没用工具暴露策略默认是 deferred,模型需要时才会搜索;enabledTools、disabledTools 和 hidden
超时connectTimeoutSeconds、initializeTimeoutSeconds、callTimeoutSeconds

配置文件只读

FAIL  config    /home/me/.config/hanafubuki-agent/config.toml: repaired ...; read-only until the Agent restarts: ...

Agent 需要修复这个文件,但无法在 .recovery/ 中保存原文件或无法写回文件,所以在内存中使用修复后的值,并拒绝修改这个文件。检查配置目录的权限和磁盘空间,以及 .recovery 是否被一个普通文件占用,然后重新运行。见配置恢复。

配置没有生效

  • 用 hanafubuki-agent config get 键 查看最终生效的值,doctor 的 config 行查看读取了哪些层。
  • 项目配置只有在项目受信任时才会读取,见配置分层。
  • --permission-mode 和 --log-level 优先于 -c。
  • 无效的值会被替换为默认值,原文件在 .recovery/ 中。

终端界面的问题

症状原因和处理
the terminal interface needs a terminal标准输入或输出不是终端。在脚本中使用 exec
Esc 不能中断回合模型开始输出回答后状态行隐藏,Esc 不再中断;用 Ctrl-C
Shift+Enter 发送了消息终端不支持增强键盘协议,用 Ctrl+J 换行
启动时报 the terminal: ...终端没有响应光标位置查询;换一个终端模拟器,或使用 exec

日志

日志文件是数据目录中的 logs/hanafubuki-agent.log,hanafubuki-agent config path 打印它的位置。排查问题时,先提高日志级别再重现:

hanafubuki-agent --log-level debug exec "..."

trace 级别还会记录模型和工具的内容,可能包含敏感信息。见网络与日志。

崩溃记录

Agent 内部发生错误(panic)时,会把报告写到标准错误,并在数据目录中留下 crash-record.json。start-marker.json 记录没有正常结束的启动,用于发现反复崩溃。崩溃后,下一次启动会清理上次遗留的进程。

exec 运行中 Agent 停止时,会报告 the Agent stopped after an internal error, and the turn with it: ... 并以退出码 1 退出。

报告问题

在 GitHub Issues 中报告问题,并附上:

  1. hanafubuki-agent --version 的输出和操作系统;
  2. hanafubuki-agent doctor 的输出;
  3. 重现的步骤,以及期望和实际的结果;
  4. 相关的日志片段(debug 级别),以及 crash-record.json(如果有)。

提交前检查日志和配置中是否有 API 令牌、凭据、私有代码或其他敏感内容。不要附上 providers.toml 和 mcp.toml。

本页目录