OpenSandbox接入Gemini CLI：谷歌AI编码工具的沙箱化实践完整指南

OpenSandbox接入Gemini CLI：谷歌AI编码工具的沙箱化实践完整指南

【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox

OpenSandbox 是一个面向 AI 应用的通用安全沙箱平台，本文以谷歌 AI 编码工具Gemini CLI为例，手把手演示如何在完全隔离的沙箱中运行 AI Agent 工具——3 步完成 AI 编码工具的沙箱化实践，让 API Key 与命令执行都远离你的宿主机。

为什么要把 Gemini CLI 放进沙箱

Gemini CLI 是谷歌推出的命令行 AI 编码工具（npm 包@google/gemini-cli）。它在你本机运行时，会执行代码、读写文件、发起网络请求——你必须完全信任它。而把它放进 OpenSandbox 沙箱后，你会得到：

• 🏰强隔离：CLI 在容器沙箱中运行，AI 的任何"越界"操作都无法触及宿主机
• 🔑密钥安全：GEMINI_API_KEY只注入沙箱环境变量，不在本机持久化
• 🔁可复现执行：使用内置 Node.js 的code-interpreter沙箱镜像，环境始终一致
• 🧹用完即弃：任务结束后一条命令销毁沙箱，零残留

环境准备（最快 1 分钟）

开始之前，请确保本机具备：

详细的环境配置说明可参考官方快速入门文档 docs/getting-started/index.md。

第一步：启动 OpenSandbox 沙箱服务器

首先预拉取沙箱镜像（code-interpreter已内置 Node.js，可直接安装 Gemini CLI）：

docker pull opensandbox/code-interpreter:v1.1.0

接着初始化配置并启动沙箱服务（默认监听 8080 端口）：

uv pip install opensandbox-server opensandbox-server init-config ~/.sandbox.toml --example docker opensandbox-server

服务器启动成功后，终端会打印初始化日志，确认服务正常就绪：

可以用健康检查接口快速验证：

curl http://127.0.0.1:8080/health # → {"status": "healthy"}

第二步：拉取代码并运行 Gemini CLI 沙箱示例

先获取 OpenSandbox 示例代码：

git clone https://gitcode.com/GitHub_Trending/ope/OpenSandbox.git cd OpenSandbox

官方示例 examples/gemini-cli/main.py 已经封装了完整的接入流程，核心逻辑只有 3 步：

1. 通过ConnectionConfig连接沙箱服务器，创建沙箱时注入GEMINI_API_KEY等环境变量（关键代码见 examples/gemini-cli/main.py）
2. 在沙箱内执行npm install -g @google/gemini-cli@latest安装 CLI
3. 发送测试指令gemini "Compute 1+1=?."，并实时回显沙箱内的 stdout / stderr 日志

配置好环境变量后直接运行：

uv pip install opensandbox export SANDBOX_API_KEY=<你的服务器密钥> export GEMINI_API_KEY=<你的Gemini密钥> uv run python examples/gemini-cli/main.py

运行结束后脚本会自动销毁沙箱，整个过程无需手动清理。更多细节可查阅示例说明文档 examples/gemini-cli/README.md 和 docs/examples/gemini-cli.md。

第三步：用 osb 命令行管理沙箱

除了 SDK，OpenSandbox 还提供osbCLI 工具，适合日常调试和快速验证：

pip install opensandbox-cli osb config init osb config set connection.domain localhost:8080

执行osb --help可以看到沙箱管理、命令执行、文件操作等全部能力：

一条命令创建沙箱：

osb sandbox create --image python:3.12

创建成功后会返回沙箱 ID：

拿到 ID 后即可在沙箱内执行任意命令，例如运行 Python 计算：

环境变量配置速查表

Gemini CLI 示例通过环境变量灵活定制行为，完整说明见 docs/examples/gemini-cli.md：

沙箱诊断与常见问题排查

如果沙箱行为不符合预期，用osb的诊断命令可以一次性查看容器状态、资源占用、网络端口与近期日志，快速定位问题：

几个常见"坑"及解决办法：

• npm 安装慢：为沙箱配置 npm 镜像源，或直接使用已预装 CLI 的自定义镜像
• 8080 端口被占用：修改服务器配置文件~/.sandbox.toml中的监听端口
• Gemini 无法连接：检查GEMINI_API_KEY是否正确；若网络需要代理，通过GEMINI_BASE_URL指定端点

总结：AI 编码工具沙箱化的最佳实践

本文演示了 OpenSandbox 接入 Gemini CLI 的完整流程：启动沙箱服务器 → 运行官方示例 → 用 CLI 管理沙箱，三步即可让 AI 编码工具运行在安全隔离的环境中。

同样的模式同样适用于 Claude Code、Codex CLI、OpenCode 等 AI 工具，完整示例都在 examples/ 目录下；如果想深入了解架构设计与网络隔离原理，可继续阅读 docs/architecture/index.md。

【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox