如何修复 Hoppscotch REST 请求失败Agent 接入与排查完整指南【免费下载链接】hoppscotchOpen-Source API Development Ecosystem • https://hoppscotch.io • Offline, On-Prem Cloud • Web, Desktop CLI • Open-Source Alternative to Postman, Insomnia项目地址: https://gitcode.com/GitHub_Trending/ho/hoppscotch在 Hoppscotch 浏览器环境中发送 REST 请求时你可能反复遇到请求发不出、CORS 报错或证书握手失败的情况。这类 Hoppscotch REST 请求失败大多不是你的请求写错了而是浏览器本身的安全边界在拦截流量。Hoppscotch Agent 作为运行在本地的 HTTP 中继是打通这一链路的核心组件下面按定位根因 → 首次接入 → 按需配置 → 故障自查的顺序带你诊断和解决。为什么浏览器插件发不出请求先做一个判断如果你的 REST 请求在 Postman 或 curl 里正常、唯独在浏览器里的 Hoppscotch 失败问题几乎都出在浏览器的三重限制上。CORS 与跨域预检浏览器会拦截跨域响应中缺少正确访问控制头的流量请求可能在到达目标 API 前就被拒绝而这类头你无法在客户端补上。客户端证书双向 TLS浏览器对 Web 应用加载 mTLS 客户端证书支持极为有限需要双向认证的网关、金融类 API 在浏览器里基本走不通。受限的自定义 Header像User-Agent、部分Host相关的头字段会被浏览器出于安全考虑覆盖或屏蔽你填了也不生效。此外还有本地网络与localhost访问受限等次要因素。Hoppscotch Agent 的定位就是绕开这些边界它作为本地系统服务常驻在9119端口介于 Hoppscotch Web 应用与目标 API 之间。浏览器只与localhost:9119通信该链路使用 AES-256-GCM 加密、X25519 密钥交换建立真正的请求由 Agent 以桌面程序身份发出——CORS 由本地处理证书、受限头、代理、本地网络访问都不再受浏览器约束。首次接入安装 Agent 并完成 OTP 注册整个首次运行流程可以拆成准备、执行、验证三个阶段全程大约两到三分钟。准备阶段从官方发布渠道下载与你系统对应的安装包Windows 10/11 x64、macOS 10.15、Linux GLIBC 2.38 以上。标准版带安装向导、自动启动和自动更新如果不想落盘安装可选便携式版本——解压后直接运行可执行文件即可但它不自动启动、不自动更新重启后要手动拉起。装完先确认两件事系统托盘出现 Hoppscotch 图标且防火墙没有拦截9119端口端口可访问性是后面所有排障的前提。执行阶段打开 Hoppscotch Web 应用进入Settings→Interceptors在拦截器列表中选中Agent并点击注册按钮。此时把焦点切到 Agent 窗口它会显示一个 6 位验证码回到页面把它填入 OTP 输入框并确认。注意验证码有有效期超时了就重新发起注册不要反复试同一个旧码。验证阶段注册成功后 Agent 界面会显示一个掩码后的认证密钥哈希同时托盘的显示注册里能看到活动连接。此时再用浏览器访问localhost:9119/handshake应能收到响应。若你使用的是自托管的 Hoppscotch 实例还需注意 Agent 与 Web 应用的版本要匹配版本错配是注册失败的常见隐性原因。按需进阶三类场景配置Agent 的配置是全局默认 按域名覆盖的模型全部入口都在Settings→Interceptors→Agent。先想清楚你属于下面哪一类场景再动手改对应域名的配置。当您需要客户端证书调用内网 APImTLS面对要求双向认证的网关时进入目标域名的Client Certificates配置。Agent 支持两种格式.pem需要证书文件与私钥文件分开上传.pfx/.pkcs12是单文件按需输入密码。上传后配置会按域名自动保存。配完先问自己一句私钥和证书是否同一对、证书是否在有效期内——这两点是 mTLS 握手失败的最高频原因。当您需要通过带认证的代理转发请求企业内网往往要求流量经指定代理出网。选中目标域名打开Proxy开关填入带协议的代理地址如http://proxy.example.com:8080再按需配置用户名密码。Agent 支持 HTTP/HTTPS 代理及 NTLM 等认证方式且不同域名可以挂不同的代理互不干扰。当您需要为不同域名设置不同安全策略域名管理弹窗里*是全局默认项对所有域名生效且不可删除其余域名各自维护一份覆盖配置。每个域名下可以独立控制Verify HostSSL 握手时是否校验主机名、Verify Peer是否校验对端证书、上传自定义CA 证书以及上述客户端证书。典型用法是全局保持严格校验只对企业自签名 CA 的域名放宽并挂上对应 CA 证书而不是全局关闭校验。故障自查遇到报错不要盲目重装按下表按症状对号入座能覆盖绝大多数 Agent 相关问题。现象可能原因处理办法弹窗提示 Agent not detectedAgent 进程未运行或9119被防火墙拦截查看系统托盘是否有图标检查防火墙放行9119拦截器切换被弹窗卡住检测失败后页面拒绝切换重启浏览器并在更改拦截器设置前先停止 AgentFailed to initiate the registration浏览器安全策略或扩展冲突macOS 上 Safari 对localhost:9119有访问控制限制换用 Chrome 或 Firefox 完成注册OTP 输入框缺失、或填码无效Agent 窗口未聚焦未出码或 6 位码已过期聚焦 Agent 窗口等待出码过期则重新发起注册注册成功但仍有 CORS 报错拦截器未真正生效请求没走 Agent确认拦截器为 Agent且请求实际经由localhost:9119转发自定义 Header 未生效拦截器未选 Agent浏览器仍按默认方式覆盖头字段确认 Agent 拦截器已选中后重发证书校验/握手失败格式不支持、证书过期、私钥不匹配、PFX 密码错误、域名配置挂错位置核对.pem/.pfx格式与有效期确认域名配置与目标 API 主机名一致自托管部署下行为异常Agent 与 Web 应用版本不匹配让自托管实例与 Agent 的 release 版本对齐如果以上都不中直接翻 Agent 日志路径见下方速查重点看连接错误、证书校验失败与代理认证失败三类记录。速查参考配置与日志目录排查与备份时直接用Windows配置%APPDATA%\io.hoppscotch.agent\日志%LOCALAPPDATA%\io.hoppscotch.agent\logs\macOS配置~/Library/Application Support/io.hoppscotch.agent/日志~/Library/Logs/io.hoppscotch.agent/Linux配置~/.config/io.hoppscotch.agent/日志~/.local/share/io.hoppscotch.agent/logs/系统托盘快捷功能显示注册查看活动连接、清除注册移除全部已注册实例、最大化窗口呼出 Agent 界面、退出。通信参数默认端口9119传输层 AES-256-GCM 加密X25519 密钥交换注册走一次性 6 位 OTP。相关源码Agent 本体位于仓库的packages/hoppscotch-agent/拦截器前端逻辑在packages/hoppscotch-common/src/platform/std/kernel-interceptors/阅读 packages/hoppscotch-agent/README.md 可获取完整功能清单。发送请求前的 4 项检查Agent 活着托盘有图标9119端口未被防火墙拦截。拦截器对了Settings→Interceptors中当前生效的是 Agent且注册连接未失效。域名配置对路目标域名的证书、代理、校验策略已保存且覆盖关系符合预期*是默认值具体域名优先级更高。版本没错配自托管场景下Agent 与 Web 应用 release 版本一致。四项都过REST 请求仍失败时问题大概率已不在浏览器侧转而去查目标 API 自身的鉴权与网络链路即可。【免费下载链接】hoppscotchOpen-Source API Development Ecosystem • https://hoppscotch.io • Offline, On-Prem Cloud • Web, Desktop CLI • Open-Source Alternative to Postman, Insomnia项目地址: https://gitcode.com/GitHub_Trending/ho/hoppscotch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考