PLM与工艺管理系统融合的核心技术与应用
2026/9/10 21:49:53
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 浏览器插件测试内网 API、给 REST 请求挂客户端证书时，请求经常发不出去：CORS 拦截、localhost 访问不到、证书无处上传。加一个 Agent 就能解决这类问题——它是跑在你本机的 HTTP 请求中继服务，替浏览器把受限的请求转出去。
插件为什么发不出请求
浏览器有安全边界，这是设计如此。Hoppscotch 的 REST 请求从插件页面发出时，会遇到这些拦路的情况：
- 跨域请求：目标 API 没返回 CORS 响应头，浏览器直接掐断响应。
- 自定义 HTTP 头：部分头部被浏览器锁定，插件想改也改不了。
- 客户端证书：浏览器不提供在单个请求上挂证书的能力，双向 TLS 直接做不了。
- 内网与 localhost：网页无法访问本机地址和内部网络，本地起的服务连不上。
Agent 是怎么绕开限制的
思路很直接：让请求不在浏览器里发。Agent 是运行在本地的 HTTP 请求中继服务，默认监听 9119 端口，装在系统托盘里。插件把请求发到 localhost:9119，由 Agent 替你转发给目标 API——跨域、受限头部、证书挂载这些限制统统由本地进程接手。通道是加密的，且只接受配对过的设备：在 Hoppscotch Web 端把 Agent 设为拦截器，再用 Agent 窗口显示的 6 位验证码完成注册即可。
三步跑起来
安装并启动 Agent
- 从官方发布页下载与系统匹配的 Agent 安装包。
- 双击运行安装程序，按向导完成安装。
- 安装结束后 Agent 自动启动，系统托盘里能看到 Hoppscotch 图标。
完成注册配对
- 打开 Hoppscotch Web 应用，进入 Settings → Interceptors，选择 Agent。
- 点击 Register Agent，Agent 窗口会显示一个 6 位验证码。
- 把验证码填入页面输入框，点确认建立连接。
- 注册成功后，Agent 会显示一个掩码的认证密钥哈希，表示配对完成。
确认注册生效
- 点开托盘图标，选择"显示注册"。
- 列表里能看到刚配对的 Hoppscotch 实例，就可以正常发请求了。
三种高频场景怎么配
Agent 的配置按域名拆分，全局默认项挂在*域下。
内网 API 与自签名证书
- 在域名选择器里选中内网 API 的域名，没有就先添加。
- 自签名证书场景下，按需关闭"验证主机"和"验证对等体"，并上传自签 CA 证书。
- 需要双向 TLS 时，在客户端证书入口上传证书，.pem 格式要分别传证书和私钥，.pfx 单文件即可。
走代理的 API
- 选中目标域名，打开 Proxy 开关。
- 填入代理地址，例如
http://proxy.example.com:8080。 - 代理需要认证时，补上用户名和密码。
按域名差异化配置
- 全局设置放在
*域，是所有域名的兜底。 - 某个域名需要不同的证书或代理时，单独添加该域名，覆盖项优先生效。
- 域名可在域名管理弹窗里增删，全局
*不能删除。
出问题了对着这张表查
| 现象 | 常见原因 | 处理方法 |
|---|---|---|
| 提示"Agent 未检测到" | Agent 没在运行 | 看托盘有没有 Hoppscotch 图标；若弹窗挡住拦截器切换，先停掉 Agent 再重启浏览器去改设置 |
| 配对时连不上 | 9119 端口被防火墙拦截 | 在系统防火墙放行 Agent，确认 9119 可达 |
| macOS 的 Safari 无法配对 | Safari 的访问控制限制 localhost:9119 | 换 Chrome 或 Firefox 完成注册 |
| 卡在验证码输入 | Agent 窗口未聚焦或 OTP 过期 | 把 Agent 窗口切到前台确认 6 位码；码过期就重新发起注册 |
| 证书校验失败 | 证书过期、私钥不匹配或域名不对 | 核对有效期与密钥对，确认配置的域名和目标 API 主机名一致 |
进阶：配置放哪、怎么重置
Agent 的配置存在平台特定目录：
- Windows：
%APPDATA%\io.hoppscotch.agent\ - macOS：
~/Library/Application Support/io.hoppscotch.agent/ - Linux：
~/.config/io.hoppscotch.agent/
配置乱了想重来，最轻量的做法是点托盘图标选"清除注册"，移除所有已配对的实例，再回 Web 端重新走一遍配对。更彻底的方式是直接删掉对应配置目录。细节实现可以看 Agent 源码。
Agent 在运行、注册已生效、9119 端口可达，插件端的请求失败问题基本就排完了。如果还卡住，先查托盘状态，再逐个核对目标域名的证书与代理设置，问题大多藏在这几处。
【免费下载链接】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），仅供参考