一分钟看懂
- 装上 Dev Containers 扩展、保持 Docker 运行，对任何带 .devcontainer/ 的仓库执行 Reopen in Container——Claude Code 和它执行的每条命令都发生在容器里，不碰你的机器。
- 官方 feature——features 块里的 "ghcr.io/anthropics/devcontainer-features/claude-code:1.0"——能把 CLI 装进任何 devcontainer；VS Code 还会一并装上扩展，两者共用同一个 ~/.claude。
- 在容器终端里登录；浏览器回调进不了容器时，把代码贴进提示处。再用 ~/.claude 卷挂载加 containerEnv.CLAUDE_CONFIG_DIR，让认证在重建后依然有效。
- dev container 换掉的是整个环境（/sandbox 则是在你本机上约束单条命令）。两者可以叠加——容器管环境，沙箱和权限提示管行为。
Run Your AI Coding Agent in Dev Containers - Complete Beginner's Guide
频道：Visual Studio Code15:39
Step-by-Step: Run Claude Code SAFELY in a Dev Container
频道：Fuzz Puppy6:56
Development containers — official documentation
官方文档：code.claude.com/docs
本页的每个配置步骤、feature 名称和凭据路径，都对照官方 development containers 文档核实过；上面的视频是画面与事实来源。
截图版权归各自创作者所有，并深链到对应时间点；未使用任何人脸镜头。
在 dev container 里跑 Claude Code，一步一步来
第 1 部分 — 前置要求：VS Code 与 Docker
- 1
安装 Dev Containers 扩展
在 VS Code 里打开扩展视图，安装微软的 Dev Containers。状态栏的远程指示器、Reopen in Container 命令、Remote Explorer 都由它带来——下面整个流程都跑在它上面。这一步还不需要 Docker。
Dev Containers 扩展让 VS Code 多出 Reopen in Container——先在扩展视图里把它装上。跳到 2:00 观看 - 2
安装并启动 Docker Desktop
dev container 是货真价实的容器，打开任何东西之前得先有容器引擎在跑。macOS 和 Windows 通常用 Docker Desktop，Linux 用 Docker Engine 即可。启动后保持运行——引擎没起来，是首次 "Opening Remote" 卡住的头号原因。
Docker Desktop 保持运行即可；空空的 Containers 列表正是装容器之前的健康状态。跳到 2:12 观看 - 3
弄清容器给 Claude Code 带来什么
Reopen in Container 之后，VS Code 的服务端跑在容器里——Claude Code 执行的每条命令也一样。安装依赖、跑测试、改文件都留在容器内，工作区文件夹则以挂载方式映射回你的仓库。本机只需要 VS Code 和 Docker；工具链与依赖都在镜像里，agent 再怎么折腾也出不了容器。
第 2 部分 — 从零跑通一个容器
- 4
打开一个现成的 dev container
想最快看到整套机制运转：在 Remote Explorer 里选一个示例，比如 Go dev container。VS Code 会克隆 github.com/microsoft/vscode-remote-try-go 并直接在容器卷里打开——你还一行配置都不用写。
Remote Explorer 自带现成示例——选一个，VS Code 会把仓库直接克隆进容器卷。跳到 2:30 观看 - 5
等 VS Code 构建并连上容器
首次连接会克隆仓库、一层层拉取容器镜像、再把容器跑起来——状态栏会提示 "Connecting to Dev Container"。网速慢时这是整个流程里最久的一步；之后再打开会复用镜像，几秒钟搞定。
首次构建会一层层下载容器镜像；状态栏实时显示与 dev container 的连接进度。跳到 2:52 观看 - 6
确认终端确实在容器里
新开一个终端，打印工具链版本（这里是 go version）。输出会报容器的操作系统和架构，而不是你笔记本的。这个终端就是以后启动 claude 的地方——它执行的任何东西都留在容器内。
go version 打印的是容器里的工具链，不是你笔记本上的——在这个终端里跑 claude，它同样只待在容器内。跳到 3:50 观看 - 7
读懂 devcontainer.json
.devcontainer/devcontainer.json 定义了整个环境：基础镜像（或 Dockerfile）、装进容器的 VS Code 扩展、转发端口、postCreateCommand 初始化命令，以及 remoteUser。对 Claude Code 来说，官方 feature 和凭据卷以后也写在这个文件里——见第 9 步和第 13 步。
容器的全部定义都在 .devcontainer/devcontainer.json：镜像、扩展、转发端口、创建后命令。跳到 4:40 观看 - 8
把 agent 指向工作区
在 agent 面板里挂上 @workspace，让它讲解这个项目。讲解背后的每条命令都在容器里执行。Claude Code 装进镜像之后也是同样的工作方式：@workspace 式的上下文，加上一条都不会跑出容器的命令。
用 @workspace 让 agent 讲解项目——它执行的每条命令都发生在容器里。跳到 5:20 观看 - 9
换上官方 Claude Code feature
不用手动安装：把 "ghcr.io/anthropics/devcontainer-features/claude-code:1.0" 加进 devcontainer.json 的 features 块再重建即可。这个 feature 会装好 CLI——容器在 VS Code 里打开时还会一并装上 Claude Code 扩展，与终端共用同一个 ~/.claude。基础镜像没有 Node.js 时会报 "Failed to install Node.js and npm"：在它上方加 Node feature。CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC、DISABLE_AUTOUPDATER 这类环境配置放进 containerEnv；mounts 还能把本机的其他仓库挂进容器。
- 10
跑起应用，用转发端口访问
在容器里把应用跑起来（调试面板、npm run dev、go run——看技术栈），VS Code 会探测到监听端口：弹出通知让你在本地浏览器打开。服务器从没离开过容器，转发只是让 localhost 照常工作。
应用跑在容器内的 9000 端口；VS Code 自动转发，localhost 用起来和平时一模一样。跳到 6:08 观看
第 3 部分 — 自己的项目与登录
- 11
给自己的项目加上 dev container
在任何仓库里，从命令面板或远程指示器运行 Dev Containers: Add Dev Container Configuration Files，选 "Add configuration to workspace folder"。配置随代码一起提交，队友——以及 Codespaces——就能白拿一个一模一样的环境。
还没有 devcontainer.json？VS Code 能按模板生成——选 workspace，让 git 把配置带给队友。跳到 9:00 观看 - 12
选模板，选 features
VS Code 会按你的技术栈推荐模板（Node.js、Python、Go……），然后给出 features 列表——Git LFS、GitHub CLI 这类可复用的安装器。第 9 步的 claude-code feature 也加在这份列表里。接受默认值（或让 agent 帮你打磨生成的文件），然后重新打开容器。
features 列表就是加 Claude Code feature 的地方——和模板推荐项并列一行。跳到 9:48 观看 - 13
在容器里完成登录
在集成终端里运行 claude，选择登录方式（Claude 订阅或 Anthropic Console）。浏览器在你的宿主机上打开；如果回调进不了容器，就把浏览器里显示的代码贴到 "Paste code here if prompted" 提示处。想让登录在重建后保留：把卷挂载到 ~/.claude，并把 containerEnv.CLAUDE_CONFIG_DIR 设成同一路径——账号文件 ~/.claude.json 在该目录之外，所以两处缺一不可。无人值守或 Codespaces 场景，用 claude setup-token 生成令牌，再传 ANTHROPIC_API_KEY 或 CLAUDE_CODE_OAUTH_TOKEN。
Dev container 还是 /sandbox：你要哪种隔离？
Claude Code 给了两套隔离方案，解决的问题不同。dev container 换掉 agent 所处的整个环境；内置沙箱则约束它在当前机器上执行的命令。官方文档把两者定位为互补——参考容器甚至自带了一个出口限流脚本。
- 1范围。dev container 换掉整个环境——操作系统、工具链、依赖，一切以 devcontainer.json 为准。沙箱保留你的机器，只限制每条 bash 命令能读写哪些文件、能访问哪些网络。
- 2依赖。dev container 需要 Docker（Desktop 或 Engine）加 Dev Containers 扩展；沙箱内置于 Claude Code，两者都不用装。
- 3协作方式。devcontainer.json 随仓库提交，每个队友、每个 Codespace 构建出的环境完全一致；沙箱策略放在 Claude Code 设置里，跟着用户走，不跟着仓库走。
- 4出错半径。在容器里，一次失败的 rm -rf 或一个来路不明的安装只砸到一次性文件系统，宿主机毫发无伤。沙箱以命令为单位追求同样的效果——只是没有容器边界。
- 5项目本身需要环境时选 dev container：多运行时、新人开箱、云端开发。日常在宿主机上的会话用沙箱当护栏。两者可以叠加——在 dev container 里跑 Claude Code，同时保留沙箱和权限提示。
还有一条分界线：/sandbox 是会话级策略，对话中途就能调整；dev container 在会话开始前就定死了——改配置意味着重建。无人值守的批处理任务两边一起上：非 root 容器用户、受限出口网络，--dangerously-skip-permissions 只在容器内使用。
表现不对劲？先看这里
Claude Code 遇到的 dev container 问题大多落在这几类已知模式里。下面的每一个修法都直接来自官方 development containers 文档。
- 1装 feature 时报 "Failed to install Node.js and npm"：基础镜像里没有 Node.js。在 features 块里把 Node feature（ghcr.io/devcontainers/features/node:1）加在 claude-code feature 上方，然后重建。
- 2浏览器里登录成功，容器里却没登上去：OAuth 回调到不了容器。把浏览器里显示的代码复制下来，贴进终端的 "Paste code here if prompted" 提示处。
- 3每次重建后登录和设置都消失：没有任何东西在持久化 ~/.claude。把命名卷挂载到该路径，并把 containerEnv.CLAUDE_CONFIG_DIR 设为同一路径——卷名里带上 devcontainerId 变量，项目之间就不会互串。Codespaces 上该目录在停止/启动后保留、完整重建后被清空，所以改用 secret 提供 ANTHROPIC_API_KEY 或 claude setup-token 生成的 CLAUDE_CODE_OAUTH_TOKEN。
- 4Claude Code 版本出乎意料：claude-code:1.0 锁的是安装脚本版本，不是 CLI——容器里装的仍是最新版并默认自动更新。想锁死版本，就在 Dockerfile 里 npm install -g @anthropic-ai/claude-code@X.Y.Z。
- 5报 "Is Docker running?" 或 "Opening remote" 卡住：引擎不可达——启动 Docker Desktop（或守护进程）再试。--dangerously-skip-permissions 拒绝启动，说明容器在以 root 运行；把 remoteUser 设成 "vscode" 这类非 root 用户。组织还可以通过 /etc/claude-code 下的 managed-settings.json 直接禁用绕过模式。
重建是万能重试：命令面板 → "Dev Containers: Rebuild Container"，改完任何配置都会重新读取 devcontainer.json 并重跑 features。如果重建后的行为和新克隆不一样，删掉容器再重开——镜像和命名卷在删除后依然保留。