OpenClaw portal 工具实战:把本地服务一键变成可分享的实时预览

背景

写代码、调接口、做原型时，经常需要把本地跑起来的服务给别人看一眼。传统做法是改 nginx、申请域名、配 HTTPS，麻烦且慢。OpenClaw 的 portal 工具就是为这个场景存在的：它会在 Gateway 上开一个反向代理 tunnel，把本地某个端口的服务直接暴露到 Control UI 的实时面板里，外部通过 Gateway 返回的 URL 就能访问，无需自己配域名或公网。

本文基于真实可用的 portal 工具能力，演示从零跑通一个本地服务并拿到可访问链接的完整流程。

portal 工具能做什么

portal 的核心动作只有几个：

| 动作 | 作用 |

|------|------|

| open | 用一个本地端口开一个 portal，返回可访问的 URL |

| list | 列出当前所有已开的 portal |

| close | 关闭指定 portal（按 id） |

关键点：

• 代理 HTTP 与 WebSocket
  ：所以带热更新的前端 dev server（如 Vite、webpack-dev-server）也能正常用，HMR 不会因为代理断掉。

• 返回重试页
  ：端口还没监听时，访问 URL 会看到重试页，等服务起来自动正常。

• 生命周期跟随 Gateway
  ：Gateway 重启后 portal 失效，需要重新 open。

实操：三步跑通一个实时预览

第一步：准备一个本地服务

用一个最小例子，Python 内置 HTTP 服务器即可：

# 在某个目录起一个静态服务，监听 8080
cd /tmp/demo-site
python3 -m http.server 8080

如果是前端项目，常见的是：

npm run dev   # Vite 默认监听 5173

只要本地端口在监听，portal 就能接管。

第二步：用 portal 开隧道

调用 portal 工具的 open 动作，传入端口和路径：

{
  "action": "open",
  "port": 8080,
  "path": "/",
  "title": "我的演示站点"
}

工具返回的 JSON 里会带一个 url 字段，类似：

https://gateway.example.com/portal/<随机id>/

这个 URL 就是外部可访问地址。把它发给协作者，对方在浏览器打开即可，不需要你有公网 IP 或域名。

路径 path 默认 /，如果你的服务挂在子路径下（例如 /app），填对应值即可。

第三步：确认与关闭

打开后随时查状态：

{ "action": "list" }

演示结束、或 Gateway 要重启前，记得关掉，避免端口一直暴露：

{ "action": "close", "id": "<上一步返回的 portal id>" }

实战注意点（踩过的坑）

1. 端口必须真的在监听

open 之后如果本地服务没起来，URL 会一直显示重试页。正确顺序：先起服务，再 open，或接受重试页等服务就绪。

1. WebSocket 类应用要用对 target

默认 target 是 host（本机）。如果你的服务跑在 node 沙箱或独立容器里，需要指定对应 node 或 target，否则代理找不到端口。

1. Gateway 重启即失效

portal 不是持久化资源，Gateway 进程重启后所有 portal 清空。需要长期固定入口请走正式的子域名反代部署，别依赖 portal 做生产。

1. 不要拿它暴露敏感服务

portal 链接一旦发出去，任何拿到 URL 的人都能访问。只用于演示/临时协作，别把含密钥的管理后台随便开出去。

适合用 portal 的场景

• 给远程协作者看一个正在调的前端页面 / 接口联调结果

• 临时演示一个本地原型，不想走完整部署流程

• 在 Control UI 里把某个 dashbaord / 小工具直接挂出来看实时效果

不适合用 portal 的场景

• 长期对外服务：用正式的子域名 HTTPS 反代（见 subdomain-service-deploy 思路）

• 需要鉴权、需要固定域名、需要被搜索引擎收录

小结

portal 是 OpenClaw 里一个被严重低估的小工具：一行 open 把本地端口变成可分享链接，省掉域名、证书、nginx 一整套。记住三件事——先起服务再开、用完就关、别暴露敏感服务，它就非常好用。

关注公众号，获取更多 OpenClaw 实操技巧