在现代软件开发与 AI Agent 协同编程的时代,“沙盒(Sandbox)”技术已成为保护开发者宿主系统、隔离不可信第三方脚本、以及支持 Agent 自主化运行的核心基石。
本文将结合 Google Antigravity 的实战案例,深入剖析 无沙盒(Raw Host)、本地沙盒(Local Sandbox) 和 云端沙盒(Cloud Sandbox) 的底层运行机制、配置体系、电报机器人(Telegram Bot)联动代码,并以图形化流程解构其核心区别。
1. 三种运行模式深度剖析与对比
🔓 1.1 无沙盒原生模式 (Unsandboxed / Raw Host)
- 定义:Agent 以您物理机当前登录用户的身份,直接在宿主机的文件系统和 Shell 中运行。
- 安全性:极低。没有任何隔离机制。如果 Agent 执行了恶意脚本或误删命令(如
rm -rf /),宿主机系统会立即损坏。 - 文件访问:可以直接读写宿主机的任意用户文件(包括本地的
~/.ssh秘钥目录、密码数据库等)。 - 资源消耗:完全占用本地物理机的 CPU、内存和电池。
🛡️ 1.2 本地沙盒模式 (Local Sandbox)
- 定义:利用操作系统内核级轻量级虚拟隔离技术对运行环境进行“加锁”控制。
- 安全性:高。Agent 被锁在虚拟容器中,无法窥探或篡改沙盒外的任何真实系统文件。
- 底层机制:
- macOS:使用系统内核的
sandbox-exec进行进程限制。 - Linux:使用 Google 开源的
nsjail(cgroups / namespaces) 技术进行隔离。 - Windows:使用
AppContainer机制。
- macOS:使用系统内核的
- 资源消耗:消耗本地物理机的计算资源(CPU/内存)。
☁️ 1.3 云端无服务器沙盒模式 (Serverless Cloud Sandbox)
- 定义:沙盒完全托管在 Google Cloud 数据中心,与开发者本地物理机在物理上完全隔绝。
- 安全性:极高(绝对安全)。
- 底层机制:当发起 API 调用交互时,Google Cloud 会秒级在云端动态 Provision(配置并启动)一个 Ephemeral Linux Container(临时隔离容器),并在运行完毕后瞬间物理销毁。
- 运行理念:
[!IMPORTANT] 它是“即用即销毁”的一次性执行环境,而不是常驻后台的 Daemon 程序! 任务结束,容器立即灰飞烟灭,零闲置成本,零安全残留。
- 网络与存储:默认运行在 Google 的虚拟私有网络(VPC)中,IP 出口属于 Google Cloud。
2. 实验项目:云端沙盒一次性遥测推送器
🎯 2.1 核心项目需求与终极目标
本项目的业务需求是:创建一个安全的隔离沙盒环境,并在该沙盒内以无服务器(Serverless)一次性执行模式运行一套自动化遥测程序。该程序必须能自动捕获沙盒当前出站的公网出口 IP、所在的物理地理位置(国家、省份、城市)以及实时的气象指标(晴雨与温度),并通过强加密 HTTPS 协议安全推送至开发者的个人 Telegram Bot 进行实时自动播报。
🎯 2.2 核心业务功能细分
- 环境自检 (Self-Probing):
- 自动提取当前沙盒会话的公网出口 IP 以及网络服务商(ISP)信息(通过
ipinfo.io)。
- 自动提取当前沙盒会话的公网出口 IP 以及网络服务商(ISP)信息(通过
- 多维数据抓取 (Telemetry Data Collection):
- 无缝调用外部天气 API,根据沙盒当前的物理 IP 位置,自动抓取其所在地的实时气象指标(通过
wttr.in)。
- 无缝调用外部天气 API,根据沙盒当前的物理 IP 位置,自动抓取其所在地的实时气象指标(通过
- 电报自动播报 (Telegram Telemetry Push):
- 构造统一的数据面板,按格式自动推送给指定的 Telegram Bot 聊天室。
- 单次审计模式 (
--once):- 执行一次自检、抓取、推送后立即退出,沙盒随即销毁,完美符合 Serverless 理念。
🛡️ 2.3 极致的沙盒兼容性设计
- 零外部库依赖 (Zero-Dependency):
- 云端沙盒是最小化 Linux 容器,安装第三方库(如
requests等)不仅增加网络冷启动耗时,更有可能被沙盒网络白名单拦截。 - 设计:代码必须 100% 采用 Python 内置标准库(仅使用
urllib、json)编写,保证在任何秒级拉起的临时沙盒中“开箱即用”。
- 云端沙盒是最小化 Linux 容器,安装第三方库(如
- 密钥配置物理隔离 (Decoupled Credentials):
- 采用标准的
.env配置文件承载 API Keys。开发完毕后通过环境变量读取,彻底划清代码逻辑与密钥凭证的边界。
- 采用标准的
3. 系统的软件与环境拓扑架构设计
为了达成上述强隔离、高可用且零依赖的设计目标,我们设计了如下的分层集成拓扑架构:
+-----------------------------------------------------------------------------------+
| 宿主与沙盒物理执行边界 |
| |
| +-----------------------------------------------------------------------------+ |
| | Google Cloud / Local Linux Sandbox (执行环境) | |
| | | |
| | +-------------------------------------------------------------------+ | |
| | | 1. 密钥配置层 (Configuration) | | |
| | | - 映射 .env 文件 (TELEGRAM_BOT_TOKEN / CHAT_ID) | | |
| | +------------------+------------------------------------------------+ | |
| | | (读取注入) | |
| | v | |
| | +-------------------------------------------------------------------+ | |
| | | 2. 推理与控制核心 (Execution Core) | | |
| | | - 一次性执行引擎 (python3 telegram_cron_simulator.py --once) | | |
| | +------------------+------------------------------------------------+ | |
| | | (自检触发) | |
| | v | |
| | +-------------------------------------------------------------------+ | |
| | | 3. 多维自检与遥测引擎 (Telemetry Engine) | | |
| | | - 纯 urllib 接口 | | |
| | | - ipinfo.io API (获取出口IP及Toronto等位置) | | |
| | | - wttr.in 气象 API (抓取温度及晴雨) | | |
| | +------------------+------------------------------------------------+ | |
| | | (TLS 1.3 安全发送) | |
| | v | |
| | +-------------------------------------------------------------------+ | |
| | | 4. 出口安全网络层 (Egress Network) | | |
| | | - 沙盒网格 VPC 虚拟网卡 (网络白名单限制) | | |
| | +------------------+------------------------------------------------+ | |
| +-----------------------|-----------------------------------------------------+ |
+--------------------------|--------------------------------------------------------+
|
| (SSL / TLS 1.3 链路安全穿越)
v
+------------------+------------------+
| 电报云端服务器 (Telegram Bot API) |
+------------------+------------------+
|
| (Push 消息推送)
v
+------------------+------------------+
| 用户物理终端 (Telegram Mobile App) |
+-------------------------------------+
🧠 3.1 元智能体编排(Base Agent Orchestrator)原理
在 Google Agent Platform 中,有一个核心概念:“演员”与“剧本”。
- Base Agent(演员):当我们在配置中指定
"base_agent": "antigravity-preview-05-2026"时,Google Cloud 会分配一个极其聪明的元智能体编排引擎。它天生掌握阅读 Markdown 指令、规划任务并安全调用沙盒内 Linux 工具的能力。 - Custom Agent(剧本):我们提交的
AGENTS.md(人设指令)、SKILL.md(动作步骤)和 Python 源码,就是这个演员要在临时舞台(云端沙盒)上表演的剧本和道具。
4. 架构配置与执行流程图 (Mermaid)
下面的流程图展示了 Antigravity 在不同配置下,是如何调度并决定 Agent 命令在哪个沙盒环境执行,以及 Telegram Bot 的最终通信链路:
flowchart TD
Start(["开发者输入命令 agy"]) --> ReadConfig["读取 settings.json 配置文件"]
ReadConfig --> CheckSandboxEnabled{"enableTerminalSandbox == true?"}
%% Unsandboxed Route
CheckSandboxEnabled -- No --> UnsandboxedRun["无沙盒原生模式 (Raw Local)"]
UnsandboxedRun --> HostShell["直连本地终端 shell (UID 501 / root)"]
HostShell --> LocalWrite["直接修改本地物理硬盘"]
%% Sandboxed Route
CheckSandboxEnabled -- Yes --> CheckCloudProvider{"是否存在 cloudSandbox 块?"}
%% Local Sandbox Route
CheckCloudProvider -- No --> LocalSandboxRun["本地沙盒模式 (Local Sandbox)"]
LocalSandboxRun --> MacSandbox["macOS sandbox-exec 隔离网格"]
MacSandbox --> LocalJail["本地硬盘限制 (CWD 限制)"]
%% Cloud/Docker Sandbox Route
CheckCloudProvider -- Yes --> CheckProvider{"provider 的值是什么?"}
CheckProvider -- "google-cloud" --> CloudSandboxRun["云端托管沙盒模式"]
CloudSandboxRun --> GCPContainer["Google Cloud Ephemeral Container"]
GCPContainer --> GcpNetwork["GCP VPC 网络出口 (Torono AS20473)"]
CheckProvider -- "docker" --> LocalDockerRun["本地 Docker 沙盒模式"]
LocalDockerRun --> LocalDockerContainer["本地拉起轻量级 Docker 容器"]
LocalDockerContainer --> LocalDockerNetwork["共享本地 network"]
%% Telegram Event Flow
GcpNetwork & LocalJail & LocalDockerNetwork --> ExecApp["执行 telegram_cron_simulator.py"]
ExecApp --> ReadEnv["读取 .env 密钥配置文件"]
ReadEnv --> IpInfoProbe["调用 ipinfo.io 抓取沙盒出口 IP / 地理位置"]
IpInfoProbe --> WttrProbe["调用 wttr.in 抓取当地实时天气"]
WttrProbe --> TelegramApi["调用 Telegram API (api.telegram.org)"]
TelegramApi --> UserTelegram["用户手机 Telegram App 收到美观 of Tick 信息"]
style UnsandboxedRun fill:#ff9999,stroke:#ff3333,stroke-width:2px;
style LocalSandboxRun fill:#ffff99,stroke:#cccc00,stroke-width:2px;
style CloudSandboxRun fill:#99ff99,stroke:#33cc33,stroke-width:2px;
style UserTelegram fill:#99ccff,stroke:#3333ff,stroke-width:2px;5. 极简、高兼容性沙盒运行代码实现
为满足云端沙盒**“冷启动快、无多余依赖”**的要求,我们编写了一款只依赖 Python 3 标准库的高维环境探测与电报通知脚本:telegram_cron_simulator.py。
📄 安全凭证配置文件 (`.env`)
TELEGRAM_BOT_TOKEN=8763417888:AAE3U-VFaM4FYB5dpEb6xlRBiHdMx16v888
TELEGRAM_CHAT_ID=8250511888
📄 沙盒主程序代码 (`telegram_cron_simulator.py`)
#!/usr/bin/env python3
import os
import sys
import time
import urllib.request
import urllib.parse
import json
from datetime import datetime
def load_env():
env_file = ".env"
if not os.path.exists(env_file):
env_file = os.path.join(os.path.dirname(__file__), ".env")
if not os.path.exists(env_file):
return {}
config = {}
with open(env_file, "r") as f:
for line in f:
line = line.strip()
if not line or line.startswith("#"):
continue
if "=" in line:
key, val = line.split("=", 1)
config[key.strip()] = val.strip()
return config
def get_sandbox_network_info():
"""通过 ipinfo.io 探测沙盒的公网 IP 和地理位置"""
try:
req = urllib.request.Request("https://ipinfo.io/json", headers={'User-Agent': 'Mozilla/5.0'})
with urllib.request.urlopen(req, timeout=5) as response:
data = json.loads(response.read().decode())
return {
"ip": data.get("ip", "Unknown IP"),
"city": data.get("city", "Unknown City"),
"region": data.get("region", "Unknown Region"),
"country": data.get("country", "Unknown Country"),
"org": data.get("org", "Unknown ISP")
}
except Exception as e:
return {"ip": "Unknown IP", "city": "Unknown City", "region": "Unknown Region", "country": "Unknown Country", "org": str(e)}
def get_weather(city):
"""利用 wttr.in 免 Key 探测当地实时天气"""
if not city or city == "Unknown City":
url = "https://wttr.in?format=%C+%t"
else:
city_encoded = urllib.parse.quote(city)
url = f"https://wttr.in/{city_encoded}?format=%C+%t"
try:
req = urllib.request.Request(url, headers={'User-Agent': 'curl/7.79.1'})
with urllib.request.urlopen(req, timeout=5) as response:
return response.read().decode('utf-8').strip()
except Exception as e:
return f"Weather unavailable ({str(e)})"
def send_telegram_message(token, chat_id, message):
url = f"https://api.telegram.org/bot{token}/sendMessage"
payload = urllib.parse.urlencode({"chat_id": chat_id, "text": message, "parse_mode": "Markdown"}).encode("utf-8")
req = urllib.request.Request(url, data=payload, headers={"User-Agent": "Mozilla/5.0"})
try:
with urllib.request.urlopen(req, timeout=10) as response:
res_data = json.loads(response.read().decode())
return res_data.get("ok"), "Success"
except Exception as e:
return False, str(e)
def main():
config = load_env()
token = config.get("TELEGRAM_BOT_TOKEN")
chat_id = config.get("TELEGRAM_CHAT_ID")
if not token or not chat_id:
print("[!] Error: Credentials missing in .env")
sys.exit(1)
args = sys.argv[1:]
if args and args[0] == "--once":
current_time = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
net_info = get_sandbox_network_info()
weather = get_weather(net_info["city"])
message = (
f"🔔 *Antigravity Cloud Sandbox Explorer Update*\n\n"
f"📍 *位置 (Location)*: `{net_info['city']}, {net_info['region']}, {net_info['country']}`\n"
f"🌐 *公网 IP (Exit IP)*: `{net_info['ip']}`\n"
f"🏢 *运营商 (ISP)*: `{net_info['org']}`\n"
f"🌤️ *当地天气 (Weather)*: `{weather}`\n"
f"⏰ *当前时间 (Time)*: `{current_time}`\n\n"
f"🚀 *状态*: 沙盒多维探测运行正常!"
)
success, info = send_telegram_message(token, chat_id, message)
if success:
print(" --> SUCCESS! Probed metadata delivered to your Telegram Bot.")
else:
print(f" --> FAILED: {info}")
if __name__ == "__main__":
main()
6. 基于官方 `google-genai` SDK 的生命周期管理实现
在本地 Mac 升级到官方标准的 Python 3.11.9 并安装了最新版 google-genai SDK 之后,我们可以使用极其优雅的面向对象(OOP)方式来完成 Custom Agent 的注册与一次性运行。
下面是重构后的 /Users/eric/.gemini/antigravity-cli/scratch/run_agent.py 核心逻辑实现:
from google import genai
import os
# 1. 初始化官方 SDK 客户端 (自动从 GEMINI_API_KEY 环境变量加载)
client = genai.Client()
agent_id = "telegram-notifier"
# 2. 🧹 清理可能存在的旧配置,保证部署的幂等性
try:
client.agents.delete(id=agent_id)
except Exception:
pass
# 3. 🚀 部署并注册 Custom Agent 蓝图 (包含系统提示词、源码文件和技能)
client.agents.create(
id=agent_id,
base_agent="antigravity-preview-05-2026",
system_instruction="你是一个云端一次性遥测智能体...",
base_environment={
"type": "remote",
"sources": [
{
"type": "inline",
"target": ".env",
"content": "TELEGRAM_BOT_TOKEN=...\nTELEGRAM_CHAT_ID=...\n"
},
{
"type": "inline",
"target": "telegram_cron_simulator.py",
"content": "[Python 零依赖探针源码]"
},
{
"type": "inline",
"target": ".agents/skills/telegram-pusher/SKILL.md",
"content": "[技能描述,定义了运行 python3 telegram_cron_simulator.py --once]"
}
]
}
)
# 4. 🔌 一键拉起一次性无服务器云端沙盒运行,发送消息后沙盒物理销毁
interaction = client.interactions.create(
agent=agent_id,
input="Execute the telegram-pusher skill to collect remote telemetry.",
environment="remote" # 👈 直接传 "remote" 字符串,云端会自动根据预注册的 blueprint 拉起沙盒!
)
print("云端执行完成!请检查您的 Telegram 手机端。")
7. 本地沙盒安全权限配置手册 (settings.json vs config.json)
本地沙盒的安全隔离是基于 VS Code 插件级配置与底层引擎配置双管齐下的。
7.1 `settings.json`(插件层:目录挂载与开关)
位于 ~/.gemini/antigravity-cli/settings.json,用于控制基本行为:
{
"antigravity.sandbox.enabled": true,
"antigravity.sandbox.allowedDirectories": [
"/Users/eric/work/agy"
]
}
7.2 `config.json`(安全层:精细化“三态拦截”)
位于 ~/.gemini/config/config.json,控制具体的命令和资源权限。
[!CAUTION] 绝对的防自我越权机制: 为防止恶意 AI 自行篡改安全级别,该文件对 AI 代理的写入权限是
denied(完全禁止) 的!只有人类才能手动修改它!
{
"permissions": {
"command": {
"allowed": [
"echo", "date", "ls" // 🟢 允许自动静默执行,绝不弹窗
],
"ask": [
"brew", "pip", "python3.11", "curl" // 🟡 触发黄色气泡,必须人类手动按 1 授权
],
"denied": [
"sudo", "rm -rf /", "chmod" // 🔴 物理死锁,直接报错,不允许运行
]
},
"read_file": {
"allowed": ["/Users/eric/work/agy"],
"denied": ["/Users/eric/.ssh", "/Users/eric/.gemini/config/config.json"]
}
}
}

8. 总结
- 无沙盒模式是高风险的“全裸”运行,将系统控制权完全交给 AI,只适用于纯单机无毒开发;
- 本地沙盒模式利用
sandbox-exec/nsjail技术与config.json的“三态拦截”规则,构建起了一道物理级的人机信任红线,保障宿主安全; - 云端无服务器沙盒则是面向未来的终极生产形态。它将执行彻底隔绝在 Google 物理云端,随用随建,完工即毁,零闲置计费,零依赖冷启动,并通过官方
google-genaiSDK 实现无缝的高级智能体编排。