Claude Code Docker: Chạy tác nhân AI trong container

Các tác nhân AI lập trình tự chủ rất mạnh mẽ. Chúng điều hướng hệ thống tệp của bạn, thực thi lệnh shell, tạo commit và sửa đổi tệp mà bạn không cần gõ một dòng mã nào. Tuy nhiên, sức mạnh đó đi kèm một câu hỏi thực tế: điều gì xảy ra nếu có trục trặc? Nếu tác nhân sửa một tệp cấu hình mà lẽ ra không nên đụng vào, hoặc cài một gói xung đột với hệ thống của bạn thì sao?

Câu trả lời mà hầu hết các nhà phát triển thiên về sản xuất lựa chọn là Docker, và đó cũng là câu trả lời tôi liên tục quay lại sau một phiên làm việc mà Claude Code đã "dọn dẹp" tệp .env của dự án vì trông có vẻ không dùng. (Thực ra vẫn đang dùng.) 

Container tạo ra một ranh giới cứng giữa tác nhân và máy chủ của bạn, và chính ranh giới đó khiến các phiên tác nhân không giám sát trở nên an toàn thay vì gây lo lắng. 

Trong hướng dẫn này, tôi sẽ dẫn bạn qua việc chạy Claude Code bên trong Docker: từ xây dựng một image cơ sở tối giản đến điều phối ứng dụng nhiều dịch vụ với Docker Compose. Kết thúc, bạn sẽ có một quy trình làm việc lặp lại được và an toàn cho mọi dự án.

Nếu bạn quan tâm đến các mô hình mới nhất của Anthropic, tôi khuyến nghị đọc các hướng dẫn về Claude Opus 4.6 và Claude Sonnet 4.6.

Cách Claude Code Tích Hợp Với Docker

Để hiểu vì sao Docker rất phù hợp với Claude Code, sẽ hữu ích khi nắm ngắn gọn mỗi công cụ thực sự làm gì.

Claude Code là công cụ lập trình dạng tác nhân qua dòng lệnh của Anthropic, phát hành chính thức vào tháng 5/2025. Nó sống trong terminal của bạn, đọc codebase và thực hiện tác vụ (tái cấu trúc mã, viết kiểm thử, quản lý quy trình git) thông qua lời nhắc ngôn ngữ tự nhiên. Hướng dẫn Claude Code 2.1 toàn diện của chúng tôi bao quát mọi thứ bạn cần biết.

Docker là nền tảng đóng gói và chạy ứng dụng trong các container nhẹ, cách ly, dùng chung nhân hệ điều hành của máy chủ nhưng giữ ranh giới chặt giữa tiến trình và hệ thống tệp. Nếu bạn hoàn toàn mới với Docker, tôi khuyến nghị xem hướng dẫn về nền tảng miễn phí Play with Docker và thử nghiệm tại đó.

Claude Code cần một môi trường để chạy. Docker cung cấp môi trường có thể tái lập và dùng rồi bỏ. Kết hợp này rất mạnh, nhưng để tận dụng tối đa, bạn cần hiểu mô hình thực thi, cấu hình bảo mật mặc định, và cách triển khai nào phù hợp với tình huống của bạn.

Kiến trúc container và luồng thực thi

Bắt đầu với cách một phiên Claude Code được container hóa thực sự hoạt động ở cấp độ yêu cầu.

1. Bạn đưa ra một prompt từ terminal trên máy chủ. 
2. Docker khởi động container có sẵn CLI Claude Code và gắn workspace của bạn làm volume. 
3. Claude Code đọc tệp từ volume đó, suy luận về codebase, thực thi lệnh trong không gian tiến trình cách ly của container và ghi kết quả trở lại volume đã gắn. 
4. Khi phiên kết thúc, hệ thống tệp tạm thời của container (mọi thứ ngoài volume) bị loại bỏ.

Điểm khác biệt then chốt ở đây là giữa trạng thái tạm thời và trạng thái được lưu. Mọi thứ ghi vào container nhưng ngoài volume gắn sẽ bị xóa khi dọn dẹp. Workspace của bạn, vốn nằm trên máy chủ và được gắn vào, thì tồn tại. 

Điều này có nghĩa là các phụ thuộc tạm, hiện vật build và cài đặt công cụ đều biến mất, nhưng tệp dự án thực tế của bạn vẫn giữ nguyên như Claude để lại. Tôi thấy sự tách bạch này thật sự yên tâm: trước khi hiểu điều đó, tôi thường ngồi hồi hộp theo dõi các phiên tác nhân. Giờ tôi khởi chạy một tác vụ và đi pha cà phê.

Mô hình bảo mật và mặc định an toàn

Với luồng thực thi trong đầu, đáng để nói rõ Docker thực sự bảo vệ điều gì và không bảo vệ điều gì.

Cách ly hệ thống tệp là lợi thế bảo mật chính. Claude Code chỉ có thể đọc/ghi tệp trong các đường dẫn bạn gắn rõ ràng. Nếu bạn không gắn chúng vào container, khóa SSH, thông tin xác thực ~/.aws, biến môi trường trên máy chủ và tệp cấu hình hệ thống của bạn sẽ vô hình với tác nhân trừ khi bạn cố ý phơi bày. Tuy nhiên, sự bảo vệ đó chỉ giữ vững nếu bạn cấu hình volume cẩn thận.

Một quy tắc quan trọng: không bao giờ gắn socket Docker của máy chủ (/var/run/docker.sock) vào container Claude Code. Nếu tác nhân có thể nói chuyện với daemon Docker trên máy chủ, nó có thể khởi chạy container đặc quyền, thoát khỏi sandbox hoàn toàn và đạt quyền root trên máy của bạn. 

Đây là một đường leo thang đặc quyền đã biết, không có lý do chính đáng nào. Tôi đã thấy điều này được gợi ý trong một vài Dockerfile cộng đồng để cho phép tác nhân "quản lý container", và mỗi lần thấy, tôi đều muốn gửi tác giả một tin nhắn gay gắt.

Chọn hướng triển khai phù hợp

Ngoài các mặc định bảo mật, còn một quyết định nữa trước khi viết bất kỳ dòng mã nào: mô hình triển khai nào phù hợp với trường hợp sử dụng của bạn? Có ba lựa chọn chính, và chúng không thể thay thế cho nhau.

Với hầu hết tác vụ (chạy tác nhân trên một repo, gỡ lỗi script, tái cấu trúc một mô-đun), một Docker sandbox thuần là mặc định an toàn nhất. 

Docker Compose hợp lý khi Claude Code cần tương tác với cơ sở dữ liệu, API hoặc dịch vụ frontend đang chạy. 

Devcontainer là lựa chọn đúng đắn cho môi trường tiêu chuẩn hóa toàn đội với các tiện ích mở rộng IDE được cấu hình sẵn. Đáng chú ý, devcontainer tham chiếu chính thức của Anthropic có tường lửa tích hợp hạn chế kết nối ra ngoài vào danh sách cho phép tin cậy, và chính sự cách ly đó khiến việc chạy Claude Code với --dangerously-skip-permissions trở nên an toàn cho vận hành hoàn toàn không giám sát. 

Trong hướng dẫn này, chúng ta sẽ đề cập cả sandbox một container và thiết lập Compose.

Thiết Lập Docker Container Cho Claude Code

Giờ khi kiến trúc và lựa chọn triển khai đã rõ, hãy đảm bảo môi trường được cấu hình đúng trước khi viết mã. Tôi đã thấy bước này bị bỏ qua vô số lần, và đó là lý do phổ biến nhất khiến các hướng dẫn như thế này hỏng giữa chừng.

Yêu cầu hệ thống và phần mềm

Dưới đây là mọi thứ bạn cần có trước lệnh docker build đầu tiên:

• Docker Desktop (macOS hoặc Windows) hoặc Docker Engine (Linux), với daemon đang chạy. Trên macOS và Windows, phải bật ảo hóa trong thiết lập BIOS/firmware. Trên Linux, thêm người dùng của bạn vào nhóm docker với sudo usermod -aG docker $USER, hoặc tiền tố mọi lệnh Docker bằng sudo.

• Node.js v18 trở lên trên máy chủ của bạn, vì CLI Claude Code là một gói npm. Xác nhận bằng node --version.

• Một khóa API Anthropic, bạn có thể tạo trong Claude Console.

Xác minh Docker hoạt động khỏe với một kiểm tra nhanh trước khi đi tiếp:

docker run --rm hello-worldĐược hỗ trợ bởi

Nếu bạn thấy Hello from Docker!, daemon phản hồi đúng và bạn có thể tiếp tục.

Xác thực và biến môi trường

Khi đã xác nhận daemon khỏe, điều tiếp theo cần làm đúng là thông tin xác thực. Truyền khóa API Anthropic của bạn như một biến môi trường lúc chạy an toàn hơn nhiều so với đăng nhập tương tác bên trong container. 

Tôi học điều này theo cách khó: đăng nhập tương tác có thể khắc thông tin xác thực vào các lớp image của container hoặc tệp lịch sử shell, tồn tại trên đĩa rất lâu sau khi bạn quên chúng.

Mẫu chuẩn là truyền khóa lúc chạy bằng -e:

docker run --rm -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" my-claude-imageĐược hỗ trợ bởi

Lưu ý tôi đang tham chiếu $ANTHROPIC_API_KEY từ shell máy chủ. Khóa không bao giờ được ghi vào Dockerfile, không bao giờ commit vào kiểm soát phiên bản, và không xuất hiện trong bất kỳ lớp image nào. Thiết lập một lần trong hồ sơ shell của bạn (~/.zshrc hoặc ~/.bashrc), và nó sẽ chảy gọn vào mọi lần chạy container sau đó.

Khởi tạo workspace

Khi xác thực đã ổn, bước thiết lập cuối là tạo một workspace sạch. Tôi luôn tạo một thư mục riêng cho mỗi phiên tác nhân thay vì trỏ Claude vào một dự án có sẵn, vì nó loại bỏ rủi ro tác nhân đi lạc vào mã bên cạnh mà bạn không định cho phép chạm tới.

mkdir ~/claude-docker-tutorial
cd ~/claude-docker-tutorial
echo "# My Project" > README.md
echo "def hello(): return 'world'" > app.pyĐược hỗ trợ bởi

Giữ thư mục này sạch. Đừng sao chép tệp .env thật hay bất kỳ thông tin xác thực nào vào đây. Workspace chỉ nên chứa mã bạn muốn tác nhân làm việc, và không gì khác. Với điều đó, chúng ta sẵn sàng build.

Chạy Claude Code Trong Docker

Với môi trường đã cấu hình và khái niệm đã rõ, đến lúc xây dựng. Phần này đi qua các bước: trước tiên, image tối thiểu một container, sau đó một phiên sandbox hoạt động, và cuối cùng là một stack Compose đa dịch vụ đầy đủ. Mỗi bước xây trên bước trước, nên tôi khuyến nghị theo thứ tự thay vì nhảy cóc.

1. Xây dựng image container cơ sở

Mọi thứ trong phần này dựa trên các nguyên tắc bảo mật đã bàn. Đây là Dockerfile tối giản áp dụng những nguyên tắc đó, cài CLI Claude Code trên image Node.js slim:

FROM node:20-slim

# Create a non-root user for safer execution
RUN useradd -m -u 1001 claude

# Install Claude Code CLI globally
RUN npm install -g @anthropic-ai/claude-code

# Set the working directory
WORKDIR /workspace

# Switch to non-root user
USER claude

ENTRYPOINT ["claude"]Được hỗ trợ bởi

Một vài quyết định thiết kế đáng giải thích. Tôi dùng node:20-slim thay vì node:20-alpine vì Alpine dùng thư viện libc musl, đôi lúc gây vấn đề tương thích với các gói npm native. 

Tôi gặp đúng vấn đề này ở lần thử đầu với Alpine: CLI Claude Code cài được, nhưng sập ngay lần chạy đầu với lỗi liên kết mơ hồ mà mất cả giờ tôi mới lần ra do musl. 

Biến thể slim dựa trên Debian: gọn nhẹ và ổn định, không drama. Ngoài ra, tôi tạo người dùng claude riêng và chuyển sang trước entrypoint, nghĩa là tiến trình tác nhân chạy không có đặc quyền root và bị hạn chế ngay cả trong container.

Build image bằng:

docker build -t claude-code:latest .Được hỗ trợ bởi

Ở lần build đầu, Docker kéo image cơ sở và cài CLI. Ở các lần sau không đổi Dockerfile, bạn sẽ thấy “CACHED” cạnh mỗi layer, giúp rebuild gần như tức thời khi nền tảng đã thiết lập.

2. Khởi chạy phiên sandbox cách ly

Khi image đã sẵn, đến lúc chạy phiên thực đầu tiên. 

Tác vụ chỉ đọc

Với tác vụ chỉ đọc như liệt kê hay tóm tắt tệp, lệnh cơ bản là đủ:

docker run --rm \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  -v $(pwd):/workspace \
  claude-code:latest \
  "List the files in this workspace and describe what each one does."Được hỗ trợ bởi

Tham số -v $(pwd):/workspace gắn thư mục hiện tại vào container, nên lệnh hoạt động từ bất kỳ thư mục dự án nào. Cờ --rm tự động xóa container sau khi thoát.

Tác vụ ghi

Tác vụ ghi cần thêm hai cờ. 

Cờ -u $(id -u):$(id -g) truyền UID và GID của người dùng trên máy chủ vào container, cho tiến trình claude quyền ghi vào tệp đã gắn. Thiếu nó, bạn sẽ gặp lỗi hệ thống tệp chỉ đọc vì người dùng claude trong container không khớp quyền sở hữu tệp trên máy chủ. 

Cờ --dangerously-skip-permissions bỏ qua các lời nhắc phê duyệt tương tác của Claude Code, vốn cần khi chạy không tương tác trong container. Chính ranh giới Docker khiến điều này an toàn.

docker run --rm \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  -v $(pwd):/workspace \
  -u $(id -u):$(id -g) \
  claude-code:latest \
  --dangerously-skip-permissions \
  "Add a docstring to the hello function in app.py."Được hỗ trợ bởi

Thao tác ghi của Claude Code trên Docker

Sau đó kiểm tra tệp cục bộ: cat app.py. Nếu bạn thấy docstring, volume mount hoạt động hai chiều, và bạn sẵn sàng mở rộng lên thiết lập đa dịch vụ.

3. Điều phối ứng dụng nhiều dịch vụ

Sandbox một container hoạt động tốt cho tác vụ cách ly, nhưng phát triển thực tế thường liên quan nhiều dịch vụ chạy đồng thời. Đây là lúc Docker Compose phát huy vai trò.

Cấu hình dưới đây liên kết tác nhân Claude Code với dịch vụ web và cơ sở dữ liệu PostgreSQL, một thiết lập tiêu biểu cho nhiều dự án backend:

services:
  claude:
    build: .
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    volumes:
      - ./workspace:/workspace
    depends_on:
      db:
        condition: service_healthy
    networks:
      - app-network

  web:
    image: python:3.12-slim
    working_dir: /app
    volumes:
      - ./workspace:/app
    command: python -m http.server 8080
    ports:
      - "8080:8080"
    networks:
      - app-network

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: appdb
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user -d appdb"]
      interval: 5s
      timeout: 3s
      retries: 5
    networks:
      - app-network

networks:
  app-network:
    driver: bridgeĐược hỗ trợ bởi

Lưu ý version được lược bỏ vì đã lỗi thời trong Docker Compose hiện đại và sẽ tạo cảnh báo nếu thêm vào. 

Hai chi tiết khác đáng lưu ý:

Thứ nhất, dịch vụ claude gắn .:/workspace (thư mục hiện tại) thay vì thư mục con. Dùng ./workspace sẽ đòi thư mục con riêng tồn tại, và tác nhân sẽ thấy workspace trống. 

Thứ hai, DATABASE_URL được truyền rõ ràng để tác nhân biết cách truy cập Postgres. Không có nó, Claude không có chuỗi kết nối và sẽ hỏi bạn.

Dòng user: "${UID}:${GID}" áp dụng cùng việc ghi đè UID/GID máy chủ như chúng ta dùng trong lệnh docker run độc lập, để ghi tệp hoạt động đúng. Xuất cả hai trước khi chạy:

export UID=$(id -u) GID=$(id -g)Được hỗ trợ bởi

Dịch vụ claude không có command chạy liên tục, nên khác với web và db, nó không nhằm chạy thường trực. Khởi động các dịch vụ hỗ trợ trước, rồi gọi Claude theo nhu cầu bằng docker compose run:

# Start the database and web service
docker compose up -d web db

# Run a one-off Claude task
docker compose run --rm \
  claude \
  --dangerously-skip-permissions \
  "Check the database connection and summarize the schema in README.md."Được hỗ trợ bởi

Claude Code với Docker Compose

Khởi động dịch vụ hỗ trợ trước bằng docker compose up -d web db, sau đó theo dõi log với docker compose logs -f. Lưu ý depends_on với condition: service_healthy. 

Tôi đã bỏ qua điều này ở một dự án sớm và mất 20 phút đuổi theo lỗi kết nối cơ sở dữ liệu trước khi nhận ra Claude khởi chạy trước khi Postgres sẵn sàng. Health check không tốn gì và tránh đúng cơn đau đầu đó.

4. Quản lý dọn dẹp phiên

Khi phiên hoàn tất, dọn dẹp quan trọng không kém thiết lập. Container mồ côi tiêu tốn bộ nhớ và can thiệp các lần chạy sau, và theo kinh nghiệm của tôi, đây là bước nhiều nhà phát triển bỏ qua cho đến khi có gì đó ứng xử kỳ lạ.

Đây là các lệnh bạn sẽ dùng nhiều nhất, và khi nào nên dùng:

Tham số -v trên docker compose down là điều cần cẩn trọng. Nó xóa các volume đặt tên, nghĩa là mọi dữ liệu cơ sở dữ liệu bạn đã tích lũy trong Postgres sẽ mất. Tôi chỉ dùng khi thực sự muốn làm sạch hoàn toàn. Còn lại chỉ docker compose down là đủ.

Tích Hợp Và Khắc Phục Sự Cố Claude Code Docker

Khi quy trình cốt lõi chạy trơn tru, hãy xem cách mở rộng và cách gỡ lỗi khi có sự cố.

Tích hợp mô hình cục bộ và tiện ích mở rộng

Claude Code hỗ trợ chuyển hướng suy luận tới bất kỳ endpoint cục bộ tương thích Anthropic nào qua ANTHROPIC_BASE_URL. Docker Model Runner, tích hợp trong Docker Desktop, cung cấp đúng API như vậy, khiến tích hợp trở nên bản địa trong hệ sinh thái Docker.

Kéo một mô hình và trỏ Claude Code vào endpoint cục bộ:

docker model pull ai/smollm2
ANTHROPIC_BASE_URL=http://localhost:12434 claude --model ai/smollm2 "List the files of the repository."Được hỗ trợ bởi

Đây là mẫu khác với cách sandbox container đã đề cập. Ở đây, Claude Code chạy trên máy chủ của bạn, và suy luận ở lại cục bộ thông qua Docker Model Runner, nên không có cuộc gọi API nào rời khỏi máy.

Ngoài mô hình cục bộ, bạn có thể mở rộng khả năng của Claude Code thông qua máy chủ MCP (Model Context Protocol). Nếu bạn chưa quen, Hướng dẫn MCP của chúng tôi là tài nguyên tuyệt vời để bắt đầu.

Bộ công cụ MCP của Docker cung cấp hơn 200 máy chủ MCP dựng sẵn, đóng gói trong container bao phủ GitHub, Jira, Supabase và hơn thế nữa, cho Claude Code quyền truy cập có phân quyền vào các công cụ đó mà không phơi bày thông tin xác thực API thô. 

Cùng nhau, hai điểm mở rộng này cho bạn quyền kiểm soát có ý nghĩa cả nơi diễn ra suy luận và những dịch vụ bên ngoài mà tác nhân có thể tiếp cận.

Tối ưu hiệu năng build

Khi Dockerfile của bạn phình to, thời gian build có thể trở thành nút thắt. Build nhiều giai đoạn khắc phục bằng cách tách cài đặt khỏi image runtime:

# Build stage
FROM node:20-slim AS builder
RUN npm install -g @anthropic-ai/claude-code

# Runtime stage
FROM node:20-slim
COPY --from=builder /usr/local/lib/node_modules /usr/local/lib/node_modules
COPY --from=builder /usr/local/bin/claude /usr/local/bin/claude
RUN useradd -m -u 1001 claude
USER claude
WORKDIR /workspace
ENTRYPOINT ["claude"]Được hỗ trợ bởi

Thứ tự layer quan trọng không kém cấu trúc, và đây là điều tôi đã làm sai lâu hơn mình muốn thừa nhận. 

Các chỉ thị ít thay đổi (như cài gói hệ thống) đặt gần đầu. Những phần thay đổi thường xuyên (như sao chép mã nguồn) đặt gần cuối. Điều này tối đa hóa khả năng cache và biến các lần rebuild 30 giây thành gần như tức thời.

Gỡ lỗi các lỗi tích hợp phổ biến

Ngay cả với thiết lập tốt, sự cố vẫn xảy ra. Dưới đây là vòng lặp gỡ lỗi lặp lại được cho những vấn đề tôi thường gặp. Triệu chứng trước, rồi lệnh cần chạy:

• Bị chặn truy cập mạng ra: Claude Code không thể tới API Anthropic. Chạy docker run --rm alpine wget -qO- https://api.anthropic.com để xác minh truy cập ra ngoài. Nếu lỗi, kiểm tra docker network inspect bridge xem cấu hình proxy.

• Gắn volume sai: Claude Code báo không tìm thấy tệp. Chạy docker run --rm -v $(pwd):/workspace alpine ls /workspace. Danh sách rỗng nghĩa là đường dẫn sai. Xác nhận thư mục tồn tại trước hết.

• Bộ nhớ đệm build cũ: Bạn cập nhật Dockerfile nhưng hành vi không đổi. Ép rebuild đầy đủ bằng docker build --no-cache -t claude-code:latest ..

• Lỗi kết nối giữa dịch vụ trong Compose: Một dịch vụ không tới được dịch vụ khác. Dịch vụ liên lạc qua tên dịch vụ (db, web), không phải localhost. Chạy docker compose exec web ping db để thử khả năng tiếp cận. Ping thất bại nghĩa là các dịch vụ không ở cùng mạng.

Kết luận

Chạy Claude Code bên trong Docker mang lại điều thực sự giá trị: tự do để một tác nhân tự chủ làm việc thoải mái, biết rằng những gì nó có thể chạm tới được giới hạn chặt chẽ. 

Trong hướng dẫn này, tôi đã đi qua việc xây dựng image không root tối giản, quản lý volume workspace, điều phối ứng dụng nhiều dịch vụ với Docker Compose, và chẩn đoán các lỗi tích hợp phổ biến nhất. 

Thiết lập mất của tôi khoảng một buổi chiều để làm đúng, và nó hoàn toàn thay đổi cách tôi tiếp cận phát triển có trợ giúp tác nhân. Tôi ủy thác cả tác vụ thay vì dõi theo từng bước, và ranh giới Docker là điều khiến điều đó khả thi.

Từ đây, hai hướng đáng khám phá:

Thứ nhất, tìm các mẫu devcontainer cho đội của bạn. Devcontainer tham chiếu Claude Code trên GitHub bao gồm tường lửa cấu hình sẵn hạn chế kết nối ra ngoài tới miền tin cậy. Thứ hai, thử nghiệm với Docker MCP Toolkit để cho Claude Code quyền truy cập có cấu trúc vào các công cụ hiện có của bạn: GitHub, cơ sở dữ liệu, hệ thống quản lý dự án, và hơn thế nữa.

Cuối cùng, hãy đặt lời nhắc cập nhật image cơ sở định kỳ. Docker image tích lũy lỗ hổng theo thời gian, và một lệnh docker pull node:20-slim rồi rebuild chỉ mất vài phút.

Nếu bạn quan tâm phát triển ứng dụng AI, tôi rất khuyến nghị ghi danh vào lộ trình kỹ năng AI Engineering with LangChain. Các khóa học trong đó là AI-native, vì vậy bạn sẽ có một gia sư cá nhân đồng hành đúng trình độ hiện tại và giúp bạn đạt mục tiêu với tốc độ phù hợp.