VSCode连接Docker容器失败主因是前置条件缺失：必须安装官方Remote-Containers扩展（ID为ms-vscode-remote.remote-containers）、配置正确的.devcontainer/devcontainer.json文件、确保docker CLI可用且当前用户有Docker daemon访问权限，三者缺一不可。
VSCode 连接 Docker 容器，不是装个插件点一下就能通——它卡在前置条件上，90% 的失败都出在这里。
docker CLI 必须可用且当前用户有权限
VSCode 的 Remote-Containers 扩展不启动 Docker 服务，只调 docker 命令。如果终端里 docker info 报 Permission denied 或直接没响应，VSCode 就会卡在 “Cannot connect to the Docker daemon”。
- Linux/macOS：运行
sudo usermod -aG docker $USER后，必须完全退出终端（关掉所有 shell 窗口），再重新登录；newgrp docker不生效 - Windows/macOS：确认 Docker Desktop 正在运行，右上角鲸鱼图标是绿色的；WSL2 后端要启用（不是 Hyper-V）
- 验证命令：
docker run --rm hello-world成功 +docker info --format '{{.OSType}}'返回linux或darwin - 别用
sudo code启动 VSCode——会导致容器内文件 UID 错乱，后续git commit或npm install可能失败
Remote-Containers 扩展必须装对 ID
VSCode 自带的 Docker 扩展、第三方“Remote Containers”同名插件，都不能替代官方扩展。装错或漏装，就等于没装。
在 Linux 上通过 Docker 运行 OpenClaw，并使用 Tailscale 实现远程访问。⚠️ 涉及 sudo、Docker、Tailscale和凭证挂载——请先查阅安全章节...
- 必须安装发布者为
Microsoft、ID 为ms-vscode-remote.remote-containers的扩展 - Docker 扩展（
ms-azuretools.vscode-docker）可选，只用于查看镜像/日志，不参与开发环境接管 - 装完重启 VSCode，然后在命令面板里执行
Remote-Containers: Show Log，能看到初始化日志才算加载成功
.devcontainer/devcontainer.json 是唯一有效配置入口
没有这个文件，VSCode 就不知道该拉哪个镜像、装哪些插件、转发哪些端口——哪怕你本地有 Dockerfile 或 docker-compose.yml，它也视而不见。
- 路径必须是项目根目录下的
.devcontainer/devcontainer.json，不能是devcontainer.json平铺在根目录，也不能是其他名字 -
"image"和"build"必须二选一，不能都空着，也不能同时存在 - 推荐初学者用
"image": "mcr.microsoft.com/vscode/devcontainers/python:3.11"这类微软预置镜像，而不是python:3.11-slim——后者缺bash、git、curl，连pip install都可能失败 - 漏配
"forwardPorts"，Flask 的5000或 React 的3000就不会自动映射到宿主机；漏配"customizations.vscode.extensions"，容器里就只有裸编辑器，没 Python 插件也没 Prettier
容器内用户权限和 UID 匹配是静默故障高发区
VSCode 默认以宿主机当前 UID 启动容器进程。但多数基础镜像只有 root 用户，结果就是：你在编辑器里新建的文件属主是 root:root，而本地 git 以你自己的 UID 运行，git status 会误报 modified，git commit 可能被拒绝。
- 最稳解法是在
devcontainer.json中加"remoteUser": "vscode"和"runArgs": ["--user", "vscode"] - 如果用了自定义
Dockerfile，必须在里面创建该用户：RUN useradd -m -u 1001 -G sudo vscode，再USER vscode - 别依赖
containerUser字段——它只影响 VSCode Server 的写入权限；remoteUser才决定你手动打开终端时的默认用户，一般不用单独设
真正容易被忽略的是：所有这些配置项一旦写错（比如 forwardPorts 拼成 forwordPorts），VSCode 不会明确报错，而是卡在 “Building image…” 或进容器后没终端、没插件、端口打不开——错误日志全藏在 Remote-Containers: Show Log 里，不主动看就永远找不到原因。
