首先，明确几个核心判断：CodeBuddy 的容器启动失败，绝大多数情况下并非源于镜像或代码自身的问题，而是开发环境配置链中某个环节未能成功衔接。你需要确保以下三个关键要素保持同步——Docker 服务确实在运行、Remote-Containers 扩展已被正确启用、.devcontainer 目录结构准确无误。接下来，我们逐步展开详细排查。
检查 Docker 服务与 VS Code 兼容层
CodeBuddy 的容器功能依赖于宿主机上的 Docker 引擎与 Remote-Containers 扩展协同运作，缺少任何一环都会导致卡壳。
- 在终端中运行
docker --version，正常输出应类似Docker version 24.0.7。若提示“command not found”，则需要先安装 Docker Desktop（macOS/Windows）或 Docker Engine（Linux）。 - 接着确认守护进程的运行状态：执行
docker info或sudo systemctl is-active docker（Linux）；Windows 用户可直接查看系统托盘中的 Docker 图标是否为绿色。 - 在 CodeBuddy 中按下
Ctrl+Shift+P（Windows/Linux）或Cmd+Shift+P（macOS），搜索Extensions: Install Extensions，然后安装微软官方发布的 Remote-Containers 扩展——务必认准官方版本，避免使用第三方插件。 - 安装完成后重启 CodeBuddy，状态栏右下角应能看到 Dev Container 图标或可点击的容器状态提示。
验证 .devcontainer 配置是否规范
CodeBuddy 只识别项目根目录下严格命名的 .devcontainer 文件夹。只要拼写错一个点、路径偏差一层，那个“Reopen in Container”提示就不会出现。
- 确认文件夹名称必须为
.devcontainer（开头带有英文句点，不是devcontainer，也不是.devcontainer.json）。 - 该文件夹内必须包含
devcontainer.json，其内容至少应具备"image"或"dockerfile"字段。例如：{"image": "codebuddy/python:3.11"}或{"dockerfile": "Dockerfile"}。 - 如果使用了自定义 Dockerfile，请确保它放置在项目根目录（与
.devcontainer同级），并且语法正确——例如FROM指令有效、基础镜像能够正常拉取。 - 配置完成后，在 CodeBuddy 中通过 File > Open Folder 重新打开项目根目录（而非子文件夹），等待右下角弹出 Reopen in Container 提示。
排查常见干扰因素
如果前两步都已正确执行，但容器仍然无法启动，那么很可能是环境冲突在作祟。
- 关闭其他基于 Electron 的 IDE 或工具（如 QClaw、myclaw 等），它们可能占用端口或干扰进程调度。
- 检查是否手动安装了 VS Code 原生的
Remote-SSH或Dev Containers插件——CodeBuddy 已内置这些功能，额外安装反而会造成冲突，建议卸载后重启。 - 如果出现“Error Opening Container”提示，请打开输出面板（
Ctrl+Shift+U），查看 Remote-Containers 日志，重点查找Failed to connect to Docker或Cannot find image等错误信息，然后根据线索反向排查缺失的组件。 - 临时关闭系统防火墙或安全软件，以排除它们拦截容器网络桥接的可能性。