fix(doctor): detect Codex bwrap namespace denials

vincentkoc · web-flow · commit 43c6c260deb0 · 2026-05-21T16:13:53.000+08:00
Fixes #83018.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -201,6 +201,7 @@ Docs: https://docs.openclaw.ai
 - ClawHub: preserve configured base URL path prefixes when building API request URLs, so self-hosted ClawHub instances mounted under a subpath keep routing correctly. (#83982) Thanks @ThiagoCAltoe.
 - Slack: persist delivered inbound message IDs and fail closed when same-channel thread replies lose their thread context, preventing delayed duplicate replies and accidental channel-root posts. Fixes #83521. Thanks @shannon0430.
 - Codex app-server: complete OpenClaw dynamic tool diagnostics at the request boundary so successful, failed, timed out, aborted, and blocked tool calls do not leave active tool state behind. Fixes #83474. Thanks @rozmiarD.
+- Doctor/Codex: warn when Linux host policy blocks the Codex bwrap user or network namespace path used by sandboxed app-server turns, with Ubuntu/AppArmor repair guidance. Refs #83018.
 - Gateway/config: keep config writes from failing on unrelated unresolved auth-profile SecretRefs while preserving live auth-profile runtime snapshots.
 - Gateway/sessions: clear stored CLI provider resume bindings on non-subagent `/reset` so the next turn starts a fresh provider-side CLI conversation instead of resuming old context. (#83448) Thanks @jasonyliu.
 - Doctor: preserve legacy whole-agent Claude CLI intent by moving matching Anthropic model selections to model-scoped runtime policy before removing stale runtime pins. Fixes #83491. Thanks @danielcrick.
diff --git a/docs/gateway/sandboxing.md b/docs/gateway/sandboxing.md
@@ -100,6 +100,18 @@ If you deploy the OpenClaw Gateway itself as a Docker container, it orchestrates
 - **FS bridge parity (identical volume map)**: The OpenClaw Gateway native process also writes heartbeat and bridge files to the `workspace` directory. Because the Gateway evaluates the exact same string (the host path) from within its own containerized environment, the Gateway deployment MUST include an identical volume map linking the host namespace natively (`-v /home/user/.openclaw:/home/user/.openclaw`).
 - **Codex code mode**: When an OpenClaw sandbox is active, OpenClaw constrains Codex app-server turns to Codex `workspace-write` sandboxing even if the Codex plugin default is `danger-full-access`. The Codex turn network flag follows the OpenClaw sandbox egress setting, so Docker `network: "none"` stays offline and `network: "bridge"` or a custom Docker network allows outbound access. Do not mount the host Docker socket into agent sandbox containers or custom Codex sandboxes.
 
+On Ubuntu/AppArmor hosts, Codex `workspace-write` can fail before shell startup
+when the service user is not allowed to create unprivileged user namespaces.
+When Docker sandbox egress is disabled (`network: "none"`, the default),
+Codex also needs an unprivileged network namespace. Common symptoms are
+`bwrap: setting up uid map: Permission denied` and
+`bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted`. Run
+`openclaw doctor`; if it reports a Codex bwrap namespace probe failure, prefer
+an AppArmor profile that grants the required namespaces to the OpenClaw service
+process. `kernel.apparmor_restrict_unprivileged_userns=0` is a host-wide
+fallback with security tradeoffs; use it only when that host posture is
+acceptable.
+
 If you map paths internally without absolute host parity, OpenClaw natively throws an `EACCES` permission error attempting to write its heartbeat inside the container environment because the fully qualified path string doesn't exist natively.
 </Warning>
 
diff --git a/docs/plugins/codex-harness-reference.md b/docs/plugins/codex-harness-reference.md
@@ -154,6 +154,16 @@ from the OpenClaw sandbox egress setting: Docker `network: "none"` stays
 offline, while `network: "bridge"` or a custom Docker network permits outbound
 access.
 
+On Ubuntu/AppArmor hosts, Codex bwrap can fail under `workspace-write` before
+the shell command starts. If you see
+`bwrap: setting up uid map: Permission denied` or
+`bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted`, run
+`openclaw doctor` and fix the reported host namespace policy for the OpenClaw
+service user rather than granting broader Docker container privileges. Prefer
+a scoped AppArmor profile for the service process; the
+`kernel.apparmor_restrict_unprivileged_userns=0` fallback is host-wide and has
+security tradeoffs.
+
 ## Auth and environment isolation
 
 Auth is selected in this order:
diff --git a/src/commands/doctor-sandbox.ts b/src/commands/doctor-sandbox.ts
@@ -82,6 +82,85 @@ async function isDockerAvailable(): Promise<boolean> {
   }
 }
 
+type CodexBwrapNamespaceProbe =
+  | { ok: true }
+  | { ok: false; kind: "user" | "network"; command: string; reason: string };
+
+function formatNamespaceProbeCommand(args: string[]): string {
+  return ["unshare", ...args].join(" ");
+}
+
+async function runCodexBwrapNamespaceProbe(
+  kind: "user" | "network",
+  args: string[],
+): Promise<CodexBwrapNamespaceProbe> {
+  try {
+    await runExec("unshare", args, {
+      timeoutMs: 5_000,
+    });
+    return { ok: true };
+  } catch (error) {
+    const reason =
+      (error as { stderr?: string } | undefined)?.stderr?.trim() ||
+      (error as { stdout?: string } | undefined)?.stdout?.trim() ||
+      (error instanceof Error ? error.message : String(error));
+    return { ok: false, kind, command: formatNamespaceProbeCommand(args), reason };
+  }
+}
+
+function codexBwrapNeedsNetworkNamespaceProbe(cfg: OpenClawConfig): boolean {
+  const network = cfg.agents?.defaults?.sandbox?.docker?.network?.trim().toLowerCase();
+  return network === undefined || network === "" || network === "none";
+}
+
+async function probeCodexBwrapNamespaces(cfg: OpenClawConfig): Promise<CodexBwrapNamespaceProbe> {
+  if (process.platform !== "linux") {
+    return { ok: true };
+  }
+  const userProbe = await runCodexBwrapNamespaceProbe("user", [
+    "--user",
+    "--map-root-user",
+    "true",
+  ]);
+  if (!userProbe.ok || !codexBwrapNeedsNetworkNamespaceProbe(cfg)) {
+    return userProbe;
+  }
+  return await runCodexBwrapNamespaceProbe("network", [
+    "--user",
+    "--map-root-user",
+    "--net",
+    "true",
+  ]);
+}
+
+async function noteCodexBwrapNamespaceWarning(cfg: OpenClawConfig): Promise<void> {
+  const probe = await probeCodexBwrapNamespaces(cfg);
+  if (probe.ok) {
+    return;
+  }
+  const symptom =
+    probe.kind === "user"
+      ? "  bwrap: setting up uid map: Permission denied"
+      : "  bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted";
+  const networkSentence = codexBwrapNeedsNetworkNamespaceProbe(cfg)
+    ? "With Docker sandbox network egress disabled, it also needs an unprivileged network namespace."
+    : "Docker sandbox network egress is enabled, so doctor only checked the user namespace.";
+  const lines = [
+    `Codex bwrap ${probe.kind} namespace probe failed while Docker sandbox mode is enabled.`,
+    `Codex app-server \`workspace-write\` shell execution needs unprivileged user namespaces. ${networkSentence}`,
+    "On Ubuntu/AppArmor hosts this usually appears as:",
+    symptom,
+    `Probe command: ${probe.command}`,
+    `Probe result: ${probe.reason}`,
+    "",
+    "Fix the host namespace policy for the OpenClaw service user, then restart the gateway.",
+    "Prefer an AppArmor profile that grants the required namespaces to the OpenClaw service process.",
+    "`kernel.apparmor_restrict_unprivileged_userns=0` is a host-wide fallback with security tradeoffs; use it only when that host posture is acceptable.",
+    "Do not add broad Docker container privileges just to satisfy nested bwrap; that weakens the outer sandbox.",
+  ];
+  note(lines.join("\n"), "Sandbox");
+}
+
 async function dockerImageExists(image: string): Promise<boolean> {
   try {
     await runExec("docker", ["image", "inspect", image], { timeoutMs: 5_000 });
@@ -227,6 +306,7 @@ export async function maybeRepairSandboxImages(
     note(lines.join("\n"), "Sandbox");
     return cfg;
   }
+  await noteCodexBwrapNamespaceWarning(cfg);
 
   let next = cfg;
   const changes: string[] = [];
diff --git a/src/commands/doctor-sandbox.warns-sandbox-enabled-without-docker.test.ts b/src/commands/doctor-sandbox.warns-sandbox-enabled-without-docker.test.ts
@@ -69,6 +69,21 @@ describe("maybeRepairSandboxImages", () => {
     };
   }
 
+  function createSandboxConfigWithDockerNetwork(network: string): OpenClawConfig {
+    return {
+      agents: {
+        defaults: {
+          sandbox: {
+            mode: "all",
+            docker: {
+              network,
+            },
+          },
+        },
+      },
+    };
+  }
+
   async function runSandboxRepair(params: {
     mode: "off" | "all" | "non-main";
     dockerAvailable: boolean;
@@ -131,6 +146,98 @@ describe("maybeRepairSandboxImages", () => {
     );
     expect(dockerUnavailableWarning).toBeUndefined();
   });
+
+  it("warns when Codex bwrap namespaces are blocked on a sandboxed Linux host", async () => {
+    const platformSpy = vi.spyOn(process, "platform", "get").mockReturnValue("linux");
+    runExec.mockImplementation(async (command: string, args: string[]) => {
+      if (command === "docker" && args[0] === "version") {
+        return { stdout: "24.0.0", stderr: "" };
+      }
+      if (command === "unshare") {
+        throw Object.assign(new Error("unshare failed"), {
+          stderr: "unshare: write failed /proc/self/uid_map: Operation not permitted",
+        });
+      }
+      return { stdout: "", stderr: "" };
+    });
+
+    try {
+      await maybeRepairSandboxImages(createSandboxConfig("all"), mockRuntime, mockPrompter);
+    } finally {
+      platformSpy.mockRestore();
+    }
+
+    expect(note).toHaveBeenCalledWith(
+      expect.stringContaining("Codex bwrap user namespace probe failed"),
+      "Sandbox",
+    );
+    expect(note).toHaveBeenCalledWith(
+      expect.stringContaining("kernel.apparmor_restrict_unprivileged_userns=0"),
+      "Sandbox",
+    );
+  });
+
+  it("checks Codex bwrap network namespaces only when Docker sandbox egress is offline", async () => {
+    const platformSpy = vi.spyOn(process, "platform", "get").mockReturnValue("linux");
+    runExec.mockImplementation(async (command: string, args: string[]) => {
+      if (command === "docker" && args[0] === "version") {
+        return { stdout: "24.0.0", stderr: "" };
+      }
+      if (command === "unshare") {
+        if (args.includes("--net")) {
+          throw Object.assign(new Error("unshare failed"), {
+            stderr: "unshare: unshare failed: Operation not permitted",
+          });
+        }
+        return { stdout: "", stderr: "" };
+      }
+      return { stdout: "", stderr: "" };
+    });
+
+    try {
+      await maybeRepairSandboxImages(createSandboxConfig("all"), mockRuntime, mockPrompter);
+    } finally {
+      platformSpy.mockRestore();
+    }
+
+    expect(note).toHaveBeenCalledWith(
+      expect.stringContaining("Codex bwrap network namespace probe failed"),
+      "Sandbox",
+    );
+    expect(note).toHaveBeenCalledWith(
+      expect.stringContaining("bwrap: loopback: Failed RTM_NEWADDR"),
+      "Sandbox",
+    );
+  });
+
+  it("skips the Codex bwrap network namespace probe when Docker sandbox egress is enabled", async () => {
+    const platformSpy = vi.spyOn(process, "platform", "get").mockReturnValue("linux");
+    runExec.mockImplementation(async (command: string, args: string[]) => {
+      if (command === "docker" && args[0] === "version") {
+        return { stdout: "24.0.0", stderr: "" };
+      }
+      if (command === "unshare") {
+        return { stdout: "", stderr: "" };
+      }
+      return { stdout: "", stderr: "" };
+    });
+
+    try {
+      await maybeRepairSandboxImages(
+        createSandboxConfigWithDockerNetwork("bridge"),
+        mockRuntime,
+        mockPrompter,
+      );
+    } finally {
+      platformSpy.mockRestore();
+    }
+
+    expect(
+      runExec.mock.calls.some(
+        ([command, args]) => command === "unshare" && Array.isArray(args) && args.includes("--net"),
+      ),
+    ).toBe(false);
+  });
 });
 
 describe("maybeRepairSandboxRegistryFiles", () => {
