【Bug已解决】codex: sandbox mode blocks network / Cannot connect to database — CodeX CLI 沙箱阻止网络访问解决方案

1. 问题描述

CodeX CLI 在沙箱模式下无法访问网络或数据库：

# 网络访问被阻止
$ codex "测试 API 连接"
Error: Network access denied
Sandbox mode blocked network request to https://api.example.com

# 或数据库连接失败
$ codex "运行数据库迁移"
Error: ECONNREFUSED 127.0.0.1:5432
Sandbox blocked connection to localhost:5432

# 或 npm install 被阻止
$ codex "安装新依赖"
Error: Network access denied
Sandbox blocked npm registry access

# 或 curl 命令失败
$ codex "运行 curl 测试 API"
Error: Command blocked: curl
Not in allowed commands list.

这个问题在以下场景中特别常见：

• 沙箱默认禁止网络访问
• 数据库端口未被允许
• npm registry 被阻止
• curl/wget 被阻止
• allowedCommands 未包含网络命令
• 沙箱配置过于严格

2. 原因分析

核心原理拆解

CodeX 在沙箱中 → 执行网络操作
        ↓
沙箱默认禁止网络/端口/命令
        ↓
网络访问被阻止

原因分类表

原因分类	具体表现	占比
网络禁止	默认无网络	约 40%
命令未允许	curl/wget 被阻止	约 25%
端口限制	数据库端口不通	约 20%
npm 被阻止	registry 不可达	约 10%
配置过严	无 allowedCommands	约 5%

3. 解决方案

方案一：配置沙箱允许网络（最推荐）

# 步骤 1：在 config.json 中允许网络
cat > ~/.codex/config.json << 'EOF'
{
  "sandbox": {
    "enabled": true,
    "allowNetwork": true,
    "allowedCommands": [
      "npm install",
      "npm test",
      "curl",
      "wget",
      "node"
    ]
  }
}
EOF

# 步骤 2：验证
codex "运行 curl https://httpbin.org/get"

# 步骤 3：或允许特定端口
cat > ~/.codex/config.json << 'EOF'
{
  "sandbox": {
    "allowNetworkPorts": [443, 5432, 3000, 8080]
  }
}
EOF

方案二：禁用沙箱

# 步骤 1：完全禁用沙箱
codex --no-sandbox "运行 npm install"

# 步骤 2：或在配置中禁用
cat > ~/.codex/config.json << 'EOF'
{
  "sandbox": {
    "enabled": false
  }
}
EOF

# 步骤 3：验证
codex "运行 curl https://httpbin.org/get"

# 步骤 4：注意：仅在信任的环境中禁用沙箱

方案三：允许特定命令

# 步骤 1：在 allowedCommands 中添加网络命令
cat > ~/.codex/config.json << 'EOF'
{
  "sandbox": {
    "allowedCommands": [
      "curl",
      "wget",
      "npm install",
      "npm run",
      "node",
      "psql",
      "mysql",
      "redis-cli"
    ]
  }
}
EOF

# 步骤 2：验证
codex "运行 curl https://httpbin.org/get"
codex "运行 psql -c 'SELECT 1'"

方案四：使用 --print 模式

# 步骤 1：--print 模式可能有不同的沙箱策略
codex --print "运行 npm test" --max-turns 5

# 步骤 2：或配合 --auto-approve
codex --print --auto-approve --no-sandbox "运行 npm install" --max-turns 5

# 步骤 3：CI/CD 中使用
codex --print --auto-approve "task" --max-turns 10

方案五：分步执行网络操作

# 步骤 1：分析阶段（不需要网络）
codex "分析 src/index.js 中的问题"

# 步骤 2：手动执行网络操作
npm install  # 手动执行
psql -c "CREATE TABLE..."  # 手动执行

# 步骤 3：CodeX 修改代码（不需要网络）
codex "修改 src/index.js 修复问题"

# 步骤 4：手动测试
npm test  # 手动执行

方案六：Docker 网络模式

# 步骤 1：Docker 中使用 host 网络
docker run --network host \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  codex-env codex

# 步骤 2：或配置端口映射
docker run -p 5432:5432 \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  codex-env codex

# 步骤 3：容器中可能不需要沙箱
docker run codex-env codex --no-sandbox "task"

4. 各方案对比总结

方案	适用场景	推荐指数	难度
方案一：配置网络	核心修复	⭐⭐⭐⭐⭐	低
方案二：禁用沙箱	开发环境	⭐⭐⭐⭐	低
方案三：允许命令	精确控制	⭐⭐⭐⭐⭐	低
方案四：--print	CI/CD	⭐⭐⭐⭐	低
方案五：分步执行	临时	⭐⭐⭐	低
方案六：Docker	容器	⭐⭐⭐⭐	中

5. 常见问题 FAQ

5.1 沙箱默认允许网络吗

不。沙箱默认禁止网络访问，需要通过 allowNetwork: true 开启。

5.2 如何允许数据库连接

在 config.json 中添加 allowNetworkPorts: [5432, 3306, 6379]。

5.3 --no-sandbox 安全吗

不安全。禁用沙箱后 CodeX 可以执行任何操作。仅在信任的开发环境使用。

5.4 如何查看沙箱配置

cat ~/.codex/config.json | python3 -m json.tool

5.5 沙箱阻止了 curl

在 allowedCommands 中添加 curl。

5.6 npm install 被阻止

在 allowedCommands 中添加 npm install，或设置 allowNetwork: true。

5.7 Docker 中沙箱如何配置

容器本身是隔离的，可以在容器中使用 --no-sandbox 简化配置。

5.8 沙箱和 Docker 的区别

• 沙箱：CodeX 内部的安全限制
• Docker：操作系统级隔离

5.9 CI/CD 中如何处理

CI/CD 中使用 --print --auto-approve --no-sandbox，CI/CD 环境本身是隔离的。

5.10 排查清单速查表

□ 1. sandbox.allowNetwork: true 开启网络
□ 2. allowNetworkPorts: [443, 5432, 3000]
□ 3. allowedCommands 添加 curl/npm/psql
□ 4. --no-sandbox 临时禁用
□ 5. --print --auto-approve CI/CD
□ 6. 分步: 分析→手动网络→修改→手动测试
□ 7. Docker: --network host
□ 8. 容器中可用 --no-sandbox
□ 9. 查看配置: cat config.json
□ 10. 开发环境可禁用沙箱

6. 总结

1. 根本原因：沙箱阻止网络最常见原因是默认禁止网络（40%）和命令未允许（25%）
2. 最佳实践：在 config.json 中设置 allowNetwork: true 和 allowNetworkPorts
3. 命令允许：在 allowedCommands 中添加 curl、npm install、psql 等网络命令
4. 开发环境：使用 --no-sandbox 禁用沙箱（仅信任的开发环境）
5. 最佳实践建议：CI/CD 中使用 --print --auto-approve --no-sandbox，开发环境配置精确的 allowedCommands

故障排查流程图

flowchart TD
    A[沙箱阻止网络] --> B{需要网络?}
    B -->|是| C[配置 allowNetwork: true]
    B -->|否| D[分步执行]
    C --> E[配置 allowNetworkPorts]
    E --> F[allowedCommands 添加命令]
    F --> G[codex 验证]
    D --> H[分析: codex 无网络]
    D --> I[手动: npm install/psql]
    D --> j[修改: codex 无网络]
    D --> K[手动: npm test]
    G --> L{成功?}
    L -->|是| M[✅ 问题解决]
    L -->|否| N[--no-sandbox 禁用]
    N --> O[codex --no-sandbox]
    O --> M
    H --> M
    I --> j
    j --> K
    K --> M
    M --> P[CI/CD: --print --no-sandbox]
    P --> Q[✅ 长期方案]