AGENTUPDATE 技术博客

深入浅出Managed agent,从本地隔离到云端托管 (Google Antigravity cli 实战指南)

深入浅出Managed agent,从本地隔离到云端托管 (Google Antigravity  cli 实战指南)
目录

在现代软件开发与 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 机制。
  • 资源消耗:消耗本地物理机的计算资源(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 核心业务功能细分

  1. 环境自检 (Self-Probing):
    • 自动提取当前沙盒会话的公网出口 IP 以及网络服务商(ISP)信息(通过 ipinfo.io)。
  2. 多维数据抓取 (Telemetry Data Collection):
    • 无缝调用外部天气 API,根据沙盒当前的物理 IP 位置,自动抓取其所在地的实时气象指标(通过 wttr.in)。
  3. 电报自动播报 (Telegram Telemetry Push):
    • 构造统一的数据面板,按格式自动推送给指定的 Telegram Bot 聊天室。
  4. 单次审计模式 (--once)
    • 执行一次自检、抓取、推送后立即退出,沙盒随即销毁,完美符合 Serverless 理念。

🛡️ 2.3 极致的沙盒兼容性设计

  • 零外部库依赖 (Zero-Dependency)
    • 云端沙盒是最小化 Linux 容器,安装第三方库(如 requests 等)不仅增加网络冷启动耗时,更有可能被沙盒网络白名单拦截。
    • 设计:代码必须 100% 采用 Python 内置标准库(仅使用 urllibjson)编写,保证在任何秒级拉起的临时沙盒中“开箱即用”。
  • 密钥配置物理隔离 (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. 总结

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

ccstatusline零基础教程

一份面向 Claude Code 用户的渐进式教程,涵盖 ccstatusline 的基础安装、TUI 配置、技术原理、Powerline 美化及外部数据接入,助你从会用到精通。

2026年5月24日 作者: AgentUpdate
谷歌 Antigravity CLI 踩坑与破局全指南(Gemini CLI 替代品)
AGENT-SYS // SYNTH

谷歌 Antigravity CLI 踩坑与破局全指南(Gemini CLI 替代品)

谷歌强推 Antigravity CLI 替代 Gemini CLI,底层用 Go 重构,速度起飞且支持多智能体并发。本文用大白话带你拆解它的核心功能、安装迁移步骤,并重点拔掉代理网络失效、反人类登录交互等深坑,帮你无痛上手这款 AI 编程新利器。

2026年5月23日 作者: Eric w