如何用 Hoppscotch Agent 配置 mTLS 客户端证书PEM 与 PFX访问需要双向认证的 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当目标 API 要求双向认证mutual TLS即 mTLS时TLS 握手阶段服务器会要求客户端出示证书。浏览器直接发出的请求无法附加客户端证书这类请求通常无法到达接口本身。Hoppscotch Agent 是一个基于 Tauri V2 的跨平台 HTTP 请求中继它作为本地系统服务运行在端口9119位于 Hoppscotch web 应用与目标 API 之间注册后 Hoppscotch 发出的所有 HTTP 请求都由 agent 代为处理。Agent 支持按域名配置 mTLS 客户端证书支持.pem与.pfx/.pkcs12两种格式还提供自定义 CA 证书和 SSL/TLS 校验开关。Agent 底层的 hoppscotch-relay 请求库使用带静态 OpenSSL 构建的 curl-rust 分支以在不同平台上保持一致的 SSL/TLS 行为并原生支持 PEM 与 PFX/PKCS#12 客户端证书认证。本文的操作路径是安装并注册 Agent → 准备客户端证书文件 → 在 Hoppscotch 的目标域名下上传客户端证书 → 按文档给出的证书检查清单确认配置生效。一、准备条件安装 Agent 并确认系统环境Agent 提供两种分发方式详见 Agent README标准版从官方 release 页面下载最新版本运行安装程序并按向导完成安装。agent 会自动启动并出现在系统托盘。便携版解压后直接运行可执行文件无需安装它不包含自动更新和自动启动重启系统后需要手动启动。便携版使用独立配置tauri.portable.conf.json禁用了打包与更新器功能。文档给出的最低系统要求平台系统版本架构依赖WindowsWindows 10 1803 或 Windows 11x64WebView2 Runtime标准版安装时自动安装macOSmacOS 10.15 (Catalina) 或更高Intel x64 或 Apple Silicon (ARM64)无额外说明Linux—x64WebKit2GTK 2.44.0通常已预装GLIBC 2.38另外端口9119不能被防火墙拦截否则 Hoppscotch web 应用无法与 agent 建立通信。二、注册 Agent配置证书的前提在配置任何证书之前必须先完成 agent 注册否则 Hoppscotch 的请求不会走 agent 通道。注册步骤在 Hoppscotch web 应用中打开Settings→Interceptors在可用拦截器中选择Agent点击Register Agent按钮agent 窗口会显示一个 6 位验证码将验证码输入 OTP 输入框点击确认按钮建立连接。成功判定注册成功后agent 窗口会显示一个经过掩码处理的 auth key hash。文档说明 agent 与 web 应用之间的通道使用 AES-256-GCM 加密、X25519 密钥交换注册本身是一次性 6 位 OTP 校验。如果注册卡住文档给出的检查项出现Agent not detected提示确认 agent 是否在运行检查系统托盘中的 Hoppscotch 图标如果该提示阻止了切换拦截器重启浏览器并先停止 agent 再修改拦截器设置确认浏览器能访问localhost:9119/handshake且端口9119未被防火墙拦截出现Failed to initiate the registration可能由浏览器安全策略或扩展冲突导致OTP 输入框缺失确认 agent 窗口处于聚焦状态且正在显示 6 位验证码验证码有有效期过期后需重新发起注册macOS 上 Safari 可能因 CORS 限制无法访问localhost:9119改用 Chrome/Firefox 注册自托管self-hosted环境下确认 Agent 版本与所用 Hoppscotch web 应用版本匹配否则可能出现不兼容。三、准备客户端证书文件Agent 支持的客户端证书格式与所需文件格式所需文件说明PEM证书文件.crt/.cer/.pem 私钥文件.key/.pem两个文件分别上传PFX / PKCS#12单个.pfx/.pkcs12文件如证书带密码保护需要输入密码提前确认手上的证书属于上述格式、私钥与证书配对PEM 场景并记下 PFX 文件的密码——这些都是文档证书排查清单中的核对项。四、在目标域名下配置客户端证书配置入口在 Hoppscotch web 应用内步骤如下进入Settings→Interceptors→Agent在域名选择器中选择目标域名。Agent 按域名管理配置域名*是应用到所有域名的全局默认配置单个域名例如api.example.com可以有自己的覆盖配置新域名通过域名管理弹窗添加自定义域名可以删除但全局默认域名*不能删除点击Client Certificates按钮选择证书格式标签页PEM 或 PFX上传证书文件PEM 标签页分别上传证书文件和私钥文件PFX 标签页上传.pfx/.pkcs12文件如有需要输入密码配置会自动按域名保存无需额外保存操作。一个容易忽略的点域名配置必须与目标 API 的主机名匹配。如果证书配在*或api.example.com而请求实际发往另一个主机名客户端证书不会按预期生效——这是文档证书排查清单中明确列出的一项。五、API 服务器使用私有 CA 时配置 CA 证书可选分支如果 mTLS 端点的服务器证书由私有 CA 签发客户端还需信任该 CA否则即便客户端证书正确握手仍会失败。文档给出的 CA 证书配置流程同样按域名进入目标域名的 CA Certificates 区域点击Add Certificate File上传 CA 证书文件用开关控制该证书的启用/停用inclusion on/off用垃圾桶图标删除不再需要的证书。同一域名的 SSL/TLS 安全设置中还有两个开关文档的定义是Verify Host启用/禁用 SSL 握手过程中的主机名校验Verify Peer启用/禁用对端证书校验。只有当服务端证书链确实无法通过默认校验例如私有 CA 未加入系统信任时再考虑调整这些开关或补配 CA 证书文档没有建议默认关闭它们。六、验证与排查证书不生效时按文档清单核对文档没有给出 mTLS 成功握手后的固定日志或输出值因此这里的验证以文档实际提供的检查项为准。请求经由 agent 发出后如果证书相关配置没有生效按 Agent README 的Certificate Issues清单逐项核对确认证书格式受支持.pem或.pfx/.pkcs12检查证书有效期.pem场景确认私钥与证书匹配确认域名配置与目标 API 主机名一致.pfx/.pkcs12场景确认证书密码正确检查 CA 证书的 inclusion 开关状态。请求层面的相关检查项Request Processing Issues出现 CORS 错误确认 agent 拦截器处于激活状态、请求确实经由localhost:9119路由怀疑 SSL/TLS 校验问题检查目标域名的 verify host/verify peer 设置自定义头未生效确认 agent 已被选为拦截器文档提示浏览器在部分默认 HTTP 方法下可能覆盖User-Agent等头部。需要更详细的错误信息时查看 agent 日志目录文档建议在其中查找 connection errors、certificate validation failures、proxy authentication issues 三类记录平台日志目录Windows%LOCALAPPDATA%\io.hoppscotch.agent\logs\macOS~/Library/Logs/io.hoppscotch.agent/Linux~/.local/share/io.hoppscotch.agent/logs/配置存储与版本限制按域名的证书配置由 agent 持久化保存各平台的配置目录为Windows%APPDATA%\io.hoppscotch.agent\macOS~/Library/Application Support/io.hoppscotch.agent/Linux~/.config/io.hoppscotch.agent/使用便携版时注意两点限制它没有自动启动系统重启后需手动运行可执行文件也没有自动更新升级需要手动下载新版本。若 agent 在 Linux 上以服务方式启动失败文档提示可以检查 systemd 日志和 GLIBC 版本需 2.38Windows 上若 agent 无法工作检查 WebView2 Runtime 以及 Windows Defender/杀毒软件对 agent 可执行文件的排除设置和 Windows 防火墙的网络权限。【免费下载链接】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），仅供参考