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/hoppscotch你在 Hoppscotch 里发送 REST 请求浏览器却报了 CORS 错误或者自定义头、客户端证书怎么也带上不去这不是你的请求写得有问题而是浏览器自身的安全限制。Hoppscotch 为此提供了 Hoppscotch Agent一个运行在本地的 HTTP 请求中继服务默认监听 9119 端口把受限请求转到本地转发。这篇文章带你从零装好 Agent、完成注册并给出一份请求失败时的排查清单。浏览器为什么发不出这个 REST 请求Agent 解决的是这类典型故障跨域被浏览器拦截、User-Agent等受保护的头无法修改、需要双向 TLS 的接口、走公司代理才能访问的接口。浏览器里这些能力被锁死而本地程序不受同样限制。Agent 的做法是充当中间人Hoppscotch Web 应用把请求交给localhost:9119由 Agent 代表浏览器发出再把响应带回来。通信链路用 X25519 密钥交换加 AES-256-GCM 加密建立服务端逻辑在 hoppscotch-agent 的 Rust 实现 里可以看到其中 握手路由 定义了/handshake注册端点。对前端来说它只是拦截器选项里的一个名字实现见 内核拦截器服务。如何安装并启动 Hoppscotch Agent从官方发布页下载对应系统的安装包运行安装程序按向导完成安装完成后 Agent 自动启动系统托盘出现 Hoppscotch 图标托盘菜单可以显示注册清除注册最大化窗口或退出不想起安装器的话有免安装的便携版解压后直接运行可执行文件即可。区别是便携版不会开机自启也不会自动更新。装完先用命令确认端口通不通curl http://localhost:9119有响应就说明 Agent 在 9119 端口正常工作。如何完成 Agent 的 OTP 注册注册建立浏览器与 Agent 之间的加密通道只需一次流程很短打开 Hoppscotch Web 应用进入 Settings → Interceptors选择Agent拦截器点击Register AgentAgent 窗口弹出 6 位验证码把它填进页面的 OTP 输入框点击确认注册成功时 Agent 窗口显示掩码后的认证密钥哈希验证码有有效期输慢了就重新点一次注册即可。注册成功后你在 Web 应用里发出的所有请求都会自动走 Agent 转发。如何按域名配置证书与代理Agent 支持按域名覆盖配置*表示全局默认值再为特定域名如api.example.com单独设其余沿用默认。SSL/TLS 设置每个域名可独立开关验证主机和验证对等体适合内网自签名证书的场景CA 证书为目标域名上传自定义 CA可单独开启或关闭客户端证书支持 PEM证书和私钥两个文件和 PFX/PKCS12单文件加密码两种格式用于双向 TLS代理打开域名的代理开关填入形如http://proxy.example.com:8080的地址需要认证时再填账号密码所有配置按域名自动保存位置在各平台的io.hoppscotch.agent配置目录下Windows 在%APPDATA%macOS 在~/Library/Application SupportLinux 在~/.config。Agent 报错排查清单请求失败怎么定位现象先查什么弹窗提示 Agent not detected托盘里有没有 Agent 图标防火墙是否放行 9119 端口提示 Failed to initiate the registration换 Chrome 或 Firefox 再试macOS 上 Safari 对 localhost:9119 有访问控制问题看不到 OTP 输入框Agent 窗口没有聚焦显示验证码点一下窗口验证码输完没反应代码已过期重新发起注册自定义头没生效确认当前拦截器选的是 Agent 而非浏览器默认证书类错误核对格式.pem / .pfx、有效期、私钥是否匹配证书、PFX 密码以上都正常仍失败看日志Windows 在%LOCALAPPDATA%\io.hoppscotch.agent\logs\macOS 在~/Library/Logs/io.hoppscotch.agent/Linux 在~/.local/share/io.hoppscotch.agent/logs/还有一个容易忽略的点自托管 Hoppscotch 时Agent 版本要和 Web 端版本配套版本错配也会导致握手失败。下一步REST 请求发不出去多半是浏览器在挡路而不是网络不通装好 Agent、用 OTP 注册一次、按需配好域名级的证书或代理绝大多数失败都会消失。现在就打开 Settings → Interceptors 看一眼如果那里没有 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考