网络与日志
用 network.proxy 设置代理,它对哪些请求和进程生效;以及日志级别和日志文件。
代理
network.proxy 设置 Agent 的代理:
hanafubuki-agent config set network.proxy http://127.0.0.1:7890
hanafubuki-agent config set network.proxy socks5h://user:pass@proxy.example.com:1080
hanafubuki-agent config set network.proxy disabled
hanafubuki-agent config set network.proxy system| 值 | 含义 |
|---|---|
"system"(默认) | 不指定代理,使用 Agent 进程环境中的设置 |
"disabled" | 不使用代理 |
| 代理 URL | 使用这个代理。支持 http、https、socks4、socks4a、socks5、socks5h,可以带用户名和密码 |
config get network.proxy 会把 URL 中的用户名和密码显示为 ***。
代理对什么生效
| 对象 | 使用的代理 |
|---|---|
网页搜索和抓取(web_search、fetch_web_page) | network.proxy,包括每一次重定向和 Jina Reader 回退;页面的域名仍在本机解析,除非你另行设置(见下文) |
| MCP 的 Streamable HTTP 服务器和 OAuth | network.proxy(包括登录和令牌刷新);修改后会重新连接这些服务器 |
| 模型运行的命令和终端 | 由 network.proxy 决定的环境变量,见下文 |
| MCP 的 stdio 服务器 | 同样的变量,覆盖它们自己的环境;修改后会重新启动它们 |
插件包和市场的下载(git) | 同样的变量(你的 git 配置中的 http.proxy 优先于它们) |
| 模型 Provider 的请求及其模型列表 | network.proxy;修改后各会话从下一轮起使用,见下文 |
models.dev 的下载(modelMetadata.modelsDev) | network.proxy |
| 终端界面启动时的更新检查 | network.proxy;发送的内容见终端界面 |
hanafubuki-agent update | 查询和下载都使用 network.proxy(配置无法读取时使用系统代理);发送的内容见 update |
命令的代理变量
模型运行的命令继承 Agent 的环境(见环境变量),随后由 network.proxy 控制代理变量:
- 代理 URL:
HTTP_PROXY、HTTPS_PROXY和ALL_PROXY设为这个 URL; "disabled":去掉HTTP_PROXY、HTTPS_PROXY和ALL_PROXY;- 以上两种都会设置
NO_PROXY=localhost,127.0.0.1,::1; "system":保留继承的代理变量(包括NO_PROXY)及命令显式指定的环境覆盖。启动 Agent 前设置代理环境变量,命令即可继承。
每个变量名都同时处理大写和小写(https_proxy、no_proxy 等),Windows 除外,因为 Windows 的变量名不区分大小写。修改只影响之后启动的命令。
MCP 的 stdio 服务器在选择后的环境和 mcp.toml 配置之上得到同样的最终代理覆盖。设为 "system" 时,只有在 transport.environmentVariables 中列出的代理变量才会继承,也可显式为该服务器配置代理值。修改代理后,已启用的 stdio 服务器会在新代理下重新启动,就像 Streamable HTTP 服务器会重新连接一样。
模型 Provider 的代理
访问模型 Provider 的请求(对话轮次、压缩、标题、回顾、记忆提取以及各 Provider 的模型列表)使用 network.proxy。修改只影响之后建立的请求:会话从下一轮起使用新代理,已经在流式传输的请求在原来的连接上完成。
设为 "system" 时,它们遵循 Agent 进程环境和操作系统的设置:启动 Agent 前设置的 HTTPS_PROXY、HTTP_PROXY、ALL_PROXY 和 NO_PROXY(大小写均可),未设置时在 macOS 和 Windows 上使用系统代理设置:
HTTPS_PROXY=http://127.0.0.1:7890 hanafubuki-agent"disabled" 无论环境如何都直接连接;设为代理 URL 时,所有 Provider 都经过这个代理,不受 NO_PROXY 影响,但本机上的 Provider(localhost、127.0.0.0/8、::1,例如 Ollama 或 LM Studio)直接连接。MCP 的 Streamable HTTP 服务器和 OAuth 以及 models.dev 的下载同样如此。
网页抓取与域名解析
fetch_web_page 拒绝不在公网地址上的页面(私有地址、回环地址、链路本地地址)。为了判断这一点,它在每次请求前、跟随每次重定向前以及询问 Jina Reader 前,都会在本机解析页面的主机名;即使 network.proxy 指定了代理也是如此,代理随后还会自己再解析一次。因此,通过代理时:
- 如果网络中只有代理能解析公网域名(本机的 DNS 不能),每次抓取都会失败,报错
web page host could not be resolved safely。web_search不受影响。 - 本机解析为私有地址的域名会被拒绝,报错
web page target is not a public web address,即使代理能访问到一个公网地址。
这项检查防止不需要审批的网页抓取访问到本机或本机所在的网络。要通过只有代理能解析域名的代理抓取网页,可以让本机能够解析公网域名(使用本机自己的 DNS,或一个本机可以访问的解析服务),也可以打开 webFetchResolveThroughProxy(/config 的网页工具):
hanafubuki-agent config set webFetchResolveThroughProxy true打开后且 network.proxy 是代理 URL 时,本机无法解析的域名交给代理解析,而不是让抓取失败。本机能解析的域名仍会检查,私有地址和 localhost 这类名称仍会被拒绝。代理为 Agent 无法检查的域名访问到什么,不再检查:页面可能引导模型访问只有代理能解析的内部域名,例如公司代理后面的内网。使用 socks5:// 代理时域名仍在本机解析;要让代理解析,请使用 socks5h://。设为 "system" 或 "disabled" 时,这项设置不起作用。
日志
独立运行的 Agent 把日志写到数据目录的 logs/hanafubuki-agent.log,hanafubuki-agent config path 会打印它的位置。日志文件超过 8 MiB 时轮换为 hanafubuki-agent.log.1,最多保留三个旧文件。
日志级别由 logLevel 设置,--log-level 只对本次运行生效:
hanafubuki-agent config set logLevel debug
hanafubuki-agent --log-level trace exec "..."| 级别 | 记录什么 |
|---|---|
off | 不记录 |
error、warn | 错误;以及警告 |
info(默认) | 启动、关闭、连接等主要事件 |
debug | 更详细的过程信息,用于排查问题 |
trace | 还记录模型和工具的内容 |
- 只有
trace记录内容:发给模型和模型返回的内容、工具的输入和输出。每条内容最多 64 KiB。 - 任何级别都不记录凭据:API 令牌、请求头和 MCP 凭据不会写入日志。
- 其他依赖库的日志最多记录到
info级别,即使设置为debug或trace也是如此。
trace
级别的日志包含对话和工具输出的内容,可能有代码、文件内容和其他敏感信息。分享日志前请检查,排查完毕后改回
info。
logLevel 和 network.proxy 只对独立运行的 Agent 有效;嵌入 Agent 的应用使用自己的日志和代理。