概述

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

模板预装 Node.js、Python、Git、ripgrep、vim、GitHub CLI 和常用前端脚手架。镜像内不保存真实 API key；可以在创建 Sandbox 时直接传入 XAI_API_KEY，也可以使用 HTTPS 密钥注入，让真实密钥只保留在平台侧。

模板内容

创建 Sandbox

通过 envs 传入 XAI_API_KEY：

import { Sandbox } from 'e2b'

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

这种方式使用 Grok Build 原生的 API Key 认证。使用完成后应及时销毁 Sandbox：

await sandbox.kill()

常用 CLI flag

Grok Build CLI 当前不提供 --base-url 参数。自定义模型服务地址需要通过环境变量或用户级模型配置指定。

无头执行

import { Sandbox } from 'e2b'

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

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

模板会在启动 grok 时准备所需的认证状态。正确传入 API key 或密钥注入规则后，可以直接执行无头命令，无需先运行 grok login。

Git 仓库集成

import { Sandbox } from 'e2b'

const sandbox = await Sandbox.create('grok', {
  envs: { XAI_API_KEY: process.env.XAI_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 && grok --always-approve -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 密钥注入会在请求离开 Sandbox 时写入真实 Authorization Header。Sandbox 内的 Grok Build 只使用占位认证，无法读取真实 API key。

使用 qshell 内联注入访问 xAI 官方 API：

qshell sandbox create grok \
  --inline-injection "type=openai,api-key=${XAI_API_KEY},base-url=https://api.x.ai"

xAI API 使用 OpenAI-compatible Bearer Token 认证，因此注入类型为 openai。模板会自动建立 Grok Build 所需的占位认证状态，进入 Sandbox 后可以直接执行：

grok --always-approve -p "Create a hello world HTTP server in Go"

对于已经保存的注入规则，可以通过 SDK 引用规则 ID：

import { Sandbox } from 'e2b'

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

try {
  const result = await sandbox.commands.run(
    'grok --always-approve -p "Review the current repository"',
  )
  console.log(result.stdout)
} finally {
  await sandbox.kill()
}

内联注入适合临时验证。命令中的密钥会作为 qshell 进程参数传递；长期或多人协作场景建议使用持久注入规则，便于审计、轮换和回收。

使用兼容网关

注入规则中的 base-url 只用于匹配需要改写的 HTTPS 请求，不会改变 Grok Build 的模型服务地址。使用兼容 xAI Responses API 的自定义网关时，还需要设置 GROK_XAI_API_BASE_URL：

qshell sandbox create grok \
  --inline-injection "type=openai,api-key=${XAI_API_KEY},base-url=https://llmapi.example.com" \
  -e GROK_XAI_API_BASE_URL=https://llmapi.example.com/v1

模板会把 GROK_XAI_API_BASE_URL 同步到 Grok Build 的 API Key 和 CLI Chat Proxy 调用链。注入规则与 Grok 配置的 Host 必须一致，自定义网关需要支持 POST /v1/responses。

如果网关还要求指定模型 ID，可以在 Sandbox 中写入用户级配置：

# ~/.grok/config.toml
[model.gateway]
model = "your-model-id"
base_url = "https://llmapi.example.com/v1"
name = "Gateway"
env_key = "XAI_API_KEY"
api_backend = "responses"

[models]
default = "gateway"

故障排查

• 提示 Not signed in：确认使用的是 grok 模板，并通过 XAI_API_KEY 或密钥注入创建 Sandbox。当前模板会在首次运行时自动初始化认证状态。
• 请求仍访问 api.x.ai：注入规则的 base-url 不负责修改上游地址；自定义网关还需要传入 GROK_XAI_API_BASE_URL。
• 返回 401：检查 API key 是否有效，以及注入规则的 Host 是否与 Grok 实际请求地址一致。
• 返回 403 且提示出口 IP 不允许：将 Sandbox 的实际出口 IP 加入网关访问白名单，或调整对应安全策略。

--always-approve 会允许 Grok Build 自动执行工具调用。Sandbox 默认可以访问互联网，应根据任务所需配置出站网络规则，并在任务结束后检查代码差异和命令输出。

参考

• xAI Grok Build：https://docs.x.ai/build/overview
• 密钥注入