关于 troubleshoot-ngrok
troubleshoot-ngrok 是诊断 ngrok 端点或 Agent 故障的技能,按错误代码查阅对应文档,再检查实时状态以定位原因。适用于使用 ngrok MCP 服务、Shell 或本地检查器排查问题的场景。
主要功能
- 01从错误页面或输出获取错误代码
- 02查阅错误代码对应的文档
- 03检查端点、Agent 和流量状态
- 04验证 Traffic Policy
- 05依据症状排查无错误代码的问题
- 06重发失败请求确认修复
适用场景
- 01诊断端点离线或上游连接失败
- 02检查 Agent 连接状态与版本
- 03定位某次请求失败的原因
- 04排查策略未生效或 TLS 错误
MCP 相关
通过 ngrok MCP 服务调用错误文档、端点、Agent、流量检查器、连接、账户限制和策略验证工具。未连接时,可改用 Agent 输出、本地检查器和控制面板。
安装
复制下面的命令,在终端中运行。
npx skills add https:/ / github.com/ ngrok/ skills --skill troubleshoot-ngrok安装后在 Claude Code 中输入/troubleshoot-ngrok确认已加载。
详细介绍
排查 ngrok 问题
通过三个步骤诊断无法正常工作的 ngrok 端点或 Agent:获取错误,阅读对应的文档页面,然后检查实时状态以确定适用的原因。
1. 获取错误
ngrok 错误包含 ERR_NGROK_<code> 代码。它会显示在浏览器的错误页面、Agent 输出、API 响应和流量检查器中。有些代码是数字(ERR_NGROK_8012),有些是名称(ERR_NGROK_AGENT_NOT_FOUND)。
获取代码。如果用户只有错误消息,请保留其原文和具体值。如果完全没有错误,请转到按症状排查。
2. 阅读错误对应的文档页面
每个代码都有一个页面,介绍其原因和解决方法。不要凭记忆解释代码:错误代码各不相同,近似猜测可能会误导用户。
- 使用 ngrok MCP 服务的
docs_get_error: 使用code调用;如果没有代码,则使用message调用。如果它针对一条消息返回多个代码,请向用户询问代码。不要自行选择。 - 其他情况: 如果只有错误消息,请从错误页面或 Agent 输出中获取代码,或者向用户询问;不要根据消息猜测代码。获取代码后,访问
https://ngrok.com/docs/errors/err_ngrok_<code>.md,将代码转换为小写,并去掉ERR_NGROK_前缀。例如,ERR_NGROK_8012对应err_ngrok_8012.md。如果返回 404,说明代码有误;请与用户核实。
docs_search 无法找到错误页面。不要用它查询错误代码。
3. 确定适用的原因
错误页面会列出所有可能的原因。检查账户以确定适用的原因,而不是让用户逐一排查。
使用 ngrok MCP 服务时:
| 问题 | 工具 |
|---|---|
| 有没有服务正在提供此 URL? | 使用 URL 调用 get_resource。gw_list_endpoints 会显示账户提供的服务;URL 相差一点点是常见原因。 |
| Agent 是否已连接?其版本是否为最新? | gw_list_agents:可查看已连接的 Agent、版本及任何弃用期限。 |
| 这一个请求发生了什么? | 使用 ngrok 错误页面中的请求 ID 调用 gw_get_traffic_inspector_request。 |
| 哪些请求失败了? | gw_query_traffic_inspector:每一行都包含 ngrok 错误代码。可按主机、状态或路径筛选。 |
| TCP 或 TLS 端点故障 | gw_query_connections(可按错误代码筛选),然后调用 gw_get_connection。 |
| 账户是否达到限制? | platform_get_enforced_limits。platform_get_usage 报告的是用量,而不是上限。 |
| 流量策略是否有效? | gw_validate_traffic_policy 会报告每个问题所在的行和列。 |
不使用该服务时,请查看 Agent 自身的输出(ngrok http <port> --log stdout)、本地检查器 http://localhost:4040 和控制面板。
然后按照页面上的说明修复问题,并重新发送失败的请求以确认。
最常见错误代码的说明
完整的修复方法请参阅文档页面。以下说明补充了页面未提及的信息。
- ERR_NGROK_3200(端点离线)。 没有服务正在提供所访问的 URL。请检查两件事:Agent 是否已连接?它提供的是否与该 URL 完全一致?子域名不同或输入错误都会导致同样的错误。访问者报告 3200 错误时,所有者的 Agent 通常已停止运行。访问者可能无能为力。
- ERR_NGROK_8012(上游连接失败)。 ngrok 正常工作,但本地服务没有响应。请确认服务运行在 Agent 转发到的端口和协议上(
http与https、localhost与127.0.0.1或容器地址)。 - 身份验证错误(例如 ERR_NGROK_4018)。凭证缺失或无效。请先确认使用的是哪种凭证:Agent 使用 authtoken,API 和 IaC 使用 API 密钥。请转交给
ngrok-setup。 - 会话限制(例如 ERR_NGROK_108)。同一账户下已有另一个 Agent 连接。
gw_list_agents会显示它的运行位置。
按症状分类(无错误)
- 在 localhost 上运行正常,通过 ngrok URL 访问时返回 400 或被拒绝。 应用或开发服务器拒绝了 ngrok
Host标头。请参阅expose-localhost/references/TROUBLESHOOTING.md。对于内部端点,使用--host-header=rewrite(参见run-mcp-gateway)。 - Agent 启动后立即退出。 可能是凭据问题(参见
ngrok-setup),也可能是配置文件无法解析。运行ngrok config check。 - 流量策略没有生效。 该策略未关联到当前访问的端点,或者较早的规则终止了规则链。请在用户使用的界面上确认关联情况(参见
ngrok-surfaces)。规则顺序请参阅ngrok-engine。 - ngrok 域名出现 TLS 或证书错误。 首先查看 status.ngrok.com 是否有服务事件。如果没有,可能是用户的网络中有设备或软件正在拦截 TLS:ISP 过滤器、VPN,或受管理设备上的终端安全软件。请用户尝试切换网络,并使用
openssl s_client -connect <host>:443 -servername <host>对比证书颁发者。
给 Agent 的说明
- 如果你可以使用 MCP 服务或 shell,请自行运行检查。告知用户原因和解决方法,而不是列出需要检查的事项。
- 依据代码进行判断。如果代码明确指出了原因,就不要猜测。
- 如果原因与凭据或策略有关,请转交给
ngrok-setup或ngrok-engine。不要在此处重复其内容。