Hoppscotch Agent 实用指南浏览器发不出 REST 请求时如何用本地中继打通整条链路【免费下载链接】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/hoppscotchHoppscotch 是一套开源的 API 开发工具支持网页、桌面和 CLI 多种形态。但它的网页版本质上是跑在浏览器里的而浏览器的安全模型会拦截大量 API 测试中常用却越权的操作跨域被 CORS 挡下、自定义User-Agent等头部被强制改写、无法携带客户端证书做 mTLS、也够不到内网和 localhost 的服务。Hoppscotch Agent 就是为这个问题设计的本地请求中继组件它在你的机器上监听 9119 端口由它代替浏览器把 REST 请求真正发出去。本文按为什么失败、装在哪里、怎么注册、如何按域名配证书和代理、连不通时查哪里的顺序带你把这条链路完整搭起来。先搞清楚浏览器到底卡住了什么在装任何工具之前先确认你的问题是不是浏览器层面的。典型症状有三类CORS 报错接口明明能通网页里却提示跨域不允许。此时请求根本没到达目标服务或响应被浏览器丢弃。头部不生效你设置的User-Agent、Origin等受限头部发出的报文里仍是浏览器默认值。浏览器在部分默认 HTTP 方法下会直接覆写这些字段。够不到内网localhost、局域网 IP、需要双向 TLS 证书的内部接口浏览器要么禁止访问要么根本没有让你上传证书的地方。如果你的请求失败属于这三类说明瓶颈不在 API 本身而在谁来发这个请求。思路很简单既然浏览器不能发就让一台本地程序替你发浏览器只负责编辑请求和展示结果。这正是 Hoppscotch Agent 的定位。这个本地中继是怎么工作的Agent 是一个基于 Tauri V2 的跨平台小程序安装后常驻系统托盘。它的工作方式可以概括为三步网页端把要发出的请求通过本地 9119 端口交给 AgentAgent 在本地真实执行请求拿到响应后回传网页与 Agent 之间的通道用 AES-256-GCM 加密密钥协商采用 X25519 交换注册环节用一次性的 6 位验证码OTP完成绑定。在网页端这体现为拦截器Interceptor机制进入Settings → Interceptors默认是浏览器直接发送切换为Agent后所有请求就会改道本地中继。你可以在 Agent 的 官方说明文档 中查看协议细节和全部配置项。安装标准版和便携版怎么选标准版适合日常使用。从官方发布页下载对应操作系统的安装包运行安装向导完成后Agent 会自动启动并出现在系统托盘随后每次开机自启并支持自动更新。便携版适合不想在系统里留痕的场景解压即运行不写注册表、不占安装目录代价是没有自动启动、没有自动更新用的是独立的便携配置。两个版本的运行依赖略有差异Windows 需要 WebView2 Runtime标准版安装时会一并装好Linux 要求 WebKit2GTK 2.44 以上且 GLIBC 2.38 以上。配置和日志分别存放在不同位置排障时都会用到类别WindowsmacOSLinux配置%APPDATA%\io.hoppscotch.agent\~/Library/Application Support/io.hoppscotch.agent/~/.config/io.hoppscotch.agent/日志%LOCALAPPDATA%\io.hoppscotch.agent\logs\~/Library/Logs/io.hoppscotch.agent/~/.local/share/io.hoppscotch.agent/logs/装好后确认两件事托盘里有 Hoppscotch 图标且防火墙放行了 9119 端口。这两条不满足后面注册流程会直接卡住。完成注册从 6 位验证码到加密通道注册是网页端和 Agent 之间的握手整个过程不超过一分钟打开 Hoppscotch 网页版进入Settings → Interceptors在拦截器列表中选中Agent点击Register Agent按钮此时 Agent 窗口会弹出一个 6 位数字验证码保持 Agent 窗口处于聚焦状态把验证码填入网页上的 OTP 输入框点击确认建立加密通道注册成功后Agent 界面会显示一段打码的认证密钥哈希网页端则进入可发送状态。托盘菜单里的Show Registrations可以查看当前活跃的注册连接Clear Registrations用于解绑全部实例——换设备或密钥异常时从这里重绑。如果你的环境是自托管实例还要注意版本配套问题Agent 发布版与 Hoppscotch 网页端版本之间可能存在兼容性差异注册报版本不匹配时去发布页选择与你的网页端版本对应的 Agent 版本。按域名配置证书、CA 与代理Agent 的配置是按域名组织的*是全局默认值对任意域名生效具体域名如api.example.com可以单独覆盖在域名管理弹窗里增删。下面是三组最常用的配置SSL/TLS 校验控制。每个域名都可以独立开关验证主机名和验证对等证书并可上传自定义 CA 证书。内网 CA 签发的接口通常需要这两项配合使用关掉校验只建议用于开发环境。客户端证书mTLS。接口要求双向认证时在对应域名下点击Client Certificates有两种格式可选PEM证书文件.crt/.cer/.pem和私钥文件.key/.pem分开上传PFX / PKCS12单文件上传有密码保护时填入密码。配置会自动按域名保存下次打开无需重配。代理路由。开启域名的 Proxy 开关后填入代理地址注意协议头不能省http://或https://都要写全需要认证的代理可再填用户名和密码支持 NTLM 等认证方式。不同域名可以走不同代理。验证链路是否真正打通注册成功不等于所有请求都走了中继建议做一次端到端确认确认拦截器当前选中的是 Agent而不是浏览器默认发送发一个指向内网或 localhost 的请求——这类地址只有中继能访问到成功返回本身就证明请求绕过了浏览器托盘里点Show Registrations确认有活跃连接如果仍看到 CORS 报错说明请求还没走 9119 端口回到第一步检查拦截器状态。响应状态码正常、且内网地址可以访问这条链路就算打通了。常见故障自查表连不通时按下面这张表从上往下查能覆盖绝大多数情况现象可能原因处理办法提示 Agent not detectedAgent 没在运行或 9119 被防火墙挡住检查托盘图标放行 9119 端口弹窗挡住拦截器切换浏览器与 Agent 的旧会话残留重启浏览器切换前先把 Agent 停掉再重启Failed to initiate the registration浏览器安全策略或扩展冲突换无痕窗口或另一个浏览器试OTP 输入框没有出现Agent 窗口未聚焦把 Agent 窗口切到前台等 6 位码显示出来验证码提交无效OTP 有时效重新发起注册用新生成的验证码只有 Safari 上注册失败macOS Safari 对 localhost:9119 的访问控制更严格改用 Chrome 或 Firefox 完成注册自定义头部仍未生效拦截器没选中 Agent确认 Interceptors 当前为 Agent客户端证书校验失败格式、有效期或私钥不匹配确认是 PEM/PFX 之一、证书未过期、私钥与证书配对、域名配置与接口主机名一致自托管实例注册报版本错误Agent 与网页端版本不配套在发布页选择与网页端匹配的 Agent 版本各平台的系统级问题也有对应入口Windows 查 WebView2 Runtime、Defender 排除项和防火墙规则macOS 查 Gatekeeper 与安全隐私设置Linux 查 WebKit2GTK 依赖、GLIBC 版本服务起不来时看 systemd 日志。仍然定位不了的打开上面表格列出的日志目录找连接错误、证书校验失败和代理认证失败三类关键字。把 Agent 装好、注册完成、按需配上证书和代理之后浏览器里那些发不出去的 REST 请求就有了一个稳定的本地出口。日常调试保持它随开机自启换设备时记住重新走一遍注册流程即可。【免费下载链接】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），仅供参考