claudebox

一条命令把 Claude Code 装进 Docker，环境干净可复现

claudebox 是一个把 Claude Code（Anthropic 的 AI 编程助手）完整装进 Docker 容器的开发环境方案。它解决的核心问题是：Claude Code 直接跑在宿主机上时，容易污染本地环境、依赖版本冲突、不同机器上行为不一致、权限与凭据管理混乱。claudebox 通过预置的开发 profile，把 Claude Code、常用语言工具链和运行时依赖打包成可复现镜像，让你在任何支持 Docker 的机器上一条命令拉起一致的 AI 编码环境。核心能力包括：容器化隔离运行 Claude Code、按语言/框架选择预配置 profile、挂载项目目录实现宿主机与容器内文件同步、统一管理 API 密钥等环境变量，并支持在 CI 或远程服务器上复用同一套环境。对于需要团队统一 AI 编码环境、或不想让 AI 助手直接操作本机文件系统的开发者，它提供了一层干净、可重建的沙箱。

开源 free 编程开发

访问官网 ↗ GitHub ↗ 文档 ↗

GitHub 星标 ★ 1155

维护状态活跃

是否开源是

定价模式 free

项目数据

分类编程开发

开发团队RchGrav

所属国家

官网地址

GitHubhttps://github.com/RchGrav/claudebox

定价模式free

价格说明开源免费，需自行部署 Docker 环境

访问状态

是否开源是

开源协议MIT

主要语言Shell

技术栈/模型

GitHub 星标★ 1155

30天Star增速

HF 下载量

上线时间2025-06-06 00:00:00

最近更新2026-09-22 00:00:00

维护状态活跃

中文支持

访问方式

移动端支持

综合评分

收录时间2026-09-23

浏览次数0

使用教程

难度：入门约 10 分钟部署方式：Docker 6 步

环境要求

已安装并可使用 Docker（ClaudeBox 会自动处理 Docker 配置，必要时把你加入 docker 组）
类 Unix 环境（安装脚本与 PATH 配置均为 Shell 脚本）
安装后需保证 ~/.local/bin 在你的 PATH 中
当前项目目录会被读写挂载到容器内 /workspace（含 .git）
磁盘上可写 ~/.claudebox/ 用于存放源码、项目状态与缓存

安装与启动步骤

1安装 claudebox

README 推荐自解压安装器（适合自动化与快速安装）；也可下载归档包解压到自定义目录，然后运行 main.sh 创建符号链接。
```
cd ~/my-tools/claudebox
./main.sh
```
2配置 PATH

安装后如果找不到 claudebox 命令，需要把 ~/.local/bin 加入 PATH，建议写进 shell 配置文件后重新加载。
```
export PATH="$HOME/.local/bin:$PATH"
```
3安装语言 Profile

按项目需要选择预配置 profile，可一次指定多个，自动解析依赖（如 C 会带上 build-tools）。
```
claudebox profile python ml
```
4安装额外软件包

在项目级环境中补充常用工具，例如 htop、vim、tmux，安装作用于当前项目而非宿主机。
```
claudebox install htop vim tmux
```
5查看可用 Profile

profiles 命令会快速列出所有可用 profile 及说明，方便确认上一步是否安装成功。
```
claudebox profiles
```
6配置 SSH 目录

建议创建专用 SSH 目录，ClaudeBox 会以读写方式挂载它；否则会只读挂载宿主机 ~/.ssh。
```
mkdir -p ~/.claudebox/ssh
chmod 700 ~/.claudebox/ssh
```

关键配置

配置项	必填	说明	示例
`PATH`	是	必须包含 ~/.local/bin 才能直接调用 claudebox	`$HOME/.local/bin:$PATH`
`~/.claudebox/ssh/`	否	可选专用 SSH 目录，以读写方式挂载，用于持久化 known_hosts	`~/.claudebox/ssh`
`~/.claude.json`	否	用户 MCP 配置读取来源，容器不会挂载整个 ~/.claude 目录	`~/.claude.json`
`profiles.ini`	否	项目级共享状态文件，记录该项目已安装的 profile	`~/.claudebox/projects//profiles.ini`

如何确认成功

运行 claudebox profiles 能列出可用 profile，或执行 claudebox 后正常进入容器化 Claude Code 环境，即表示安装成功。

常见问题

Q：安装后提示 claudebox: command not found 怎么办？

A：把 ~/.local/bin 加入 PATH（例如 export PATH="$HOME/.local/bin:$PATH"），写入 shell 配置文件后重开终端，再重新执行 claudebox。

Q：Docker 权限报错怎么处理？

A：ClaudeBox 会自动把当前用户加入 docker 组，之后需要重新登录/登出，或执行 newgrp docker，然后再次运行 claudebox。

Q：Profile 安装失败怎么排查？

A：先执行 claudebox clean --cache 清理 Docker 构建缓存，再重新执行 claudebox profile 安装对应 profile。

Q：宿主机的 ~/.claude 会被整个挂载进容器吗？

A：不会。用户 MCP 配置从 ~/.claude.json 读取，命令单独同步，全局 skill 包不会自动导入。

Q：想测试 main 分支未发布的改动怎么做？

A：使用开发安装：先执行 bash .builder/build.sh 构建安装器，再运行 ./dist/claudebox.run profiles。

注意事项

自解压安装器与归档安装的具体下载命令在 README 节选中不完整，请以 GitHub 仓库 README 最新内容为准。
源码版本为 v2.0.1，release 下载包含已发布的最新版本。
README 明确提示「只读不等于密钥隔离」，容器进程仍可读取挂载目录中的私钥；使用空的专用 SSH 目录可避免暴露宿主机常规密钥。
claudebox --enable-sudo 会开启 sudo，README 提示需谨慎使用。

核心亮点

用 Docker 隔离 Claude Code，避免 AI 助手直接读写宿主机文件系统和全局依赖
提供预配置开发 profile，省去手动安装语言工具链和运行时的时间
环境可复现，团队或 CI 中能拉起一致的 AI 编码环境

不足之处

依赖 Docker，Windows 或资源受限环境使用门槛较高
项目较新、星标 1155，profile 覆盖的语言和框架可能有限
容器内运行 AI 助手在文件挂载和权限上可能需要额外调试

适用场景

团队统一 Claude Code 开发环境，避免每人本地配置不一致
在远程服务器或 CI 流水线中运行 AI 编码助手
试用 Claude Code 但不想污染本机环境的开发者

替代项目

devcontainers、aider、continue

项目介绍

claudebox 是编程开发领域的开源项目，由 RchGrav 开发，2025 年首次发布。

在全站 12,961 个收录项目中，它的 GitHub 星标数（1,155）位列前 30%，在编程开发分类中处于中上游。

项目目前处于活跃维护状态，最近一次代码更新于 2026-09-22。开源免费，需自行部署 Docker 环境。

它主要面向的使用场景是：团队统一ClaudeCode开发环境，避免每人本地配置不一致。同类可对比的替代方案包括 devcontainers、aider、continue。

上一篇：agent-skills

下一篇：ascend