在一個網路受限的 Docker 容器裡執行 Claude Code，讓 AI Agent 可以在隔離環境中讀寫程式碼、執行指令，同時透過防火牆把對外連線限制在少數白名單網域，降低資料外洩與誤操作的風險。
本專案改自 Anthropic 官方的 .devcontainer 參考實作。
.
├── .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
- 用 IDE 開啟此資料夾。
- 按
F1→Dev Containers: Reopen in Container。 - 第一次會建置映像（image）並執行
init-firewall.sh套用防火牆，請稍候。 - 容器開好後，在整合終端機執行：
claude
- 依照指示完成登入即可開始使用。
你的程式碼透過 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
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 或任意網站。 需要時請見下方「調整防火牆」。
devcontainer.json 帶有 --cap-add=NET_ADMIN --cap-add=NET_RAW，讓容器能設定 iptables。這是套用防火牆所必需的。
裡面的權限白名單（permissions.allow）通常含有特定機器的路徑，不建議共用 / commit（一般會放進 .gitignore）。團隊共用的設定請放 .claude/settings.json。
容器隔離與防火牆能降低風險，但仍建議在重要操作前檢視 Claude 的計畫，並善用權限提示。
Agent Skills 是以 SKILL.md 為核心的可安裝知識包，Claude Code 會在任務符合其描述時自動載入。本專案用 skills CLI 安裝：
- 正本放在
.agents/skills/，.claude/skills/以 symlink 指過去（其他 agent 也能共用同一份） skills-lock.json記錄每個 skill 的來源 repo 與內容雜湊- 這些檔案都有進版控，clone 下來就有，不用在容器裡重裝
| Skill | 來源 | 用途 | 在這個容器裡 |
|---|---|---|---|
frontend-design |
anthropics/skills | UI 視覺方向、字體、版面，避免「AI 模板感」 | 純文件，直接可用 |
git-smart-commit |
本專案自訂 | 把雜亂變更拆成多個 conventional commit，與前端無關 | 純文件 |
git-smart-commit不是用 CLI 裝的，所以不在skills-lock.json裡；目前.agents/skills/與.claude/skills/各有一份相同的實體檔案，而不是 symlink。
評估情境是前端網頁專案（例如 feat/yt-comment-digest 分支的 YouTube 留言彙整工具：單檔 HTML/CSS/JS 前端 + Node.js 伺服器），並把這個容器的實際條件一起考慮進去：沒有 GUI、沒有 Python、對外連線受防火牆限制。
結論是只留 frontend-design 負責「畫面該長什麼樣」：純文件、零相依，clone 下來就能用。原本一起裝的五個 skill 已移除：
| 已移除 | 原因 |
|---|---|
browser-use |
與 agent-browser 功能重複；需要 Python 3.12、uv、有 GUI 的桌面 Chrome，容器內都沒有 |
skill-creator |
用來撰寫、評測 skill 本身，與前端開發無關；還帶進 4000 多行 Python 與 HTML |
code-review-expert |
Claude Code 內建的 /code-review、/security-review 已涵蓋 |
find-skills |
只是搜尋工具；npx skills find 走 skills.sh/api/search，防火牆未放行。想用就以 -g 裝到使用者層級 |
agent-browser |
無頭瀏覽器自動化。skill 本身只是指引，實際要在 Dockerfile 另裝 Chromium 與系統函式庫才跑得起來，且尚未在本容器實測；目前專案用不到 |
之後可視需要再加：
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 瀏覽排行榜。
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則可直接重跑該腳本。
基底映像是 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）。