概述

pi 是预构建的 AI Agents 运行环境，已内置 Pi CLI，可在隔离的 Sandbox 中以交互或无头模式生成、修改和执行代码，并访问完整的文件系统、终端和 Git 工作区。

Pi 支持通过 TypeScript extensions、skills、prompt templates 和 themes 扩展。模板同时预装 Node.js、Python、Git、ripgrep、vim、GitHub CLI 和常用前端脚手架。镜像内不保存 API Key，认证信息需要在创建 Sandbox 时提供。

模板内容

创建 Sandbox

以下示例使用 Anthropic，通过 envs 传入 ANTHROPIC_API_KEY：

import { Sandbox } from 'e2b'

const sandbox = await Sandbox.create('pi', {
  envs: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY },
  timeoutMs: 600_000,
})

Pi 也支持其他模型供应商，常用认证环境变量如下：

无头执行

使用 -p 执行提示词，Pi 会在任务完成后退出：

import { Sandbox } from 'e2b'

const sandbox = await Sandbox.create('pi', {
  envs: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY },
})

try {
  const result = await sandbox.commands.run(
    'pi -p "Create a hello world HTTP server in Go"',
    { onStdout: (data) => process.stdout.write(data) },
  )
  console.log(result.exitCode)
} finally {
  await sandbox.kill()
}

Pi 的内置工具不会弹出权限确认，因此无需传入自动批准参数。Sandbox 默认可以访问互联网，应根据任务范围配置出站网络规则，并在任务结束后检查代码差异和命令输出。

指定供应商和模型

可以通过 CLI 参数选择模型供应商和模型：

pi --provider anthropic \
  --model claude-sonnet-4-5 \
  -p "Review the current repository"

常用参数如下：

自动化场景优先使用环境变量，避免 API Key 出现在命令参数和进程列表中。

Git 仓库集成

import { Sandbox } from 'e2b'

const sandbox = await Sandbox.create('pi', {
  envs: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY },
  timeoutMs: 600_000,
})

try {
  await sandbox.git.clone('https://github.com/your-org/your-repo.git', {
    path: '/home/user/repo',
    username: 'x-access-token',
    password: process.env.GITHUB_TOKEN,
    depth: 1,
  })

  const result = await sandbox.commands.run(
    'cd /home/user/repo && pi -p "Add error handling to all API endpoints"',
    { onStdout: (data) => process.stdout.write(data) },
  )
  console.log(result.exitCode)

  const diff = await sandbox.commands.run('cd /home/user/repo && git diff')
  console.log(diff.stdout)
} finally {
  await sandbox.kill()
}

配合密钥注入使用

HTTPS 密钥注入可以让真实 API Key 只保留在平台侧。先在本机将 QINIU_AI_API_KEY 设置为七牛 AI 网关密钥；以下命令创建临时 Sandbox，并在访问兼容 Anthropic 协议的七牛 AI 网关时由平台写入真实的 x-api-key：

qshell sandbox create pi \
  --inline-injection "type=qiniu,api-key=${QINIU_AI_API_KEY},base-url=https://api.qnaigc.com" \
  -e ANTHROPIC_API_KEY=placeholder

Pi 在发起请求前要求 API Key 非空，因此 Sandbox 内需要设置非敏感占位值。平台匹配 api.qnaigc.com 的 HTTPS 请求后，会用真实密钥替换该请求头。进入 Sandbox 后，把 Pi 的 Anthropic 请求地址配置为同一个网关：

mkdir -p ~/.pi/agent

cat > ~/.pi/agent/models.json <<'EOF'
{
  "providers": {
    "qiniu-anthropic": {
      "baseUrl": "https://api.qnaigc.com",
      "api": "anthropic-messages",
      "apiKey": "$ANTHROPIC_API_KEY",
      "models": [
        { "id": "qwen3-coder-480b-a35b-instruct" }
      ]
    }
  }
}
EOF

pi --provider qiniu-anthropic \
  --model qwen3-coder-480b-a35b-instruct \
  -p "Create a hello world HTTP server in Go"

使用 OpenAI 兼容协议

使用 OpenAI 兼容网关时，Pi 的 models.json 决定实际请求地址，qshell 的 base-url 决定密钥注入匹配的目标。两处应指向同一个网关：qshell 使用主机根地址匹配该网关的请求，Pi 使用 Responses API 根地址：

qshell sandbox create pi \
  --inline-injection "type=qiniu,api-key=${QINIU_AI_API_KEY},base-url=https://api.qnaigc.com" \
  -e OPENAI_API_KEY=placeholder

进入 Sandbox 后，创建自定义供应商配置：

mkdir -p ~/.pi/agent

cat > ~/.pi/agent/models.json <<'EOF'
{
  "providers": {
    "qiniu-openai": {
      "baseUrl": "https://api.qnaigc.com/bypass/openai/v1",
      "api": "openai-responses",
      "apiKey": "$OPENAI_API_KEY",
      "models": [
        { "id": "your-model-id" }
      ]
    }
  }
}
EOF

pi --provider qiniu-openai \
  --model your-model-id \
  -p "Create a hello world HTTP server in Go"

请将 your-model-id 替换为网关支持的模型 ID。示例使用 OpenAI Responses API。使用 Chat Completions API 时，请把 baseUrl 改为 https://api.qnaigc.com/v1，并把 api 改为 openai-completions。

已经保存 qiniu 类型的密钥注入规则时，可以通过 SDK 引用规则 ID：

import { Sandbox } from 'e2b'

const sandbox = await Sandbox.create('pi', {
  envs: { ANTHROPIC_API_KEY: 'placeholder' },
  injections: [{ id: '<rule-id>' }],
})

try {
  await sandbox.commands.run('mkdir -p /home/user/.pi/agent')
  await sandbox.files.write(
    '/home/user/.pi/agent/models.json',
    JSON.stringify({
      providers: {
        'qiniu-anthropic': {
          baseUrl: 'https://api.qnaigc.com',
          api: 'anthropic-messages',
          apiKey: '$ANTHROPIC_API_KEY',
          models: [{ id: 'qwen3-coder-480b-a35b-instruct' }],
        },
      },
    }),
  )

  const result = await sandbox.commands.run(
    'pi --provider qiniu-anthropic --model qwen3-coder-480b-a35b-instruct -p "Review the current repository"',
  )
  console.log(result.stdout)
} finally {
  await sandbox.kill()
}

内联注入适合临时验证。长期或多人协作场景可以使用持久注入规则，便于审计、轮换和回收。

交互模式

直接运行 pi 会进入终端交互界面：

pi

交互模式支持使用 /login 保存订阅或 API Key 凭据、使用 /model 切换模型，以及通过 extensions、skills、prompt templates 和 themes 定制工作流。临时 Sandbox 和自动化任务通常无需执行登录流程，创建时传入认证环境变量即可。