企业官网建设流程全解析

🤖 用clawk为编码 Agent 启动一次性 Linux VM 沙箱后，开发服务器跑在 guest 里，浏览器却开在宿主机上——中间隔着虚拟网络边界，端口该怎么通？这份 clawk 端口转发指南带你用forward add和forward add-reverse两条命令，双向打通宿主机与沙箱，让开发服务器秒开即用，还能把宿主机本地服务反向暴露给 guest。

_{clawk 启动沙箱后的工作场景：沙箱里的 Agent 在干活，网络访问受允许列表保护}

clawk 把整个虚拟机隔离得严严实实：出站流量默认全部拒绝，只有你显式放行的目的地才能访问。这种安全模型带来一个现实问题——guest 里起的开发服务器，宿主机默认连不上；反过来，绑定在宿主机127.0.0.1的服务（IDE WebSocket、本地 API mock、数据库），guest 也摸不到。

好消息是：clawk 内置了双向端口转发，一条命令一个方向，无需配置 iptables、无需 sudo、不需要改 Docker 网络。本文按「原理 → 出站转发 → 反向转发 → 声明式配置 → 排查」的顺序讲透。

🔄 先搞清楚：两种转发方向的区别

clawk 的端口转发分两个方向，命令前缀不同，生效时机也不同：

一个容易混淆的点是 guest 里的127.0.0.1：它是 guest 自己的回环地址，不是你宿主机的回环。所以想让 guest 访问宿主机上绑定127.0.0.1的服务，光加network allow是没用的——这正是反向转发存在的理由。

💡 两个方向共用同一套端口规范：宿主机端口在前（HOST:GUEST），只有「谁来拨号」这件事不同。

📤 一键暴露：forward add 把 guest 开发服务器搬到宿主机

最典型的场景：Agent 在沙箱里起了一个 Web 服务（Next.js、FastAPI、Vite……），你想在自己 Mac 的浏览器里打开它。

基本用法

clawk forward add my-project 3000

这条命令把宿主机的localhost:3000绑定到 guest 的 3000 端口。之后宿主机上curl localhost:3000就能拿到 guest 开发服务器的响应了。

端口映射：HOST:GUEST 双端口写法

端口规范支持两种格式（解析逻辑见 forward.go 中的parsePortSpec）：

两侧端口可以不同——比如 guest 里跑着一个标准 80 端口的 HTTP 服务，宿主机端口 80 被占了，就写8080:80。

一条命令可以带多个端口规范：

clawk forward add my-project 3000 8080:80 5432:5432

⚠️ 两个必须知道的坑

1. guest 里的服务要绑定0.0.0.0，别绑127.0.0.1。转发的流量是从 guest 网络接口进来的，回环接口对宿主机不可见。如果你的开发服务器默认只监听 loopback，记得显式加--host 0.0.0.0（Next.js、Vite、FastAPI 都支持）。

2. 出站转发在下次启动时生效。forward add写入的是沙箱配置，属于 VM 启动时固化的绑定。如果沙箱正在运行，执行clawk down && clawk up即可应用；若忘记重启，命令本身会提示(restart sandbox for new forwards to take effect)。

验证与清理

查看转发是否配好，clawk status会把Forwards行直接打印出来：

clawk status my-project

需要脚本化读取时，forward list只提供 JSON 模式：

clawk forward list my-project --json

用不上了就移除（支持简写rm）：

clawk forward remove my-project 3000

📥 反向转发：forward add-reverse 让 guest 摸到宿主机本地服务

反向转发解决的是「反向」问题：宿主机上绑定127.0.0.1的服务（JetBrains/VS Code 插件的 IDE WebSocket、本地 API mock、loopback 数据库），如何被 guest 访问？

clawk forward add-reverse my-project 63342

之后 guest 里访问127.0.0.1:63342，流量就会经 vsock 隧道回到宿主机的127.0.0.1:63342——同样的端口号，同一个地址，这正是那些「假设共享回环」的工具最舒服的工作方式。

端口规范同样是宿主机在前：

clawk forward add-reverse my-project 5432:15432 # 含义：guest 127.0.0.1:15432 → 宿主机 127.0.0.1:5432

与出站转发的两点关键差异

1. 立即生效，无需重启。反向转发由守护进程通过 vsock 隧道实时推送给运行中的 guest，执行完命令马上可用；沙箱没运行时会自动提示「下次 up 时生效」。
2. 最小暴露面。guest 只能访问你列出的端口——它报一个没配置的端口，宿主机直接拒绝。所以这条路只开了你申请的那几个洞，而不是整个宿主机回环。

实战：打通 Claude Code 的 IDE 插件

这是反向转发最经典的使用场景。JetBrains 和 VS Code 的 Claude Code 插件会在宿主机回环上起一个 WebSocket 服务，并把端口写进~/.claude/ide/<port>.lock锁文件。沙箱里的claude要连上它，需要两样东西：

# 1. 把宿主机的锁文件目录共享进 guest（clawk.mod 里声明） # shares ( # ~/.claude/ide /home/agent/.claude/ide ro # ) # 2. 反向转发锁文件里记录的端口 ls ~/.claude/ide # 看到 63342.lock clawk forward add-reverse my-project 63342

然后在沙箱内执行/ide，就像在宿主机上一样连上了。IDE 重启后端口会变——由于反向转发实时生效，直接对新端口再跑一次add-reverse就行，沙箱不用重启。

移除反向转发：

clawk forward remove-reverse my-project 63342

注意：反向转发仅 macOS (vz) 可用

firecracker（Linux 实验性 provider）的 vsock 是单向的（guest 监听、host 拨号），guest 没有回连通道，所以反向转发只在 vz（macOS）上支持。在 Linux 上执行时 CLI 会明确告知，而不是静默失败。

📝 声明式配置：在 clawk.mod 里写 forwards 块

如果你不想每次启动后手敲转发命令，可以在项目的 clawk.mod 里声明，随沙箱创建自动应用：

forwards ( 3000 5432:5432 reverse 63342 # 宿主机 localhost:63342，暴露给 guest )

带reverse前缀的条目就是反向转发，端口写法与 CLI 完全一致（宿主机在前）。这样新建沙箱时转发就已经就绪，团队其他成员拉下项目也能得到相同的网络配置。

完整的forwards块参考见 docs/configuration.md，网络模型全貌见 docs/networking.md。

🔍 端口转发排查清单

配置了却连不通？按这个顺序检查：

别忘了：空闲停机会让转发消失

clawk 有个省电机制：沙箱空闲 30 分钟会自动停机（idle stop），停机后所有出站端口转发随之消失，直到下次启动。如果你的沙箱需要长期对外提供开发服务器，在clawk.mod里关掉这个限制：

vm ( idle_timeout off )

🎯 快速参考卡

总结

clawk 的端口转发把「安全隔离」和「开发便利」这两件看似矛盾的事解耦了：

• 出站方向（forward add）：一条命令把 guest 开发服务器挂到宿主机 localhost，HOST:GUEST写法灵活映射端口；
• 反向方向（forward add-reverse）：让 guest 里的工具按原地址访问宿主机本地服务，实时生效、只开最小端口面；
• 声明式（clawk.mod的forwards块）：转发随项目走，团队成员开箱即得。

无需 Docker 网络、无需 iptables、无需 sudo——这正是 clawk 把网络过滤做在用户态、把转发做成 CLI 动词的回报：双向打通，快得不像话。更多网络细节（允许列表、命名策略）见 docs/networking.md，完整命令参考见 docs/commands.md。