vscode通过remote-containers扩展将编辑、终端、调试投射进docker容器，代码在宿主机、执行环境在容器内；必须将devcontainer.json置于项目根目录下.devcontainer/子目录中，且需确保docker正常运行、用户已加入docker组、端口转发（forwardports）与用户配置（remoteuser）正确设置。

VSCode 本身不运行 Docker 容器，它靠 Remote-Containers 扩展把编辑、终端、调试全部“投射”进容器里——代码在宿主机，执行环境在容器内，这才是真正可用的容器化开发。

Remote-Containers 扩展装了但点“Reopen in Container”没反应

不是扩展没生效，而是 VSCode 根本没识别到开发容器配置。它只认项目根目录下 .devcontainer/devcontainer.json 这个路径和文件名，少一个字符或放错位置都不行。

• 检查文件是否真在 .devcontainer/devcontainer.json（注意是点开头的隐藏目录，不是 devcontainer.json 直接放在项目根）
• 确认 docker 命令能在 VSCode 内置终端中直接执行：docker --version 和 docker ps 都得成功返回
• Linux 用户常见静默失败：用户没加进 docker 组，执行 sudo usermod -aG docker $USER 后必须完全退出图形会话再重登（newgrp docker 不够）
• Windows/macOS 用户要确保 Docker Desktop 正在运行，且设置里启用了 WSL2 后端（Windows）或 “Use Docker CLI from the terminal”（macOS）

devcontainer.json 里 image 和 build 到底选哪个

选 image 是为了快和稳，选 build 是为了可控和复现——90% 的新项目该从 image 开始。

OpenClaw Docker Setup

在 Linux 上通过 Docker 运行 OpenClaw，并使用 Tailscale 实现远程访问。⚠️ 涉及 sudo、Docker、Tailscale和凭证挂载——请先查阅安全章节...

下载

• 新手/验证阶段直接填 "image": "mcr.microsoft.com/vscode/devcontainers/python:3.11"，这是微软官方维护的镜像，自带 git、curl、make、vscode-server，不会出现 pip install 失败或 command not found
• 想定制才用 "build": { "dockerfile": "Dockerfile" }，但你的 Dockerfile 必须基于 mcr.microsoft.com/devcontainers/base:ubuntu 或至少显式安装 vscode-server，否则容器启动后只有黑屏终端
• 别拿生产镜像硬凑，比如 python:3.11-slim 缺基础工具，node:20-alpine 缺 glibc，连 pip 升级都可能报错

容器里能跑代码，但断点不命中、浏览器打不开 localhost:5000

问题不在代码，而在路径映射和端口暴露没对齐——VSCode 调试器和浏览器看到的“localhost”，默认不等于容器内的网络上下文。

• forwardPorts 必须写，比如 Flask 项目就填 "forwardPorts": [5000]；它让 VSCode 自动做 localhost:5000 → 容器:5000 映射，不写就只能靠 docker port 查端口再手动输
• Python 调试断点不命中？先确认 ms-python.python 插件已声明在 customizations.vscode.extensions 里，再检查 launch.json 中的 pathMappings 是否把 /workspaces/your-project 映射回本地路径
• Node.js 热重载失效？不是 watch 没起作用，而是容器内进程监听的是 0.0.0.0:3000，不是 localhost:3000；改代码时也要在容器终端里执行 npm run dev，别在宿主机终端敲

文件权限混乱、git 提交报 permission denied

默认挂载方式让所有新建文件属主是 root，而你本地 git 配置的用户名 UID 是 1000 ——混着用必然冲突，这不是 bug，是 Docker 默认行为。

• 在 devcontainer.json 里加这两行："remoteUser": "vscode" 和 "runArgs": ["--user", "vscode"]
• 如果用了自定义 Dockerfile，必须在里面创建用户：RUN useradd -m -u 1001 -G sudo vscode，否则 --user 会失败
• 别设 "remoteUser": "root" 图省事，虽然能绕过权限问题，但后续装插件、读写 .vscode 配置都会出意外，尤其配合 features 机制时

最常被跳过的其实是 forwardPorts 和 remoteUser 这两个字段——它们不报错，但会让整个开发流体验断裂：端口不通、文件乱权、调试失联，问题现象分散，排查起来反而更费时间。