Song's Blog

外观

Ubuntu 下修复 Codex sandbox 的 bubblewrap 权限问题

约 1258 字大约 4 分钟

CodexUbuntuSandbox

2026-05-11

在 Ubuntu 上启动 Codex 时，如果看到下面这类提示：

⚠ Codex's Linux sandbox uses bubblewrap and needs access to create user namespaces.

或者手动测试 bwrap 时出现：

bwrap: setting up uid map: Permission denied

通常说明问题不在 Codex 本身，而是在系统对 bubblewrap 和 user namespace 的限制上。

这篇文章整理一下排查思路，以及一种相对稳妥的处理方式。

问题原因

Codex 在 Linux 下会借助 bubblewrap 提供隔离环境。要让它正常工作，系统至少要允许两件事：

  • 创建 user namespace
  • 完成 uid/gid map 相关操作

在 Ubuntu 24.04 中，即使 user namespace 已经开启，AppArmor 仍然可能拦截 bubblewrap，最终表现为 Codex 无法正常启用 sandbox。

先检查 user namespace

先确认系统是否允许非特权用户创建 user namespace：

cat /proc/sys/kernel/unprivileged_userns_clone

如果输出是：

1

说明这一项已经开启。

如果输出是：

0

则可以临时开启：

sudo sysctl kernel.unprivileged_userns_clone=1

如果希望重启后仍然生效，更稳妥的做法是单独写一个 sysctl.d 配置文件：

printf 'kernel.unprivileged_userns_clone=1\n' | sudo tee /etc/sysctl.d/60-codex-userns.conf
sudo sysctl --system

测试 bubblewrap 是否被拦截

接着可以直接测试 bubblewrap：

bwrap --ro-bind / / true

如果命令直接返回、没有任何输出，说明 bwrap 基本可用。

如果报错：

bwrap: setting up uid map: Permission denied

在 Ubuntu 24.04 上，这通常是 AppArmor 把它拦下来了，但这不是唯一可能，user namespace、uid/gid map 或系统策略本身也可能导致类似报错。

推荐做法：只给 /usr/bin/bwrap 放行

相比直接关闭整套限制，更稳妥的方式是只针对 bubblewrap 增加一条 AppArmor 配置。

先创建配置文件：

sudo nano /etc/apparmor.d/local-bwrap

写入下面内容：

abi <abi/4.0>,
include <tunables/global>

profile local-bwrap /usr/bin/bwrap flags=(unconfined) {
  userns,

  include if exists <local/bwrap>
}

然后重新加载 AppArmor：

sudo systemctl reload apparmor

这样做的思路是：不去全局放开限制，而是只给 bwrap 这个可执行文件单独放行。

再次验证

重新运行：

bwrap --ro-bind / / true

如果这次没有报错，就可以继续测试 Codex：

codex

正常情况下，Codex 就可以以 sandbox 模式启动了。

Codex 里的两个常用操作

如果是第一次用 Codex，顺手记一下两个最常见的命令：

在 Codex 中执行 shell 命令：

!ls
!pwd
!git status

退出 Codex：

/quit

不推荐但能绕过去的方法

1. 直接关闭 Codex sandbox

codex --no-sandbox

这样确实能启动，但隔离就没了，只适合临时排查，不适合长期使用。

2. 全局关闭 AppArmor 对 user namespace 的限制

sudo sysctl kernel.apparmor_restrict_unprivileged_userns=0

这种做法影响的是整个系统，而不是单个程序，风险明显更高。

如果只是为了解决 Codex 的 sandbox 问题，更建议优先采用“仅对 /usr/bin/bwrap 放行”的方式。

如果希望所有项目在改文件前都先询问

上面的处理只解决了 Linux 下 bubblewrap 的 sandbox 启动问题。

如果你想要的是另一件事:

不管在哪个项目里，Codex 在修改文件前都先征求你的同意

那还需要额外配置 Codex 自己的全局审批策略。

1. 修改 ~/.codex/config.toml

把下面这几项写进去：

approval_policy = "on-request"
sandbox_mode = "read-only"
approvals_reviewer = "user"

这组配置的含义是：

  • 默认可以读取文件
  • 任何写文件操作都需要先审批
  • 部分命令执行和网络访问也可能进入审批流程，具体取决于当前会话的 sandbox 和权限设置

换句话说，sandbox 管的是隔离和权限边界，approval_policy 管的是操作前要不要先问你。

2. 再补一个全局 ~/.codex/AGENTS.md

为了让 Codex 在行为上也更明确，可以再加一个全局指令文件：

## Global Editing Policy

- Before making any file changes, explain which files will be changed and why.
- Wait for my explicit approval before applying edits.
- Do not create, modify, rename, or delete files before approval.

这样做相当于两层保险：

  • ~/.codex/config.toml 负责从权限层面卡住写操作
  • ~/.codex/AGENTS.md 负责从行为层面要求“先说明，再修改”

3. 配完以后记得重开 Codex

这些全局配置通常需要在新会话里才会稳定生效。

如果你已经在当前会话里切换过权限模式，旧会话不一定会自动继承新的默认设置。

小结

这个问题的核心通常不是 Codex 安装失败，而是 Ubuntu 24.04 对 bubblewrap 的安全限制更严格了。

排查时可以按这个顺序来：

  1. 检查 unprivileged_userns_clone 是否开启
  2. 用 bwrap --ro-bind / / true 单独测试
  3. 如果是 AppArmor 拦截，就只对 /usr/bin/bwrap 增加放行规则
  4. 如果你还想让所有项目都“改前先问”，再补上 ~/.codex/config.toml 和 ~/.codex/AGENTS.md 的全局配置

这样处理下来，一般既能保留 sandbox，又不用把系统级安全限制整体关掉。

版权归属：Guisong Wu

许可证：署名 4.0 国际 (CC-BY-4.0)