| name | frpctl |
| description | 通过 frpctl CLI 管理 frp 隧道,用于服务暴露和远程访问场景(本地开发服务共享、远程调试、临时公网访问)。当用户说"开个穿透/隧道"、"暴露端口 X"、"把本地 N 端口放出去"、"关掉那个隧道"、"看下现在有哪些穿透"等,激活此 skill。前提:用户已经配置好 frps 服务器信息,不要让用户手写 frp 配置文件。 |
frpctl — frp 隧道管理
工具定位
frpctl 是已装好、配置好 frps 服务器信息的本地 CLI。调用它来开/关/查 frp 隧道，不要：
- 手写 frpc.toml / frps.toml
- 让用户提供 token、服务器 IP（已在
~/.config/frpctl/config.toml）
- 打印或询问 token
- 直接起 frpc 进程（用
frpctl up/down）
常用命令速查
一键开隧道（最常用）
frpctl quick -l 4444
带 TTL 自动过期：
frpctl quick -l 4444 --ttl 4h
按类型创建（没有域名只能用 tcp/udp）：
frpctl quick -l 4444 -t tcp
frpctl quick -l 5353 -t udp
frpctl quick -l 8080 -t http --custom-domains app.example.com
frpctl quick -l 8443 -t https --subdomain myapp
frpctl quick -l 7001 -t stcp --secret-key 'CHANGE_ME'
类型参数规则：
tcp / udp：可选 --remote-port，不支持 --custom-domains、--subdomain、--secret-keyhttp / https：必须设置 --custom-domains 或 --subdomain，frps 需配置 vhostHTTPPort 和域名stcp：必须设置 --secret-key，访问端也需运行 frpc visitor
显式定义隧道（长期保留）
frpctl tunnel add dbshell -l 5432 -t tcp
frpctl tunnel add dns -l 5353 -t udp
frpctl tunnel add web -l 8080 -t http --custom-domains app.example.com
frpctl tunnel add internal -l 7001 -t stcp --secret-key 'CHANGE_ME'
frpctl up
状态查询
frpctl tunnel list
frpctl tunnel url <name>
frpctl status
frpctl logs -f
关闭
frpctl tunnel rm <name>
frpctl down
服务器管理（一般不需要动）
frpctl server list
frpctl server use <name>
只在用户明确说"加一台新 VPS"时才用 server add。
触发模式 → 命令映射
| 用户说 | 执行 |
|---|
| "开个穿透到 4444" / "暴露 4444" / "给我一个公网端口" | frpctl quick -l 4444 |
| "开个 UDP 穿透到 5353" | frpctl quick -l 5353 -t udp |
| "把本地 8080 通过域名放出去" | frpctl quick -l 8080 -t http --custom-domains <domain> |
| "给我 https 子域名入口" | frpctl quick -l 8443 -t https --subdomain <name> |
| "开 stcp 内网通道" | frpctl quick -l <port> -t stcp --secret-key <key> |
| "现在有哪些隧道" / "看下状态" | frpctl tunnel list |
| "告诉我 x 的公网地址" | frpctl tunnel url x |
| "关掉 x" / "删掉 x" | frpctl tunnel rm x |
| "全部关掉" / "收工" | frpctl down |
| "重启一下" | frpctl down && frpctl up |
| "看 frpc 日志" / "有没有连上" | frpctl logs |
给用户公网地址时的完整交互模板
当用户说类似"给我一个公网地址访问本地服务"：
- 先跑 quick（没有域名默认用 tcp）：
frpctl quick -l <port> --ttl 2h
- 从输出里提取
public: 字段
- 直接给用户可访问地址：
本地服务：localhost:<local_port>
公网入口：14.1.99.251:<remote_port>
- 提醒 TTL 到期自动回收，或用
frpctl tunnel rm <name> 手动关
不要做的事
- 不要打印或回显 token：
auth.token 是敏感信息
- 不要手写 frpc.toml：运行时自动生成在
~/.cache/frpctl/frpc.toml
- 不要用 sudo 跑 frpctl：以当前用户身份运行即可
- 不要推荐低位端口（<1024）：端口池默认 20000-20100
- 没有域名时不要创建 http/https 隧道：会连接失败，用 tcp 代替
故障排查
| 症状 | 处理 |
|---|
connect to server error: EOF | frps 关闭了 tcpMux，需在 ~/.config/frpctl/config.toml 对应服务器下加 tcp_mux = false |
frpc binary not found | 让用户装 frpc 或设 FRPCTL_FRPC=/path/to/frpc |
port pool exhausted | frpctl tunnel list 看僵尸隧道，批量 rm |
tunnels span multiple servers | 用 frpctl up <name> 指定单个隧道启动 |
| 公网连不上 | frpctl logs 看日志；检查 VPS 防火墙是否放行端口池 |
| http 隧道无法访问 | frps 需配置 vhostHTTPPort 和 subdomainHost，没有域名请改用 tcp |
