claw-code 容器优先工作流：用统一 Containerfile 在 Docker/Podman 中构建与测试 Rust 工作区

本文基于仓库内的 容器工作流文档 展开，讲解 claw-code 如何用一个签入根目录的 Containerfile 为 Docker 与 Podman 用户提供同一套构建/测试入口：如何构建镜像、如何把仓库绑定挂载进容器运行 cargo test --workspace、如何同时挂载第二个仓库供 claw 处理，并深入剖析 claw sandbox 命令背后的容器检测机制。读完本文，你可以直接在容器中复现完整的 Rust 工作区构建与测试流程，并能用源码级证据解释容器内外的隔离状态差异。

为什么需要签入的容器工作流

docs/container.md 首先交代了仓库的现状：claw-code 的 Rust 运行时在文档加入之前就已经具备容器检测能力，但此前仓库中并没有签入任何 Dockerfile、Containerfile 或 .devcontainer/ 配置，CI 也没有定义容器作业。文档为补齐这一空白而存在。具体而言：

• rust/crates/runtime/src/sandbox.rs 会检测 Docker/Podman/容器的各种标记，例如 /.dockerenv、/run/.containerenv、匹配的环境变量，以及 /proc/1/cgroup 中的线索；
• rust/crates/rusty-claude-cli/src/main.rs 通过 claw sandbox 子命令（等价于 cargo run -p rusty-claude-cli -- sandbox）暴露这一状态；
• .github/workflows/rust-ci.yml 在 ubuntu-latest 上运行 cargo fmt --check、cargo test --workspace、cargo clippy --workspace 等作业，但它没有定义 Docker 或 Podman 容器作业——本地容器工作流与 CI 是两条并行的验证路径，而非互相替代。

因此，这份文档带来的核心产物就是根目录下一个签入的 Containerfile，让 Docker 和 Podman 用户拥有一个规范的、单一来源的容器工作流。

镜像的定位：可复用的 Rust 构建/测试外壳

根目录的 Containerfile 非常精简，全文如下：

FROM rust:bookworm

RUN apt-get update \
    && apt-get install -y --no-install-recommends \
        ca-certificates \
        git \
        libssl-dev \
        pkg-config \
    && rm -rf /var/lib/apt/lists/*

ENV CARGO_TERM_COLOR=always
WORKDIR /workspace
CMD ["bash"]

各行的作用值得逐一说明：

内容	作用
FROM rust:bookworm	基于 Debian 12（bookworm）官方 Rust 镜像，锁定 glibc 生态，保证工具链与 pkg-config/libssl-dev 的组合可复现
git	工作区多处依赖 git 元信息（分支、提交状态等），构建/测试过程需要
libssl-dev + pkg-config	原生 OpenSSL 绑定（HTTP 客户端等）在 Debian 上需要开发头文件与 pkg-config 才能编译成功
ca-certificates	保证 HTTPS 请求（API 调用、crates.io 拉取）的证书信任链完整
ENV CARGO_TERM_COLOR=always	与 CI 中 CARGO_TERM_COLOR: always 的约定保持一致（见 rust-ci.yml 的 env 段），日志着色行为一致
WORKDIR /workspace	为后续绑定挂载预留统一挂载点

关键设计决策是：镜像本身不拷贝任何仓库内容（没有 COPY/ADD 指令）。文档明确推荐把 checkout 通过绑定挂载放进 /workspace，这样源码编辑始终留在宿主机上，镜像只负责提供工具链和依赖包。这与仓库的 Cargo 工作区布局配合：Rust 工作区位于 rust/ 目录，rust/Cargo.toml 以 members = ["crates/*"] 声明成员，版本为 0.1.3，并在全局禁止 unsafe_code。

构建镜像：Docker 与 Podman 各一条命令

从仓库根目录执行：

Docker

docker build -t claw-code-dev -f Containerfile .

Podman

podman build -t claw-code-dev -f Containerfile .

两条命令完全同构——这正是签入单一 Containerfile 的意义：Docker 与 Podman 共用同一份构建定义，-f Containerfile 显式指定构建文件（而非默认的 Dockerfile），. 作为构建上下文。

在容器内运行 cargo test --workspace

文档给出的标准运行命令有三个要点：挂载仓库到 /workspace、把 Cargo 构建产物重定向到容器内的 /tmp/claw-target（避免污染工作树）、并切换到 Rust 工作区目录 rust/。

Docker

docker run --rm -it \
  -v "$PWD":/workspace \
  -e CARGO_TARGET_DIR=/tmp/claw-target \
  -w /workspace/rust \
  claw-code-dev \
  cargo test --workspace

Podman

podman run --rm -it \
  -v "$PWD":/workspace:Z \
  -e CARGO_TARGET_DIR=/tmp/claw-target \
  -w /workspace/rust \
  claw-code-dev \
  cargo test --workspace

两个参数值得特别理解：

• CARGO_TARGET_DIR=/tmp/claw-target：默认的 target/ 会落在绑定挂载的 checkout 里，产生大量容器用户属主（root）的构建产物。重定向到容器私有路径后，宿主工作树保持干净，--rm 删除容器时产物随之销毁。
• Podman 的 :Z 后缀：用于 SELinux 重标注（relabeling）。在 Fedora/RHEL 系宿主机上应保留；Docker 示例中不需要。

文档还提示：如需完全干净的重建，在 cargo test --workspace 前加 cargo clean &&。

打开交互式 shell 做日常开发

如果只是想在容器里自由构建、调试，文档给出的是不带尾随命令的同款挂载：

Docker

docker run --rm -it \
  -v "$PWD":/workspace \
  -e CARGO_TARGET_DIR=/tmp/claw-target \
  -w /workspace/rust \
  claw-code-dev

Podman

podman run --rm -it \
  -v "$PWD":/workspace:Z \
  -e CARGO_TARGET_DIR=/tmp/claw-target \
  -w /workspace/rust \
  claw-code-dev

进入 shell 后的推荐动作序列：

cargo build --workspace
cargo test --workspace
cargo run -p rusty-claude-cli -- --help
cargo run -p rusty-claude-cli -- sandbox

其中 sandbox 子命令是文档特别点名的容器工作流健康检查：在 Docker 或 Podman 内运行时，它应当报告 In container true，并列出运行时实际检测到的标记。这个报告的来源可以在源码中确认：

• 检测入口是 rust/crates/runtime/src/sandbox.rs 中的 detect_container_environment()，它收集三类证据：/.dockerenv 是否存在、/run/.containerenv 是否存在、以及进程环境变量。
• detect_container_environment_from()（同文件 L119-L153）把证据归一为标记列表：文件标记直接记为路径；环境变量只匹配 container、docker、podman、kubernetes_service_host（大小写不敏感且值非空），记成 env:KEY=value；/proc/1/cgroup 内容中若出现 docker、containerd、kubepods、podman、libpod 之一，则记为 /proc/1/cgroup:<needle>。只要标记非空，in_container 即为 true。
• CLI 侧的报告由 rust/crates/rusty-claude-cli/src/main.rs 中的 format_sandbox_report() 渲染，字段包括 Enabled、Active、Supported、In container、Requested ns/Active ns、Requested net/Active net、Filesystem mode、Allowed mounts、Markers、Fallback reason 等；加 --output-format json 可获得机器可读版本（见 USAGE.md 中“诊断动词支持 JSON 输出”的说明）。

也就是说，文档中“In container true + 标记列表”这个验收标准，直接对应 SandboxStatus 结构里的 in_container 与 container_markers 两个字段。

值得注意的是，容器内文件系统隔离依然可用而命名空间隔离通常不可用：resolve_sandbox_status_for_request()（sandbox.rs L161-L208）通过 unshare_user_namespace_works() 探测宿主内核是否允许用户命名空间，并在不支持时写入 fallback_reason（如 "namespace isolation unavailable (requires Linux with unshare)）；而 filesystem_active 只取决于 request.enabled && filesystem_mode != Off，与是否在容器内无关。因此容器内跑 claw sandbox 时看到 namespace 项回退是预期行为，而非配置错误——源码注释也明确这是针对 AppArmor/seccomp 受限环境的防御性设计。

双仓库场景：同时挂载 claw-code 与另一个 checkout

文档给出的第四个场景是：让 claw 在容器里对一个第二个仓库工作，同时保持 claw-code 自身可读写挂载。

Docker

docker run --rm -it \
  -v "$PWD":/workspace \
  -v "$HOME/src/other-repo":/repo \
  -e CARGO_TARGET_DIR=/tmp/claw-target \
  -w /workspace/rust \
  claw-code-dev

Podman

podman run --rm -it \
  -v "$PWD":/workspace:Z \
  -v "$HOME/src/other-repo":/repo:Z \
  -e CARGO_TARGET_DIR=/tmp/claw-target \
  -w /workspace/rust \
  claw-code-dev

进入后示例操作：

cargo run -p rusty-claude-cli -- prompt "summarize /repo"

这个场景同时验证了挂载布局的两个约定：/workspace 是 claw-code 自身的开发树（-w /workspace/rust 让 shell 直接落在 Rust 工作区），/repo 是目标工作树，claw 的提示词中的路径可以直接引用容器内挂载点。

文档 Notes 的工程细节与延伸阅读

docs/container.md 结尾的 Notes 归纳了四条约定，与上文逐一对应：

• Docker 与 Podman 共用同一个签入的 Containerfile，不维护两套构建文件；
• Podman 示例中的 :Z 是 SELinux 重标注后缀，Fedora/RHEL 系宿主机上应保留；
• CARGO_TARGET_DIR=/tmp/claw-target 的目地是让容器属主的 target/ 产物不落入绑定挂载的 checkout；
• 非容器环境的本地开发继续沿用 USAGE.md 与 rust/README.md。

此外可以补充两点源码层面的佐证：其一，cargo run -p rusty-claude-cli -- sandbox 这条文档命令之所以成立，是因为 main.rs 的参数解析把 sandbox 登记为诊断类动词（与 status、doctor、state 等并列），并支持 --output-format json（见 main.rs 中 sandbox 帮助与解析逻辑）；其二，容器检测逻辑本身有单元测试覆盖，detects_container_markers_from_multiple_sources（sandbox.rs L382-L404）验证了文件标记、环境变量标记、cgroup 标记三类来源能同时被识别——这解释了为什么文档把 claw sandbox 定位为“sanity check”：它的每一行输出背后都有对应的可测试代码路径。

适用前提与限制：上述流程假定你在仓库根目录操作，且宿主机已安装 Docker 或 Podman；镜像基于 rust:bookworm，构建依赖宿主机对 Debian 12 基础层的拉取能力；Podman 的 :Z 仅在启用了 SELinux 的发行版上有意义，在其他发行版上添加不会报错但属于冗余。