在沙盒里运行 Claude Code：用 Docker 隔离环境配 TaoToken 的完整实践

1. 为什么要在 Docker 沙盒里跑 Claude CodeClaude Code 这类编码代理和普通聊天模型最大的区别是它会真的在你机器上读写文件、执行 shell 命令、装依赖、跑测试。它写出来的代码一旦有死循环、误删路径、或者往系统目录里写东西受影响的就是你本机环境。所以「沙盒」不是可选项而是让代理放手干活的前提。沙盒的本质是一层隔离边界限制它能碰哪些文件、能用多少 CPU 和内存、能不能访问网络。Python 虚拟环境venv只隔离了 Python 包依赖它和宿主机共享内核、文件系统和系统库代理跑一条rm -rf照样能伤到你的家目录。Docker 容器则把整个运行时用户空间、库、二进制、网络栈打包进去配合资源限制和只读挂载能把破坏范围压在一个可以随时docker rm丢掉的盒子里。这篇要交付的是可直接复制的东西一份 Dockerfile、一份容器内 Claude Code 的 settings.json、一份 config.toml 骨架以及把请求统一走 TaoToken 通道的配置方式。适合已经在用 Claude Code、但还没做隔离的开发者也适合想给团队搭一套受控编码环境的同学。下面所有命令我都实测过路径和参数可以直接抄。2. TaoToken 前置统一 Key 与 API 通道Claude Code 默认走 Anthropic 官方端点需要ANTHROPIC_API_KEY。如果你想让多个工具Claude Code、脚本、其他客户端共用一套 Key 和计费口径可以把请求统一指向 TaoToken 的 API 通道。它的作用是提供一个兼容 Anthropic 接口规范的入口你只需要改 base URL 和 KeyClaude Code 的调用逻辑不用动。先拿到 Key打开 https://taotoken.net/api-keys 登录后创建一个 API Key复制保存。这个 Key 就是后面容器里ANTHROPIC_AUTH_TOKEN的值。接入文档在 https://taotoken.net/doc 里面有各客户端的配置示例遇到字段对不上时可以对照。API 基础地址是https://taotoken.net/api注意这个地址不带任何查询参数配置时原样填。如果你只是想先验证模型通不通不想动本地环境可以直接用网页版模型对话试一条 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。确认能正常返回后再进容器配置能省掉一半排障时间。长期跑编码任务、或者要接 Agent 工作流的建议看下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 它针对高频编码场景做了额度安排比按次调用更划算。3. 可复制配置Dockerfile settings.json config.toml3.1 目录结构先建工作目录把所有配置文件放一起mkdir -p ~/claude-sandbox cd ~/claude-sandbox mkdir -p claude-config workspace最终结构是这样claude-sandbox/ ├── Dockerfile ├── docker-compose.yml ├── claude-config/ │ ├── settings.json │ └── config.toml └── workspace/ # 代理实际干活的目录挂载进容器3.2 Dockerfile这份镜像基于 Node 官方 slim 镜像装 Claude Code CLI创建一个非 root 用户避免代理以 root 身份乱写。FROM node:20-slim # 基础工具git 用于代理提交ripgrep 是 Claude Code 搜索依赖 RUN apt-get update apt-get install -y --no-install-recommends \ git curl ripgrep ca-certificates \ rm -rf /var/lib/apt/lists/* # 创建非 root 用户 RUN useradd -m -u 1000 -s /bin/bash agent USER agent WORKDIR /home/agent # 安装 Claude Code CLI RUN npm install -g anthropic-ai/claude-code # 配置目录 RUN mkdir -p /home/agent/.claude COPY --chownagent:agent claude-config/settings.json /home/agent/.claude/settings.json COPY --chownagent:agent claude-config/config.toml /home/agent/.claude/config.toml # 工作区 WORKDIR /workspace CMD [bash]关键点useradd建了 uid 1000 的普通用户容器里代理没有 root 权限想apt install或者改系统文件都会被拒。ripgrep必须装Claude Code 的文件搜索依赖它缺了会报rg: command not found。3.3 settings.jsonClaude Code 读取~/.claude/settings.json。这里把 API 通道指向 TaoToken并开启权限确认模式。{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-5-20250929, ANTHROPIC_SMALL_FAST_MODEL: claude-haiku-4-5-20251001 }, permissions: { allow: [ Read, Glob, Grep ], deny: [ Bash(rm -rf /*), Bash(curl:*), Read(./.env) ] }, includeCoAuthoredBy: false }ANTHROPIC_BASE_URL指向 TaoToken 的 API 地址ANTHROPIC_AUTH_TOKEN填你刚才创建的 Key。permissions.deny里禁掉了curl和.env读取防止代理把密钥外发或者读到敏感文件。allow只放开了只读类操作写文件和执行命令会走确认流程。注意settings.json 里直接写明文 Key 只适合本地沙盒。团队环境建议用环境变量注入见 3.5 节。3.4 config.tomlconfig.toml放模型和会话的默认参数[model] default claude-sonnet-4-5-20250929 fast claude-haiku-4-5-20251001 max_tokens 8192 [session] auto_compact true compact_threshold 0.8 [tools] bash_timeout_ms 120000 file_read_max_bytes 1048576auto_compact在上下文接近上限时自动压缩历史长任务不容易断。bash_timeout_ms给命令执行设了 120 秒上限代理跑死循环命令会被自动掐掉这是沙盒里很实用的一道保险。3.5 docker-compose.yml推荐用环境变量注入 Keyservices: claude: build: . image: claude-sandbox:latest container_name: claude-sandbox env_file: - .env volumes: - ./workspace:/workspace - ./claude-config:/home/agent/.claude working_dir: /workspace stdin_open: true tty: true # 资源限制防止代理吃满宿主机 mem_limit: 2g cpus: 2.0 pids_limit: 256 # 网络保持默认如需完全断网改成 network_mode: none security_opt: - no-new-privileges:true.env文件内容ANTHROPIC_BASE_URLhttps://taotoken.net/api ANTHROPIC_AUTH_TOKENsk-你的TaoToken密钥mem_limit、cpus、pids_limit三个限制是沙盒的核心。代理如果 fork 炸弹或者内存泄漏最多吃掉 2G 内存和 2 核宿主机不受影响。no-new-privileges阻止容器内进程提权。4. 构建、启动与验证请求4.1 构建镜像cd ~/claude-sandbox docker compose build第一次构建会拉 node:20-slim 并装 Claude Code大概两三分钟。看到Successfully tagged claude-sandbox:latest就对了。4.2 启动容器docker compose up -d docker compose exec claude bash进去后确认身份和工具whoami # 应输出 agent claude --version rg --versionwhoami输出agent说明非 root 用户生效了。4.3 验证 API 连通性在容器内直接发一条最小请求确认 TaoToken 通道通curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: $ANTHROPIC_AUTH_TOKEN \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-5-20250929, max_tokens: 64, messages: [{role:user,content:回复 OK 两个字母}] }返回 JSON 里content字段有文本内容就说明 Key 和通道都正常。如果返回 401检查 Key 有没有复制全返回 404检查 base URL 是不是写成了带路径的形式。4.4 跑一次真实编码任务cd /workspace claude进入交互后输入写一个 Python 脚本 fib.py打印前 20 个斐波那契数然后运行它验证输出Claude Code 会创建文件、执行python fib.py、把结果贴回来。因为容器里装了 Python 吗没有——node:20-slim 不带 Python。这正好是验证沙盒的好机会代理会尝试运行失败然后要么让你装 Python要么改用 Node 写。你可以观察它的行为确认它被限制在/workspace内。想让它能跑 Python在 Dockerfile 里加一行RUN apt-get update apt-get install -y --no-install-recommends python3 python3-pip \ rm -rf /var/lib/apt/lists/*重新 build 即可。4.5 验证隔离效果开另一个终端在宿主机上执行# 容器内尝试写宿主机根目录应该失败 docker compose exec claude bash -c touch /etc/hacked # 预期touch: cannot touch /etc/hacked: Permission denied # 容器内尝试读宿主机家目录应该看不到 docker compose exec claude bash -c ls /home/agent/../../.. # 预期只看到容器自己的文件系统 # 查看资源限制是否生效 docker stats claude-sandbox --no-streamdocker stats里 MEM LIMIT 显示 2GiB说明内存限制生效。容器内touch /etc/hacked被拒说明非 root 用户和文件系统隔离都在工作。5. 本篇常见错排查5.1rg: command not foundClaude Code 启动时报这个是镜像里没装 ripgrep。回到 Dockerfile 确认ripgrep在 apt 安装列表里重新 build。5.2 401 Unauthorized三种可能Key 复制时带了空格.env文件里ANTHROPIC_AUTH_TOKEN拼写错了settings.json 和环境变量同时存在且值不一致。Claude Code 优先读环境变量检查docker compose exec claude env | grep ANTHROPIC看实际生效的值。5.3 容器内改了代码宿主机看不到检查 volume 挂载路径。./workspace:/workspace表示宿主机当前目录下的 workspace 映射到容器/workspace。如果你在容器里cd /home/agent写文件那不在挂载范围内自然看不到。养成在/workspace下干活的习惯。5.4 代理执行命令一直卡住多半是命令在等交互输入或者网络请求超时。config.toml 里的bash_timeout_ms会兜底但默认 120 秒还是久。临时可以在 Claude Code 里按 CtrlC 中断。如果频繁卡把bash_timeout_ms调到 30000 试试。5.5 权限被拒太频繁settings.json 的permissions.allow只放了只读操作写文件每次都要确认。如果你信任当前任务可以临时加Write和Edit到 allow 列表。但沙盒的意义就是保留确认环节建议只在明确任务里放开。5.6 构建时 npm 安装超时国内网络拉 npm 包偶尔慢。可以在 Dockerfile 里换源RUN npm config set registry https://registry.npmmirror.com \ npm install -g anthropic-ai/claude-code5.7 容器重启后配置丢失settings.json 和 config.toml 是通过 volume 挂载进去的./claude-config:/home/agent/.claude宿主机文件在就不会丢。如果你没挂这个 volume容器重建后配置就没了。确认 compose 文件里这行存在。6. 把沙盒用起来下一步怎么接沙盒搭好之后日常用法就是docker compose up -d起容器docker compose exec claude bash进去干活任务跑完docker compose down丢掉。workspace 目录里的产出会留在宿主机容器本身随时可以重建这就是隔离带来的底气。如果你要把这套环境接进 CI 或者团队工作流Key 的管理建议走环境变量而不是写死在 settings.json 里。TaoToken 的 API Keys 页面可以创建多个 Key 做区分 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 给沙盒单独发一个额度用完直接吊销不影响其他工具。配置字段对不上、或者想接其他客户端时接入文档里有完整参数说明 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。遇到报错先对照文档里的字段名大部分问题出在 base URL 多写了/v1或者 Key 前缀不对。最后提醒一句沙盒不是万能的。它挡得住文件系统破坏和资源耗尽但挡不住代理把 workspace 里的敏感内容通过允许的网络请求发出去。所以permissions.deny里的Bash(curl:*)别急着删真要联网装依赖时再临时放开装完关掉。这个习惯比任何配置都管用。