阿里云函数计算 AgentRun 全新发布后，我们整理了「探秘 AgentRun」系列文章，本系列将梳理企业落地 Agent 常见难题，给出具体解法，助力 Agentic AI 快速走进生产级环境。 欢迎加入「函数计算 AgentRun 客户群」与我们交流，钉钉群号：134570017218。

引言：Vibecoding 的终极形态——“所见即所得”

代码生成的进化

从单纯的代码补全（Copilot），到直接生成可运行的 UI 组件和页面，AI 编程助手正在经历一次体验跃迁：用户不再只看到静态代码，而是 所见即所得——生成即运行、即预览。这种「边写边看」的 Vibecoding 体验，正在成为下一代 AI 编程助手的标配。

背后的工程挑战

大模型只负责「写」，谁来负责「跑」？在云端 安全、快速地执行不受信任的 AI 生成代码，并对外暴露 Web 访问，是构建此类 AI Agent 的核心门槛：

• 多端口需求：一个现代前端项目（如 React、Vue）往往不止占用一个端口——主页面可能在 5173，HMR（热模块替换）需要独立通道，Mock API 可能占用 3000。若只能暴露单一端口，前端开发服务器与预览能力将严重受限。
• 隔离与弹性：代码不可信，必须在隔离沙箱中执行；同时用户希望秒级看到结果，这就要求沙箱具备秒级冷启动与按需扩缩容能力。

AgentRun Sandbox

阿里云函数计算推出的  AgentRun Sandbox，正是为上述场景设计的一站式执行基座： 秒级冷启动、免运维、原生支持公网访问，并在此基础上提供了 多端口动态路由能力——单一入口即可按端口精准转发到沙箱内的任意服务。这使得「生成代码 → 云端运行 → 即时预览」的闭环得以在安全、可控的架构下实现，是构建「在线代码预览」与全栈 Vibecoding 的理想基础设施。

核心特性解析：AgentRun Sandbox 多端口访问模式

为什么前端预览也需要多端口？

运行一个现代前端项目时，往往同时存在多个监听端口：

若沙箱只暴露一个固定端口，上述多服务无法同时被正确访问。 多端口访问模式使平台能够通过 同一入口，根据「目标端口」将请求精准转发到沙箱内对应进程，从而完整支持前端开发服务器与自定义 Web 应用的预览。

双模式详解：按需选择，灵活适配

AgentRun Sandbox 支持两种多端口访问方式，可依据自身网络与域名条件选择。

泛域名模式（Wildcard Domain Mode）

机制：通过子域名区分端口流量。约定格式为：

{目标端口}-{沙箱实例标识}.{您的泛域名}

例如： 5173-abc123.sandbox.example.com 表示访问该沙箱实例内的  5173 端口； 3000-abc123.sandbox.example.com 表示访问同一沙箱内的  3000 端口。

优势：路由语义清晰，完全模拟真实的多子站、多端口场景；前端代码中的 BaseURL、代理配置与本地开发一致，无需为沙箱做特殊适配。

单域名模式（Path-based / Header-based Mode）

机制：仅有一个域名时，通过 HTTP 请求头传递「沙箱 ID」与「目标端口」：

X-Sandbox-ID: {沙箱ID}
X-Sandbox-Port: {目标端口}

例如： X-Sandbox-Port: 5173 表示将本次请求转发到该沙箱实例的 5173 端口。

优势：在无法配置泛域名解析、或存在严格域名白名单的网络环境下，仍可完成多端口访问，兼容性极强。

在 AgentRun 控制台配置 Sandbox 与域名

1. 申请域名并备案：在 DNS 服务商添加 CNAME 记录，将域名指向 AgentRun 网关，地址格式为： {uid}.agentrun-data.cn-hangzhou.aliyuncs.com（其中  {uid} 为阿里云账号 ID）。
2. 创建 Sandbox 域名：在 AgentRun 控制台创建 Sandbox 域名，选择「泛域名模式」或「单域名模式」，并填写对应域名。
3. （可选）启用 HTTPS：上传 SSL 证书以支持 HTTPS 访问。
4. 创建沙箱模板：选择模板类型（如「代码解释器」「浏览器」「AIO 沙箱」等），完成模板创建。
   
5. 创建沙箱：在模板详情中创建沙箱实例，并记录返回的 沙箱 ID。
6. 访问方式：
   • 泛域名模式：使用  https://{port}-{sandboxID}.{domain} 访问沙箱内指定端口。
   • 单域名模式：请求时携带 Header： X-Sandbox-ID: {sandboxID}、 X-Sandbox-Port: {port}，即可访问对应端口。

端口有效范围为  3000–65535（系统保留端口如 5000、5001、3000 等由网关与内置服务使用，不对外作为用户自定义端口暴露）。

OpenClaw 实战——让大模型生成的页面瞬间「上线」

架构设计

一种典型的 Vibecoding 链路是：用户通过某个 Channel（如 IM、钉钉）与  OpenClaw 交互，要求生成程序或 HTML 页面 →  LLM 生成 HTML/JS 或 React 等源码 → 调用  AgentRun Sandbox Skills 在沙箱内执行该程序（如启动 HTTP 服务）→ 依赖 泛域名生成预览 URL → 用户直接点击链接访问运行中的应用。

整体流程可概括为：

用户 → Channel → OpenClaw → LLM 生成代码/HTML
       → AgentRun Sandbox Skill（创建沙箱、执行代码/命令、生成预览 URL）
       → 泛域名返回预览 URL → 用户浏览器访问对应端口

AgentRun 为 OpenClaw 带来云上沙箱能力

agentrun-aio-sandbox-skill 是基于阿里云 AgentRun AIO（All-In-One）沙箱封装的一套 OpenClaw Skill，将沙箱的创建、代码执行、Shell 命令执行、多端口预览域名生成与沙箱销毁等能力，以 工具（Tools）形式暴露给 OpenClaw。接入该 Skill 后，OpenClaw 无需在本地或自有服务器部署任何执行环境，即可在对话中按需调用云上沙箱：大模型根据用户意图自动完成「创建沙箱 → 写入文件 / 执行代码或命令 → 生成预览链接 → 适时释放资源」的完整链路，用户获得真正的「对话即运行、即预览」体验。

Skill 提供的主要能力包括：

通过这一 Skill，OpenClaw 从「仅能生成代码」升级为「能生成并在云上运行代码、并返回可访问的预览链接」，将 AgentRun Sandbox 的秒级冷启动、多端口路由与按量计费能力与对话式交互结合，是构建 Vibecoding 与全栈预览场景的轻量级集成方式。

实践前准备（重要）

在 OpenClaw 中接入 AgentRun 能力前，需要先完成以下准备：

1. 在 AgentRun 控制台创建 Sandbox 模板：选择「AIO 沙箱」等类型，创建模板并记录模板名称（如  your-aio-template）。
2. 配置 Sandbox 泛域名：在 AgentRun 中创建并绑定泛域名（如  xxx.sandbox.example.com），并确保 DNS 已正确 CNAME 到 AgentRun 网关。后续预览 URL 将按  {port}-{sandboxID}.{domain} 规则生成。
3. 将 AgentRun Sandbox Skill 添加到 OpenClaw：将  agentrun-aio-sandbox-skill 以 Skill 形式接入 OpenClaw，使 LLM 可调用「创建沙箱」「执行 Python 代码」「执行 Shell 命令」「生成预览域名」「销毁沙箱」等能力。Skill 所需环境变量（如阿里云 AK/SK、Region、模板名称、泛域名）需在运行环境中正确配置。

重要说明：当前提供的  agentrun-aio-sandbox-skill 仅用于测试与演示，用于验证多端口预览链路与 OpenClaw 集成方式； 请勿直接用于生产环境。

典型交互流程简述

1. 用户向 OpenClaw 发起请求：「帮我写一个带按钮的 HTML 页面并给我预览链接。」
2. OpenClaw 调用 LLM 生成 HTML 或简单前端代码。
3. 通过 AgentRun Sandbox Skill：创建沙箱 → 在沙箱内写入文件并执行  python3 -m http.server <port> --bind 0.0.0.0（或等价命令）→ 使用  generate_preview_domain(wildcard_domain, port, sandbox_id) 得到预览域名。
4. 将  https://{port}-{sandbox_id}.{domain} 返回给用户；用户点击即可在浏览器中访问该沙箱内对应端口的服务，实现「生成即运行、即预览」。

示例效果展示

• 对话记录

• 预览链接效果

架构揭秘：基于 Nginx 网关的多端口路由实现

本节从实现视角说明：在 Serverless 场景下，面对海量并发的动态沙箱实例，请求如何 精准、低延迟地被送到「指定沙箱的指定端口」。AgentRun Sandbox 镜像内采用  OpenResty（Nginx + Lua） 作为统一网关，实现单一入口、多端口动态路由。

流量分发的核心问题

平台对外只暴露 一个入口端口（如 5000），而沙箱内部同时存在多个服务（Code Interpreter 5001、Browser Tool 3000、用户自定义 5173/8080 等）。网关必须回答两个问题： 当前请求要访问哪个端口？ 以及  如何把请求正确转发到该端口？ 端口信息来自两种渠道： Host 头中的泛域名（如  5173-xxx.sandbox.com）或  HTTP 头（如  X-Sandbox-Port: 5173）。

Nginx 网关规则引擎：解析与派发

网关由 单一  location / 承接所有请求，在 Lua 中分两阶段完成路由：

阶段一：rewrite** by lua_** block（路由派发）

• 先读取  X-Sandbox-Port 头；若无，再从  Host 中用正则提取子域名前缀端口（如  string.match(host, "^(%d+)%-") 得到  5173）。
• 若得到 有效端口（在 3000–65535 范围内）：不进行路径匹配，直接进入下一阶段，由  proxy_pass 动态转发到  127.0.0.1:$target_port。
• 若 无端口信息：则按请求路径派发到内置服务的 命名 location（如  /health →  @health_aggregated， /execute、 /contexts 等 → Code Interpreter， /api/v1/ → Browser Tool），通过  ngx.exec("@xxx") 做内部重定向。

阶段二：access** by lua_** block（动态端口赋值）

• 当阶段一未做路径派发时，根据 Header 或 Host 解析出的端口，设置变量  target_port、 proxy_host 等。
• 最终执行  proxy_pass http://127.0.0.1:$target\_port\，将请求转发到沙箱内对应端口。

这样设计保证了： 有端口信息时，一律按端口转发；无端口时，才走路径匹配与默认后端（如 5001 Code Interpreter）。从而避免「用户访问 5173 上的 /health」被误匹配到网关自身的健康检查。

为何不用 Nginx 自带的 location 匹配？

Nginx 的  location 规则中， 精确匹配（如  location = /health）会优先于通用  location /。若直接写  location = /health，则像  5173-xxx.sandbox.com/health 的请求也会被命中，无法转发到用户 5173 端口的服务。因此实现上采用：

• 所有面向「内置服务」的路径均改为 命名 location（如  @health_aggregated、 @path_ci、 @api_v1）。命名 location 不参与外部请求的自动匹配，只能通过 Lua 的  ngx.exec() 显式派发。
• 唯一可被匹配的 location 为  location /，在 Lua 中先判断「是否有端口」，再决定「动态转发」或「按路径派发到命名 location」。

这样就从机制上保证了 端口优先于路径的语义。

请求全链路简述

用户请求 Sandbox 域名（如 5173-xxx.sandbox.example.com）
    → AgentRun 平台网关（会话亲和、鉴权、路由到对应沙箱实例）
    → 沙箱实例内的 Nginx（OpenResty）监听 5000
    → Lua 解析 Host 得到端口 5173 → proxy_pass http://127.0.0.1:5173
    → 沙箱内监听 5173 的用户进程（如 Vite）处理请求

不同沙箱实例之间由 AgentRun 与函数计算做 会话隔离与网络隔离；同一沙箱内，Nginx 仅转发到本机回环地址的指定端口，不暴露内部服务到公网，从而在支持多端口的同时保证安全与可观测性（如自定义日志格式中记录  target_port、 port_source 等）。

总结与展望

AgentRun Sandbox 的 多端口特性，本质上是补齐了「AI 全栈开发」中最关键的一环：把 生成代码变成真正的 生成应用——在隔离沙箱中运行、通过泛域名或 Header 按端口访问、秒级冷启动与按量计费，让 Vibecoding 从「能写」走向「能跑、能看」。

行动呼吁（Call to Action）：若你正在构建 AI 编程助手、在线 IDE 或全栈预览能力，欢迎将 AgentRun Sandbox 的多端口能力集成到自己的产品中。可从以下入口开始：

• 产品与文档： 函数计算 AgentRun
• 控制台： AgentRun 控制台，快速创建模板与沙箱、配置泛域名
• 演示与 Skill：  agentrun-sandbox-demos（含 agentrun-aio-sandbox-skill，适用于测试与演示，生产请基于官方 API/SDK 自建）

欢迎加入「函数计算 AgentRun 客户群」交流多端口与沙箱实践，钉钉群号：134570017218。

快速了解函数计算 AgentRun

一句话介绍： 函数计算 AgentRun 是一个以高代码为核心的一站式 Agentic AI 基础设施平台。秉持生态开放和灵活组装的理念，为企业级 Agent 应用提供从开发、部署到运维的全生命周期管理。

函数计算 AgentRun 架构图

AgentRun 运行时基于阿里云函数计算 FC 构建，继承了 Serverless 计算极 致弹性、按量付费、零运维的核心优势。通过深度集成 AgentScope、LangChain、RAGFlow、Mem0 等主流开源生态。函数计算  AgentRun 将 Serverless 的极 致弹性、零运维和按量付费的特性与 AI 原生应用场景深度融合，助力企业实现成本与效率的极 致优化，平均 TCO 降低 60%。

让开发者只需专注于 Agent 的业务逻辑创新，无需关心底层基础设施，让 Agentic AI 真正进入企业生产环境。