使用claude-code-devcontainer这个沙箱容器（专为在bypassPermissions免确认模式下安全运行 Claude Code 而设计）时，新手最常卡住的一步就是"容器起不来"。本文整理了一套完整的 devcontainer 故障排查清单：从 Docker 运行时自检、devcontainer CLI not found报错，到devc rebuild重建容器、登录向导反复出现等高频问题，全部给出最快解决命令与排查顺序，照着做即可快速恢复。

故障速查表：先按症状定位问题

💡 排查前先对号入座，可以省掉 80% 的摸索时间：

排查前的 3 项基础自检（5 分钟搞定）

1. 确认 Docker 运行时真的在跑

devcontainer 完全依赖 Docker，这是"容器起不来"最常见的原因。任选其一的运行时并确认状态正常：

• Docker Desktop：确认应用已启动（托盘图标显示 Running）
• OrbStack：确认已运行
• Colima：执行colima status，应显示运行中状态

验证方法（任一 Docker 通用命令能执行成功即可）：

docker info

2. 确认 devcontainer CLI 已安装

项目的 install.sh 里有一个检查函数 check_devcontainer_cli，devc的所有命令都依赖它。找不到时报错和修复方式如下：

# 报错：devcontainer CLI not found. # 修复（一次性安装）： npm install -g @devcontainers/cli

3. 确认 .devcontainer/ 模板文件齐全

容器由 4 个核心文件驱动，缺一个都起不来：

如果目录不完整，在目标项目根目录执行一条命令即可重新安装模板并启动容器：

devc .

容器启动过程的 6 个高频故障与解法

故障 1：容器起不来（Container won't start）

这是最高频问题，官方 README 给出的三步法非常有效（见 README.md Troubleshooting 章节）：

1. 检查 Docker 是否运行（对应自检第 1 步）
2. 强制重建容器：

devc rebuild

3. 查看最近一个容器的日志，定位真正报错：

docker logs $(docker ps -lq)

🛠 经验提示：devc rebuild会删除并重建容器，但 devcontainer.json 中定义的命令历史、Claude 配置、gh认证都存放在独立卷里，重建不会丢数据，可以放心执行。

故障 2：devc报 "devcontainer CLI not found"

devc只是个包装脚本，真正干活的是devcontainer命令。安装后即恢复：

npm install -g @devcontainers/cli

另外确认执行devc时当前目录下存在.devcontainer/devcontainer.json，否则先运行devc .安装模板。

故障 3：启动被 SYS_ADMIN 安全检查拦截

install.sh中的 check_no_sys_admin 会主动阻止带SYS_ADMIN能力启动的容器——因为容器内挂载的.devcontainer/是只读的，一旦获得SYS_ADMIN就能把它重挂为可读写，沙箱保护就失效了。

解决办法：检查 devcontainer.json 的runArgs，正常配置只应包含NET_ADMIN和NET_RAW（用于 iptables 网络隔离），删除任何--cap-add=SYS_ADMIN后再启动。

故障 4：post_install.py 没执行，容器"起来了但没配好"

容器每次创建后，由 devcontainer.json 的postCreateCommand触发 post_install.py，它负责：开启bypassPermissions模式、配置 tmux、修复卷的属主、生成 git 配置。如果这一步没跑，典型症状是进入容器后claude的权限模式不对、目录写入报权限错误。

排查思路：执行devc rebuild强制重新触发，观察启动日志中是否出现[post_install] Starting post-install configuration...等输出（脚本所有日志都打到 stderr，可用docker logs看到）。

故障 5：GitHub CLI（gh）认证不持久

如果你用gh登录过，发现重启容器后登录状态丢了，通常是卷目录属主是 root 导致写入失败。在项目目录下执行：

sudo chown -R $(id -u):$(id -g) ~/.config/gh

脚本层面其实有自动修复逻辑 fix_directory_ownership，但如果sudo chown执行失败（比如非 root 权限），就需要手动处理一次。

故障 6：Python / uv 命令不可用

容器内 Python 由uv统一管理（见 Dockerfile），不要直接用pip。正确用法：

uv run script.py # 运行脚本 uv add package # 给项目加依赖 uv run --with requests py.py # 临时带一个依赖运行

如果uv找不到，说明镜像构建不完整，执行devc rebuild重新构建。

容器起来了但"不对劲"：登录向导反复出现

这是该项目最有特色的一个坑：即使凭据有效，Claude Code 在容器里仍会弹出交互式登录向导（上游已知行为）。项目给出的完整解法是Token 免登录（见 README.md Token-Based Auth 章节）：

claude setup-token # 在宿主机执行一次 export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-... # 填入你的 token devc rebuild # 重建容器，token 会被转发进去

原理见 post_install.py：启动时用claude -p完成一次性认证握手，写入.claude.json并打上hasCompletedOnboarding标记，之后claude直接可用。token 通过 devcontainer.json 的remoteEnv从宿主机转发，容器里无需再交互登录。

收尾检查：用 devc destroy 清理孤儿资源

如果反复重建后感觉 Docker 磁盘占用异常增长，多半是手动docker rm留下的孤儿卷和镜像。官方明确建议用devc destroy清理，它能按 label 发现容器、关联卷和镜像并一次性删干净（实现见 install.sh）：

devc destroy # 列出将删除的资源并二次确认 devc destroy -f # 跳过确认直接清理

⚠️ 注意：devc destroy会删掉该项目的 Claude 配置、命令历史、gh认证卷，执行前确认不需要保留数据。

故障排查清单（建议收藏）

按顺序执行，绝大多数"容器起不来"都能在这 8 步内解决：

相关模块路径速查

✅小结：claude-code-devcontainer 的故障排查其实很有章法——先查 Docker 与 CLI 两项基础，再用devc rebuild+docker logs定位启动失败，最后用 Token 免登录和devc destroy处理两类"隐性"问题。把上面的 8 步清单存下来，下次容器起不来时照着走即可。