1. 项目概述：为AI编码助手打造一个便携且安全的“笼子”

如果你和我一样，日常重度依赖像Claude Code这样的AI编码助手来提升开发效率，那么一个无法回避的担忧始终悬在心头：这个闭源的、代码被混淆的二进制文件，在我的系统里到底在做什么？它真的只读取我当前项目目录的文件吗？会不会在后台悄悄扫描我的 ~/.ssh 目录、浏览我的个人文档，或者上传一些不该上传的数据？虽然Anthropic作为一家负责任的AI公司，大概率不会这么做，但在安全领域，信任从来不应该替代验证。尤其是在处理公司核心代码或个人敏感项目时，这种不确定性就像一颗定时炸弹。

ClaudeCage 这个项目，就是为了彻底解决这个信任问题而生的。它的核心思想非常直接：为Claude Code CLI套上一个坚不可摧的“笼子”（Cage）。这个“笼子”基于成熟的Linux命名空间（namespaces）和容器隔离技术构建，将Claude Code的运行环境完全限制在你指定的、唯一的工作目录内。最终，它被打包成一个 单一的可执行文件 ，无需在宿主机安装Node.js、Bun等任何运行时依赖，下载即用。更妙的是，由于它使用了高性能的Bun运行时，其执行速度甚至比官方的Claude Code还要快。简单来说，ClaudeCage让你既能享受顶级AI编码助手的便利，又能拥有绝对的控制权和安全感，实现“鱼与熊掌兼得”。

2. 核心原理与技术栈拆解

要理解ClaudeCage如何工作，我们需要拆解其技术栈。这不仅仅是调用几个API那么简单，而是一套从应用打包到运行时隔离的完整解决方案。

2.1 隔离基石：Bubblewrap与Linux Namespaces

ClaudeCage的“笼子”本质是一个轻量级容器，其底层隔离能力来源于 Bubblewrap 。Bubblewrap是一个用于创建非特权（unprivileged）容器的工具，它深度利用了Linux内核的 Namespaces 和 Seccomp-bpf 等安全特性。

  • 命名空间（Namespaces） ：这是Linux内核提供的资源隔离机制。ClaudeCage主要利用了以下几种：
    • PID Namespace ：为 claude 进程创建一个独立的进程树，它看不到宿主机上的其他进程，也无法向它们发送信号。
    • Mount Namespace ：创建独立的文件系统挂载点视图。这是实现“仅访问当前目录”的关键。通过精细控制 bind mount ，ClaudeCage只将你当前的工作目录（以及必要的只读系统目录）挂载到容器内部，而你的 $HOME 、 /root 、 /boot 等敏感路径在容器内根本不存在。
    • Network Namespace ：默认情况下，ClaudeCage可能会创建一个独立的网络命名空间（具体取决于配置）。这意味着 claude 进程拥有自己的网络栈，与宿主机隔离。这对于防止其探测内网或进行未授权的网络通信至关重要。
    • UTS Namespace ：隔离主机名和域名，防止其获取宿主机标识信息。
  • Seccomp-bpf ：一种内核安全模块，用于限制进程可以执行的系统调用。ClaudeCage可以通过配置，禁止 claude 进程调用诸如 mount 、 swapon 、 clone 等危险或不需要的系统调用，将攻击面降到最低。

这种组合拳确保了即使Claude Code的二进制文件中存在恶意代码（或者因漏洞被利用），其破坏能力也被严格限制在沙箱内部，无法触及你的核心系统资产。

2.2 打包魔法：RunImage项目

仅有隔离能力还不够，如何将Claude Code、其依赖的Bun运行时、以及所有必要的库文件打包成一个 单一、便携的可执行文件 ？这就是 RunImage 项目的功劳。

RunImage是一个用于创建单文件Linux容器镜像的工具。它的工作原理可以类比为一个自解压的压缩包，但更智能：

  1. 构建阶段 ：它首先在一个干净的构建环境中，将目标应用（Claude Code）、运行时（Bun）及其所有动态库依赖打包成一个特殊的文件系统镜像（通常是SquashFS格式）。
  2. 封装阶段 ：将这个文件系统镜像与一个微型的、静态链接的“启动器”二进制文件拼接在一起。这个启动器内嵌了Bubblewrap的逻辑。
  3. 运行阶段 ：当你执行最终的 claude 文件时，这个启动器会：
    • 将自己“切开”，分离出文件系统镜像。
    • 在内存中（或临时目录）解压/挂载这个镜像。
    • 调用Bubblewrap，以这个镜像作为容器的根文件系统（rootfs），并应用ClaudeCage提供的安全配置（ .rcfg 文件），最终启动容器内的Claude Code进程。

这个过程完全对用户透明。你得到的 claude 文件，既是容器配置，也是运行时，还是应用本身，真正实现了“开箱即用”。

2.3 性能秘诀：Bun运行时

官方Claude Code CLI基于Node.js。而ClaudeCage选择使用 Bun 作为JavaScript运行时。Bun是一个用Zig语言编写的一体化工具包，兼容Node.js的API，但在性能上有多项显著优势：

  • 更快的启动时间 ：Bun的启动速度远超Node.js，这对于需要频繁交互的CLI工具体验提升明显。
  • 高效的包管理 ：内置了速度极快的包管理器，但在此场景下，所有依赖已预打包，此优势不直接体现。
  • 优化的JavaScript引擎 ：Bun使用JavaScriptCore（JSC）引擎，在某些工作负载下比Node.js使用的V8引擎表现更好。

因此，ClaudeCage不仅更安全，而且运行Claude Code指令的速度通常比原版更快，这是一个非常实用的额外收益。

3. 从零开始部署与使用ClaudeCage

了解了原理，我们来动手实践。ClaudeCage提供了两种获取方式：直接下载预编译的二进制文件，或者从源码构建。对于大多数用户，前者是最佳选择。

3.1 方案一：下载预构建二进制文件（推荐）

这是最快捷的方式，适合所有主流的Linux发行版（如Ubuntu, Debian, Fedora, Arch等）。

  1. 获取文件 ： 前往项目的GitHub Releases页面，下载最新版本的 claude 和 claude.rcfg 文件。这两个文件必须成对使用。

  2. 放置到PATH路径 ： 为了让系统在任何目录都能识别 claude 命令，需要将这两个文件放到系统 PATH 环境变量包含的目录中。个人用户通常使用 ~/.local/bin/ 。

    # 创建目录（如果不存在）
mkdir -p ~/.local/bin
# 将下载的 claude 和 claude.rcfg 移动到该目录
mv /path/to/downloaded/claude /path/to/downloaded/claude.rcfg ~/.local/bin/
# 为可执行文件添加权限
chmod +x ~/.local/bin/claude

  3. 验证安装 ： 确保 ~/.local/bin 在你的PATH中（通常默认已在）。然后打开一个新终端，运行：

    claude --version

    如果看到Claude Code的版本信息输出，说明安装成功。第一次运行可能会提示你进行身份验证，按照指引操作即可。

3.2 方案二：从源代码构建

如果你想验证构建过程，或者需要进行自定义修改，可以从源码构建。构建过程非常简单，只需要 curl 和基本工具。

# 1. 克隆仓库
git clone https://github.com/PACHAKUTlQ/ClaudeCage.git
cd ClaudeCage

# 2. 执行构建脚本
./build.sh

构建脚本 build.sh 会自动完成以下工作：

  • 下载指定版本的Claude Code CLI（从Anthropic官方源）。
  • 下载Bun运行时和RunImage工具。
  • 将所有组件打包，最终在当前目录生成 claude 和 claude.rcfg 文件。

注意 ：构建过程需要从GitHub等网络下载资源，请确保网络通畅。生成的二进制文件与构建机器的架构相关（通常是x86_64）。

3.3 基础使用与命令冲突处理

安装完成后，使用方式与官方 claude 命令完全一致，实现了“无缝替换”。

# 进入你的项目目录
cd ~/projects/my-secret-app

# 像平常一样使用claude命令
claude "请分析这个main.py文件，找出潜在的性能瓶颈。"

此时，ClaudeCage启动的沙箱环境 只能看到并访问 ~/projects/my-secret-app 这个目录及其子目录。它无法向上跳出到 ~/projects 或你的家目录 ~ 。

处理命令冲突 ： 如果你系统上已经安装了官方的 claude 命令（例如通过 npm install -g @anthropic-ai/claude-code ），那么将ClaudeCage放入 PATH 可能会覆盖它。有两种处理方式：

  1. 优先级覆盖 ：如果你希望默认使用更安全的ClaudeCage，只需确保 ~/.local/bin 在 PATH 中的顺序位于官方 claude 所在路径（如 /usr/bin ） 之前 。通常用户目录的优先级本就更高。
  2. 重命名共存 ：如果你想同时保留两个版本，可以重命名ClaudeCage的可执行文件及其配置文件。 
    mv ~/.local/bin/claude ~/.local/bin/claude-cage
mv ~/.local/bin/claude.rcfg ~/.local/bin/claude-cage.rcfg
# 使用时指定名称
claude-cage "这是一个安全的请求。"
    关键是，可执行文件（如 claude-cage ）和它的配置文件（ claude-cage.rcfg ）必须 基名相同 ，RunImage启动器才能正确找到配置。

4. 深度配置解析与定制

ClaudeCage的强大之处在于其可配置性。默认配置已在安全性和实用性之间取得了良好平衡，但你可以通过编辑 claude.rcfg 文件来精细控制沙箱的行为。

4.1 配置文件结构解析

.rcfg 文件是一个简单的文本文件，定义了沙箱的各类参数。我们来看关键部分：

# 示例 .rcfg 文件核心部分（非完整文件）
name="claude"
image="./claude.squashfs" # 内部镜像路径，构建时确定，一般无需改动

# 1. 持久化数据挂载（读写）
bind+=("$HOME/.claude.json" "/home/user/.claude.json" rw)
bind+=("$HOME/.claude/" "/home/user/.claude/" rw)

# 2. 项目目录挂载（读写） - 这是动态的，由启动时的CWD决定
# 在内部逻辑中，会将你运行命令时的当前目录绑定到容器的相同路径

# 3. 系统工具目录挂载（只读）
ro_bind+=("/usr" "/usr")
ro_bind+=("/lib" "/lib")
ro_bind+=("/lib64" "/lib64")
ro_bind+=("/bin" "/bin")
ro_bind+=("/sbin" "/sbin")
ro_bind+=("/opt" "/opt")
ro_bind+=("/etc" "/etc")

# 4. 网络与进程隔离
unshare_all=true # 启用所有支持的命名空间隔离
die_with_parent=true # 主进程退出时杀死所有子进程
new_session=true # 创建新的会话（session）

# 5. 环境变量传递
keep_env+=("HOME") # 传递HOME变量，但容器内路径是映射后的
keep_env+=("ANTHROPIC_AUTH_TOKEN") # 传递认证token
keep_env+=("SSH_AUTH_SOCK") # 传递SSH代理套接字路径，用于git操作

4.2 关键配置项详解与调整建议

  1. 持久化目录（ $HOME/.claude* ） ：

    • 作用 ：Claude Code需要在本地存储你的认证令牌、会话历史和少量配置。默认配置将宿主机的 ~/.claude.json 和 ~/.claude/ 目录以读写方式绑定到容器内。
    • 安全考量 ：这是必要的妥协，否则每次启动都需要重新登录。这些文件本身只包含Anthropic的认证信息和你的对话历史，相对敏感度较低。权限被设置为 600 （文件）和 700 （目录），仅限所有者读写。
    • 自定义 ：你可以修改绑定路径。例如，如果你想为不同项目使用完全独立的Claude配置，可以基于项目目录动态设置： 
      # 在项目目录内创建一个专属的 .claude 目录
mkdir -p ./.claude_project
# 然后修改.rcfg，或通过脚本在运行前动态设置环境变量来覆盖绑定路径（更高级用法）

  2. 系统只读挂载（ /usr , /etc 等） ：

    • 作用 ：让Claude Code能够调用宿主机上的编译器（如 gcc , python3 ）、解释器、构建工具（如 make , cargo ）和系统命令（如 git , find ）。没有这些，AI将无法执行“运行这个测试”或“安装依赖”等指令。
    • 只读（ro）的重要性 ：设置为只读后，容器内的进程可以读取这些目录下的工具，但 无法修改、删除或替换它们 。这防止了恶意代码篡改你的系统命令。

  3. SSH代理转发 ：

    • 默认安全策略 ：如果环境变量 SSH_AUTH_SOCK 存在（意味着SSH代理正在运行），ClaudeCage会 仅转发这个Unix套接字文件 到容器内。这样，容器内的 git 命令可以使用你的SSH密钥进行认证（例如克隆私有仓库），但 无法读取 ~/.ssh/id_rsa 等私钥文件本身 。这是“最小权限原则”的完美体现。
    • 高风险选项 ：只有在极端需要下才启用 CLAUDECAGE_ALLOW_SSH_KEYS=1 。这会直接将你的 ~/.ssh 目录以读写方式挂载进容器，极大增加风险。除非你完全信任当前项目环境且必须让AI直接操作密钥文件，否则绝不建议使用。

  4. 网络隔离 ：

    • 默认配置通常启用了网络命名空间隔离。这意味着 claude 进程的网络与宿主机是分开的。它可以通过宿主机的网络接口访问外网（以调用Anthropic API），但无法访问宿主机上只监听 127.0.0.1 或内部网络的服务，除非显式配置端口转发。
    • 影响 ：如果你的Claude Code需要通过本地代理（如 http://127.0.0.1:7890 ）访问API，或者需要连接本地运行的开发服务器（如 localhost:3000 ），默认配置下是无法成功的。这是安全性的代价。

4.3 高级配置：连接本地服务与自定义API端点

场景一：让ClaudeCage使用本地HTTP代理或连接本地API服务。

由于网络隔离，你需要修改 .rcfg 文件，允许容器访问宿主机的网络，或者进行特定的端口绑定。

# 方法A：完全禁用网络命名空间隔离（不推荐，降低安全性）
# 在 .rcfg 中找到类似 `unshare_all=true` 的行，可能需要将其改为 `unshare_all=false`，
# 或者寻找专门的网络隔离选项并关闭它。这取决于RunImage的具体版本和配置语法。
# 更安全的方法是使用方法B。

# 方法B：通过 `--share-net` 或类似参数允许共享宿主网络命名空间（如果RunImage支持）
# 你可能需要在启动器层面添加参数，或者修改.rcfg中的 `extra_args` 部分。
# 例如，假设RunImage支持：
extra_args+=("--share-net")

# 方法C：端口转发（更精细的控制）
# 如果只想让容器访问宿主机的某个端口（如本地代理127.0.0.1:7890），可以尝试绑定宿主机的网络回环设备。
# 但这在Bubblewrap中配置较为复杂，通常更简单的方法是使用方法B，并确保你的代理服务监听在 `0.0.0.0:7890` 而不仅仅是 `127.0.0.1:7890`。
# **注意：将代理服务绑定到0.0.0.0会暴露给同一网络的其他机器，请评估局域网安全风险。**

修改后，你可以在运行 claude 前设置代理环境变量：

export HTTP_PROXY="http://192.168.1.100:7890" # 使用宿主机的IP，而非127.0.0.1
export HTTPS_PROXY="http://192.168.1.100:7890"
claude "帮我写一个函数。"

场景二：使用自定义模型或第三方API服务（如OpenAI、Ollama）。

Claude Code本身设计用于连接Anthropic的API。但社区项目 claude-code-router 提供了一个优雅的解决方案。它是一个路由层，可以拦截Claude Code的请求，并将其转发到其他大模型提供商（如OpenRouter、DeepSeek、本地Ollama等）。

  1. 安装claude-code-router :

    npm install -g @musistudio/claude-code-router

  2. 配置路由 : 你需要按照其文档配置一个 config.yaml ，指定不同模型对应的API端点、密钥等。

  3. 启动路由并连接ClaudeCage :

    # 启动路由服务，假设它监听在 127.0.0.1:3456 并提供兼容Claude API的接口
ccr code
# 在另一个终端，设置环境变量指向这个本地路由
export ANTHROPIC_BASE_URL="http://127.0.0.1:3456/v1/" # 注意端口和路径
export ANTHROPIC_AUTH_TOKEN="dummy-token" # 如果路由不需要验证，可以填任意值
# 运行ClaudeCage。由于网络隔离，你需要确保ClaudeCage能访问到127.0.0.1:3456。
# 根据上述“场景一”的说明，你可能需要调整网络配置。
claude "用DeepSeek模型解释这段代码。"


**直接配置环境变量**：如果你不使用router，而是直接想让Claude Code调用其他兼容Anthropic API格式的服务，也可以直接设置环境变量：
```bash
export ANTHROPIC_BASE_URL="https://your-openai-proxy.com/v1/"
export ANTHROPIC_API_KEY="your-api-key" # 注意变量名可能是 ANTHROPIC_AUTH_TOKEN
export ANTHROPIC_MODEL="gpt-4o" # 指定模型
claude "Hello"

这要求你的代理服务完全模拟Anthropic API的响应格式。

5. 实战场景、问题排查与安全边界探讨

5.1 典型工作流与实操示例

假设你正在开发一个Python Web项目，目录为 ~/dev/awesome-api 。

# 1. 进入项目目录
cd ~/dev/awesome-api

# 2. 让ClaudeCage分析项目结构并给出建议
claude "浏览当前目录的代码结构，并给出一个改善导入组织的建议。"

# 3. 让ClaudeCage编写一个新功能。因为它只能访问当前目录，
#    所以它生成的所有文件都会安全地落在 ~/dev/awesome-api 内。
claude "在 `app/routers/` 目录下创建一个新的路由文件 `items.py`，实现基本的CRUD端点。"

# 4. 让ClaudeCage运行测试。由于系统工具目录(/usr/bin)已只读挂载，
#    它可以成功调用 `pytest`。
claude "运行项目的单元测试，并告诉我是否有失败的情况。"

# 5. 让ClaudeCage安装依赖。它可以读取 `requirements.txt` 并调用 `pip install`。
#    注意：`pip install` 会尝试写入系统目录或用户目录。
#    由于系统目录只读，而用户目录(~/.local/lib/python3.x)可能未挂载，
#    这可能会导致安装失败。更安全的做法是在宿主机进行依赖管理。
#    你可以指示ClaudeCage使用 `pip install --user`，但这需要将宿主机的 `~/.local` 挂载进容器（需额外配置）。
claude "检查requirements.txt，并告诉我缺少哪些依赖。"

实操心得 ：将ClaudeCage严格用于 代码生成、分析和建议 ，而将 系统级操作（如安装包、运行数据库迁移） 留给在宿主机手动执行或在更受控的Docker容器内执行，是最安全、最清晰的工作流划分。

5.2 常见问题与排查指南

问题1：运行 claude 命令后无反应或立即退出。

  • 可能原因A ： .rcfg 配置文件丢失或未与可执行文件放在同一目录，或基名不匹配。
    • 排查 ：执行 ls -la $(which claude)* ，确认 claude 和 claude.rcfg 在同一个目录（如 ~/.local/bin/ ）。
  • 可能原因B ：可执行文件权限不足。
    • 排查与解决 ： chmod +x ~/.local/bin/claude 。
  • 可能原因C ：系统缺少Bubblewrap ( bwrap ) 命令。RunImage内部依赖它。
    • 排查 ：在终端运行 which bwrap 。
    • 解决 ：使用包管理器安装。在Ubuntu/Debian上： sudo apt install bubblewrap 。在Fedora/RHEL上： sudo dnf install bubblewrap 。在Arch上： sudo pacman -S bubblewrap 。

问题2：ClaudeCage无法访问网络，提示API连接错误。

  • 可能原因A ：默认的网络命名空间隔离导致无法解析DNS或路由。
    • 排查 ：在容器内测试网络非常困难。一个间接方法是尝试在宿主机上 curl https://api.anthropic.com ，确保宿主机网络正常。
    • 解决 ：按照 4.3节 的方法，尝试修改配置以共享宿主网络（ --share-net ）。 注意这会降低安全性 。
  • 可能原因B ：使用了需要代理的网络环境，且代理设置未传入容器。
    • 解决 ：首先确保代理在宿主机工作。然后，在运行 claude 前设置 HTTP_PROXY 和 HTTPS_PROXY 环境变量。同时，可能需要按 问题2A 解决网络隔离问题，使容器能连接到宿主机的代理IP和端口。

问题3：ClaudeCage无法调用系统命令，如 git , python , gcc 。

  • 可能原因A ：系统工具目录未正确挂载或挂载为只读导致某些需要写入缓存的操作失败。
    • 排查 ：检查 .rcfg 文件中的 ro_bind 行，确保包含了 /usr/bin 、 /bin 等路径。
    • 注意 ：某些工具在运行时需要写入临时文件或缓存。如果它们试图写入只读的 /usr/bin 目录，则会失败。这是正常的安全限制。复杂的编译任务可能更适合在宿主机进行。
  • 可能原因B ：容器内的PATH环境变量与宿主机不同。
    • 解决 ：可以在 .rcfg 文件中使用 keep_env+=("PATH") 来传递宿主机的PATH，但需注意路径映射的一致性。更简单的方法是，在给Claude的指令中，使用命令的绝对路径（如 /usr/bin/git ）。

问题4：如何确认ClaudeCage真的被“关在笼子里”？

你可以运行一些简单的探测命令来验证其隔离性：

# 1. 尝试列出家目录，应该失败或返回空/不存在
claude "运行 'ls -la ~' 命令，看看能访问什么。"

# 2. 尝试读取敏感文件，应该失败
claude "尝试显示 '/etc/shadow' 文件的内容。"

# 3. 查看进程，应该只能看到容器内的少数进程
claude "运行 'ps aux' 命令。"

# 4. 查看网络接口，应该与宿主机不同
claude "运行 'ip addr show' 或 'ifconfig' 命令。"

如果这些命令返回了你的真实数据，说明沙箱配置有误，需要检查 .rcfg 文件。

5.3 安全边界与局限性认知

ClaudeCage提供了强大的隔离，但必须清醒认识其边界：

  1. 非万能容器 ：它基于Bubblewrap，是一个“无根容器”（rootless container），其隔离强度 弱于 Docker或Podman等完整的容器引擎。它无法提供像cgroups那样的资源限制（CPU/内存），也无法实现像用户命名空间映射那样更深度的隔离。对于极度敏感的环境，仍需评估。
  2. 内核漏洞风险 ：所有容器技术都依赖Linux内核。如果内核存在提权漏洞（如Dirty Pipe），攻击者有可能突破命名空间隔离。这是所有容器化方案的共同风险。
  3. 社会工程学攻击 ：沙箱无法防止你主动将敏感信息粘贴到与Claude的对话中。AI可能会诱导你执行某些操作，例如让你运行一个它生成的、看似无害但实际会通过 curl 将数据外传的脚本。 沙箱保护的是文件系统访问，而不是你的判断力。
  4. 数据持久化点 ：如前所述， ~/.claude.json 和 ~/.claude/ 目录是读写挂载的。如果Claude Code客户端存在漏洞导致这些文件被恶意写入或篡改，可能会影响后续使用。定期审查这些文件的内容是良好的安全习惯。

最佳实践建议 ：

  • 将ClaudeCage用于 不包含最高机密 的日常开发项目。
  • 对于处理密钥、凭证、未加密用户数据的项目，考虑在专用的、一次性虚拟机或完全独立的物理环境中使用。
  • 定期更新ClaudeCage版本，以获取最新的安全修复和Claude Code的功能更新。
  • 保持批判性思维，不要盲目执行AI生成的、涉及系统修改或数据发送的命令。

ClaudeCage的价值在于，它将一个潜在的安全风险从“完全不可控”降级为“在一个透明、受限的范围内可控”。它让你能够安心地在更多场景下利用AI编码助手的强大能力，而无需时刻担忧背后隐藏的成本。对于注重安全和隐私的开发者来说，这是一个不可或缺的工具。

Logo
DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

cover

DeepSeek 成本看板搭建实战：如何从 per-token 粒度优化推理账单

avatar DeepSeek技术社区
cover

RAG索引重建的工程陷阱：新旧向量空间混排如何保证召回质量

avatar DeepSeek技术社区
cover

DeepSeek-V4 API 接入实践：如何平衡延迟与成本的工程决策

avatar DeepSeek技术社区