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

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

影片教學

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

目錄

• 影片教學
• 目錄結構
• 需求
• 快速開始
• 這個容器裡有什麼
• 注意事項
• Agent Skills
• 調整防火牆（開放更多網域）
• 加入 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

Skill	來源	用途	在這個容器裡
frontend-design	anthropics/skills	UI 視覺方向、字體、版面，避免「AI 模板感」	純文件，直接可用
git-smart-commit	本專案自訂	把雜亂變更拆成多個 conventional commit，與前端無關	純文件

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

編輯 .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 嗎？ 除了第一次要登入外，後續登入狀態會被保留。

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）。