claude-code-docker-container

在一個有限制的 Docker 容器裡執行 Claude Code，讓 AI Agent 可以在隔離環境中讀寫程式碼、執行指令，同時透過防火牆把對外連線限制在少數白名單網域，降低資料外洩與誤操作的風險。

本專案改自 Anthropic 官方的 .devcontainer 參考實作。

影片教學

影片示範一套「讓 AI 放手做事、又不會失控」的完整流程：先把 Claude Code 關進沙箱，再解開權限限制、補上規格與存檔點，最後把成果部署上線。

目錄

• 影片教學
• 目錄結構
• 需求
• 快速開始
• 這個容器裡有什麼
• 注意事項
• Agent Skills
• 安裝 Plugins
• 調整防火牆（開放更多網域）
• 加入 Python 環境
• 常見問題
• 授權

目錄結構

.
├── .devcontainer/
│   ├── devcontainer.json   # Dev Container 設定（映像、掛載、環境變數、啟動指令）
│   ├── Dockerfile          # 容器映像：Node 24 + 開發工具 + Claude Code CLI
│   └── init-firewall.sh    # 啟動時套用的 iptables/ipset 防火牆規則
├── .agents/
│   └── skills/             # 用 `npx skills add` 安裝的 agent skills（正本，跨 agent 共用）
├── .claude/
│   ├── skills/             # Claude Code 讀取的 skills（多為指向 .agents/skills 的 symlink）
│   └── settings.local.json # 專案層級的本機設定（權限白名單等）
├── skills-lock.json        # skills 的來源與內容雜湊鎖定檔
├── LICENSE
└── README.md

需求

• Docker（Desktop 或 Engine）
• IDE: VS Code、Cursor、Antigravity
• 透過 Extensions 安裝 Dev Containers

快速開始

1. 用 IDE 開啟此資料夾。
2. 按 F1 → Dev Containers: Reopen in Container。
3. 第一次會建置映像（image）並執行 init-firewall.sh 套用防火牆，請稍候。
4. 容器開好後，在整合終端機執行：

   claude
   

5. 依照指示完成登入即可開始使用。

你的程式碼透過 bind mount 掛載在容器內的 /workspace，在容器內的修改會直接反映到本機檔案。

這個容器裡有什麼

由 Dockerfile 建置：

• 基底：node:24，從 AWS ECR Public 的 public.ecr.aws/docker/library/node 拉取。它是 Docker 官方映像的鏡像，內容與 Docker Hub 的 node:24 相同；改用它是因為 Docker Hub 的 registry 位於 AWS 美東，部分台灣網路連線不穩，會讓建置卡在拉取基底映像
• Claude Code CLI：@anthropic-ai/claude-code（版本由 devcontainer.json 的 CLAUDE_CODE_VERSION 控制，預設 latest）
• 開發工具：git、gh（GitHub CLI）、fzf、jq、vim、nano、zsh（含 powerlevel10k）、git-delta
• 網路工具：iptables、ipset、dnsutils、aggregate（防火牆需要）

由 devcontainer.json 設定：

• 預設使用者 node（非 root）
• /workspace：你的專案（bind mount）
• 兩個 named volume，重建容器後仍會保留：
  • /home/node/.claude → Claude Code 的設定、登入狀態、使用者層級 skills
  • /commandhistory → shell 歷史紀錄
• VS Code 預裝擴充套件：Claude Code、ESLint、Prettier、GitLens

注意事項

1. 防火牆會封鎖大部分對外連線

init-firewall.sh 會把 OUTPUT 預設政策設為 DROP，只允許以下白名單網域（其餘一律拒絕）：

• GitHub（api.github.com 動態取得的 IP 範圍）
• registry.npmjs.org（npm）
• api.anthropic.com（Claude）
• sentry.io、statsig.anthropic.com、statsig.com（遙測）
• VS Code Marketplace 相關網域

這代表預設情況下無法存取 PyPI、apt 套件庫、其他 API 或任意網站。 需要時請見下方「調整防火牆」。

2. 需要特殊權限

devcontainer.json 帶有 --cap-add=NET_ADMIN --cap-add=NET_RAW，讓容器能設定 iptables。這是套用防火牆所必需的。

3. .claude/settings.local.json 屬於本機設定

裡面的權限白名單（permissions.allow）通常含有特定機器的路徑，不建議共用 / commit（一般會放進 .gitignore）。團隊共用的設定請放 .claude/settings.json。

4. 沙箱不是萬靈丹

容器隔離與防火牆能降低風險，但仍建議在重要操作前檢視 Claude 的計畫，並善用權限提示。

Agent Skills

Agent Skills 是以 SKILL.md 為核心的可安裝知識包，Claude Code 會在任務符合其描述時自動載入。本專案用 skills CLI 安裝：

• 正本放在 .agents/skills/，.claude/skills/ 以 symlink 指過去（其他 agent 也能共用同一份）
• skills-lock.json 記錄每個 skill 的來源 repo 與內容雜湊
• 這些檔案都有進版控，clone 下來就有，不用在容器裡重裝

目前安裝的 skills

git-smart-commit 不是用 CLI 裝的，所以不在 skills-lock.json 裡；目前 .agents/skills/ 與 .claude/skills/ 各有一份相同的實體檔案，而不是 symlink。

為什麼只留 frontend-design

評估情境是前端網頁專案（例如 feat/yt-comment-digest 分支的 YouTube 留言彙整工具：單檔 HTML/CSS/JS 前端 + Node.js 伺服器），並把這個容器的實際條件一起考慮進去：沒有 GUI、沒有 Python、對外連線受防火牆限制。

結論是只留 frontend-design 負責「畫面該長什麼樣」：純文件、零相依，clone 下來就能用。原本一起裝的五個 skill 已移除：

之後可視需要再加：

• agent-browser（vercel-labs/agent-browser）：無頭瀏覽器自動化，讓 Claude 自己開頁、點擊、截圖驗收 UI。當你希望 Claude 能自己驗收畫面時再加。
• web-design-guidelines（vercel-labs/agent-skills）：100+ 條可及性、效能、表單、深色模式等 UX 規則的稽核清單，純文件、無相依。當你開始在意鍵盤操作、對比度、表單錯誤提示這類細節時再加。
• 若專案改用 React / Next.js：同一個 repo 的 react-best-practices 與 composition-patterns。目前是純 HTML/JS，用不到。
• anthropics/skills 的 webapp-testing（Playwright 測試工具組）：需要 Python、pip install playwright 與從 Playwright CDN 下載 Chromium，三者在容器內都沒有或被防火牆擋住。若你依「加入 Python 環境」一節裝了 Python 並放行相關網域，它是 agent-browser 之外的另一個選擇。

安裝、移除與更新

以下指令在專案根目錄執行，容器內外皆可（add 只連 GitHub 與 npm registry，都在白名單內）：

npx skills add vercel-labs/agent-skills@web-design-guidelines -y   # 之後想加時
npx skills remove <skill-name> -y                                  # 移除

npx skills list      # 列出已安裝的 skills
npx skills check     # 檢查是否有更新
npx skills update    # 更新全部

npx skills find <關鍵字> 會連 skills.sh 搜尋，容器內預設被擋；請在本機執行，或直接到 skills.sh 瀏覽排行榜。

安裝 Plugins

Plugin 透過 marketplace 安裝，需在 claude 互動視窗中操作：

/plugin marketplace add <owner/repo 或 marketplace URL>
/plugin install <plugin-name>
/plugin            # 開啟管理介面

防火牆提醒：marketplace 與 plugin 多半從 GitHub 取得——GitHub 已在白名單內，通常可直接安裝。若 plugin 安裝過程需要存取其他網域（例如自架 registry），請先把該網域加入防火牆白名單（見下節）。

調整防火牆（開放更多網域）

編輯 .devcontainer/init-firewall.sh，在網域解析迴圈加入你需要的網域：

for domain in \
    "registry.npmjs.org" \
    "api.anthropic.com" \
    "pypi.org" \                  # ← 新增：PyPI
    "files.pythonhosted.org" \    # ← 新增：PyPI 套件下載
    "sentry.io" \
    ...

存檔後重新套用（擇一）：

sudo /usr/local/bin/init-firewall.sh   # 在現有容器中重跑
# 或在 VS Code 重建容器：F1 → Dev Containers: Rebuild Container

修改 Dockerfile 或 devcontainer.json 一定要 Rebuild Container 才會生效；只改 init-firewall.sh 則可直接重跑該腳本。

加入 Python 環境

基底映像是 node:24，預設沒有 Python。要使用 Python，編輯 .devcontainer/Dockerfile，在 apt-get install 區塊加入：

RUN apt-get update && apt-get install -y --no-install-recommends \
  less \
  git \
  # ...既有套件... \
  python3 \
  python3-pip \
  python3-venv \
  && apt-get clean && rm -rf /var/lib/apt/lists/*

或使用更快的 uv（以非 root 的 node 使用者安裝）：

USER node
RUN curl -LsSf https://astral.sh/uv/install.sh | sh
ENV PATH="/home/node/.local/bin:$PATH"

重點：別忘了防火牆——安裝 PyPI 套件需要對外連線。請依上一節，把 pypi.org 與 files.pythonhosted.org 加入 init-firewall.sh 白名單，否則 pip install / uv pip install 會逾時失敗。

完成後 Rebuild Container，即可：

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

若需要更完整的 Python 工具鏈，也可考慮在 devcontainer.json 改用官方 Python Dev Container Feature 或直接換成 Python 基底映像。

常見問題

Q：pip install / apt-get install / curl 卡住或逾時？
多半是防火牆擋住了該網域。確認目標網域已加入 init-firewall.sh 白名單並重跑腳本。

Q：重建容器後要重新登入 Claude 嗎？
通常不用——登入狀態存在 /home/node/.claude 這個 named volume，會被保留。

Q：怎麼確認防火牆有生效？
init-firewall.sh 結尾會自我驗證：能連到 api.github.com、且無法連到 example.com 才算通過。可看容器啟動日誌。

Q：時區不對？
在 devcontainer.json 透過 TZ 環境變數設定（預設 America/Los_Angeles），或在本機設定 TZ 環境變數讓它帶入。

Q：npx skills add 在容器裡能用嗎？npx skills find 為什麼沒回應？
add 只連 GitHub 與 npm registry，可以用。find 會連 skills.sh 的搜尋 API，防火牆預設沒放行，請在本機執行或到 skills.sh 瀏覽。

授權

本專案以 MIT License 釋出。.devcontainer 改自 Anthropic 官方 claude-code（同為 MIT）。