Claudebox

claudebox

在 Docker 中运行 Claude Code，可通过交互式终端、脚本、HTTP 客户端、MCP、Telegram 或 cron 计划任务启动。Claudebox 在共享的 aicodebox 运行时基础上添加了 Claude 专用配置。

该包装器会挂载当前目录、持久化 Claude 状态和 SSH 密钥，并默认恢复工作区的上一个会话。

**这不是安全沙箱：**标准包装器使用主机网络、挂载主机 Docker 套接字、为 Claude 提供免密码 sudo，并绕过 Claude 的权限提示。仅用于可信工作负载。不同的工作区目录无法隔离不可信租户。服务示例不包含 Docker 套接字。

安装

你需要 Bash、正在运行且对当前用户可访问的 Docker、curl、SSH 密钥生成工具，以及安装包装器所需的 sudo 权限。安装程序会拉取镜像、创建 Claude 状态和 SSH 密钥，并安装 claudebox 命令。

默认的精简镜像：

curl -fsSL https://raw.githubusercontent.com/psyb0t/docker-claudebox/master/install.sh | bash

完整开发镜像：

export CLAUDEBOX_FULL=1 && curl -fsSL https://raw.githubusercontent.com/psyb0t/docker-claudebox/master/install.sh | bash

完整镜像选项会保存在已安装的包装器中。两个版本都会在全新容器首次启动时通过 npm 安装固定版本的 Claude Code CLI，因此首次启动需要网络访问。

如需经过审查的本地安装、自定义命令名称、镜像覆盖设置或包装器更新，请参阅安装和包装器。远程安装程序当前会从其内嵌的发布引用获取包装器，不一定是 master。

首次运行

在 Claude 应当工作的目录中运行：

cd /path/to/project
claudebox

在 Claude Code 中进行身份验证，或者通过环境提供 ANTHROPIC_API_KEY 或 CLAUDE_CODE_OAUTH_TOKEN。claudebox setup-token 会运行 Claude Code 的 OAuth 令牌流程；请将生成的令牌保存在机密存储中，并在需要时导出。

claudebox --no-continue
claudebox -p "explain this codebase"
claudebox -p "review this codebase" --output-format json
claudebox -p "inspect the workspace" --output-format stream-json
claudebox stop

该包装器支持一组明确指定的标志，并非所有 Claude Code 原生参数。有关输出格式、模型选择和会话控制，请参阅程序化模式。

镜像变体

镜像	内容
psyb0t/claudebox:latest	精简版 aicodebox 运行时、Claude 适配器和首次启动配置。
psyb0t/claudebox:latest-full	相同的 Claude 接口，以及 aicodebox 共享的开发工具链。

完整版本增加了 Go 及其工具、Python 和 Node 开发工具、C/C++ 工具、基础设施工具、数据库客户端和 shell 实用工具。共享的 Dockerfile.full 和锁定文件负责管理软件包清单。Claudebox 的两个版本都不会在已发布的镜像中打包 Claude Code CLI。

设置 CLAUDEBOX_IMAGE 以使用明确指定的镜像标签或摘要。现有容器会保留原有镜像和启动配置，直到重新创建。请参阅包装器生命周期。

模式

接口	指南
支持持久会话的交互式终端	交互模式
使用文本、JSON 或原生 NDJSON 输出的单次提示词	编程模式
HTTP /run、文件、异步轮询和 OpenAI 兼容聊天	API 模式
面向其他 Agent 的可流式 HTTP 工具	MCP 模式
聊天工作区、附件和访问列表	Telegram 模式
定时任务和持久化运行产物	Cron 模式

若要获取 HTTP POST /run 发出的所有原生事件，请在请求中设置 "eventMode": "full"。无论是否使用 jsonSchema，此设置均有效。事件包括 Claude Code 发出的记录，例如工具调用、工具结果和可用的思考内容。它不会暴露 CLI 未发出的私有推理。/run 会返回已完成的 JSON 响应；若要直接从 CLI 流式传输，请使用原生 stream-json；若要使用 OpenAI 端点的原生 SSE 事件，请选择启用该功能。

API 和 MCP 的身份验证相互独立。未设置令牌时，对应端点处于开放状态。请同时配置明确的 Telegram 聊天访问权限。在公开服务前，请先使用各模式指南中绑定到回环地址的部署示例。

配置和扩展

• 环境变量：封装器设置、转发的变量、额外挂载和同级容器。
• 自定义：用户脚本、容器首次启动时的初始化钩子、始终启用的技能和外部 MCP 服务。
• GitHub Action：使用只读上下文和可写输出目录执行一次性任务。
• Agent 集成：适用于 Claude Code、Codex 和 OpenClaw 的本地封装器技能与远程 MCP 连接。

在同一命令目录中安装同级的 claudebox、codexbox 和 pibox 封装器，以便进行嵌套启动。每个同级封装器都会挂载各自的主机状态。请勿手动设置 AICODEBOX_HOST_*。

开发

make help
make test-unit
make test-image-select
make test-programmatic-contract
make test-agent-launcher
make build
make build-full

构建时分别使用精简版或完整版本的 aicodebox 父镜像。有关基础镜像覆盖设置和其余检查，请参阅 Makefile。适配器位于 claudebox/claudebox/adapter.py；共享服务器模式位于 aicodebox 中。

迁移和许可证

此前的名称为 docker-claude-code，镜像为 psyb0t/claude-code。当前名称为 docker-claudebox、psyb0t/claudebox 和 claudebox。在 v2 中，latest 改为精简版，latest-full 改为完整版本。迁移历史请参阅 CHANGELOG.md。

WTFPL。