浏览器插件 REST 请求发不出去？Hoppscotch Agent 连接实操手册与 API 测试自查清单

浏览器插件 REST 请求发不出去Hoppscotch Agent 连接实操手册与 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/hoppscotchHoppscotch 是开源的 API 开发与测试平台在浏览器里发 REST 请求时经常会碰到请求发送失败跨域报错、localhost 服务够不着、客户端证书无处配置。Hoppscotch Agent 就是为此准备的本地请求中继程序它跑在你自己的电脑上默认监听 9119 端口替浏览器完成实际的网络请求。这篇实操手册从现象出发讲清楚什么情况下需要它、怎么连上、怎么按域名配置最后用一张自查清单收尾。先看现象Agent 管哪种请求发不出去典型的场景有这么几类请求打到自家接口浏览器控制台直接报 CORS 跨域错误想测 127.0.0.1 或内网地址页面里的请求根本到不了API 要求双向 TLS 客户端证书而浏览器干脆不提供这种选项。这些问题的共同点是限制来自浏览器的安全策略而不是请求本身写错了。Agent 把真正发包的动作挪到本地机器完成浏览器只和 localhost 打交道。先用这张表判断自己要不要装你的情况是否需要 Agent普通公网 API 测试没有跨域问题不需要浏览器直连即可目标 API 报 CORS 错误且后端改不了需要测试 localhost、内网服务需要API 要求客户端证书双向 TLS需要公司网络必须走代理、或要突破浏览器对自定义请求头的限制需要安装并启动 Agent确认 9119 端口在监听Agent 提供两个版本选一个即可版本特点提醒标准版带安装程序支持开机自启和自动更新日常使用推荐便携版解压即用无需安装不自启、不自动更新且使用独立的配置文件安装完成后 Agent 会自动启动并驻留系统托盘看到 Hoppscotch 的托盘图标就说明它在运行。如果浏览器提示Agent not detected优先检查两件事托盘里有没有图标、9119 端口是否被防火墙拦住了。更多安装细节可参考 packages/hoppscotch-agent/README.md。Agent 配置文件和日志放在哪排查问题或想重置 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 注册用 6 位验证码建立加密通道Agent 启动后并不会和浏览器自动配对需要走一次性的 OTP 注册流程打开 Hoppscotch 网页进入 Settings → Interceptors拦截器在拦截器列表中选择 Agent点击 Register Agent 按钮发起注册Agent 窗口中会弹出一个 6 位验证码把验证码填进浏览器里的 OTP 输入框并确认成功后Agent 窗口显示一段掩码处理的认证密钥哈希代表连接已建立⚠️ 三个容易踩的坑验证码有时效过期就回到第 3 步重来浏览器报Failed to initiate the registration多半是浏览器安全策略或扩展插件冲突可先禁用新装的扩展或换浏览器试macOS 上 Safari 对 localhost:9119 有访问控制限制注册建议改用 Chrome 或 Firefox。自建部署的用户还要注意 Agent 版本与 Hoppscotch Web 应用的版本匹配。按域名配置证书和代理只对你测的那台 API 生效连接建立后拦截器面板支持按域名做配置Agent 有一组全局默认设置域名显示为*你可以为某个具体域名如 api.example.com添加独立覆盖项其余域名继续走全局默认。常用配置如下配置项作用适用场景Verify Host / Verify Peer控制 SSL 握手时是否校验主机名、是否校验对端证书内部 CA 签发、证书即将过期的环境CA 证书为该域名添加自定义证书颁发机构API 使用内网自签 CA客户端证书配置双向 TLS支持 PEM证书与私钥分两个文件和 PFX单文件、可带密码两种格式API 强制要求客户端证书代理指定 HTTP/HTTPS 代理地址可填用户名密码做认证含 NTLM公司网络只能通过代理出网操作顺序固定先选中目标域名再打开对应开关、填好参数每个域名的设置独立保存。代理地址记得带上 http:// 或 https:// 前缀。请求还是发不出去时按症状自查症状常见原因自查动作弹出Agent not detectedAgent 未运行或 9119 被防火墙拦截看托盘图标是否在临时放行防火墙再试拦截器切不动弹窗卡住旧连接状态阻塞切换重启浏览器先停止 Agent 再改拦截器设置验证码填了却确认失败验证码过期或浏览器连不上握手端点重新发起注册确认没有代理劫持 localhost 流量仍然报 CORS 错误拦截器还停留在浏览器直连确认 Settings 里拦截器已切到 Agent证书校验失败格式不支持、证书过期、私钥不匹配核对 PEM/PFX 格式、有效期、密钥与证书是否成对走了代理但无响应代理地址写错检查 URL 是否含协议前缀、认证信息是否正确需要更细的线索时去上面的日志目录里翻 Agent 日志重点找连接错误、证书校验失败和代理认证失败这几类记录。收尾验证连接自查清单✅ 系统托盘里有 Hoppscotch 图标防火墙未拦截 9119 端口✅ 网页端 Settings 中的拦截器已选为 Agent✅ Agent 窗口显示掩码认证密钥哈希注册成功✅ 对之前失败的 API 发一个测试请求能拿到正常状态码✅ 用的是标准版的话系统重启后它会自启无需手动拉起这五项全部对上浏览器插件 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），仅供参考