Claude Code: Giới hạn 30 phút cho lệnh chạy nền

Claude Code dừng lệnh chạy nền sau 30 phút khi lệnh chạy không có người giám sát: chạy với cờ -p, ứng dụng Agent SDK, tác vụ CI hoặc phiên trên đám mây. Nếu Claude đặt thời gian cho chính lệnh đó, lệnh sẽ chạy tối đa 2 giờ, trong khi thiết bị đầu cuối thông thường, ứng dụng máy tính để bàn và VS Code không còn giới hạn này kể từ phiên bản 2.1.288.

Trước đây, tôi ngồi trước màn hình cả ngày: giao cho tác tử một bước, xem kết quả, chỉnh sửa rồi yêu cầu tiếp tục. Cứ hết giai đoạn này đến giai đoạn khác. Máy có thể viết mã, nhưng tôi mới là người điều khiển nó. Giờ đây, tôi viết kế hoạch, chia kế hoạch thành các giai đoạn, giao phần triển khai cho các tác tử phụ làm qua đêm rồi rời đi. Trong 8 giờ không có tôi, Claude thực hiện kế hoạch: nghiên cứu, xây dựng và hoàn thiện. Buổi sáng, tôi dành nhiều thời gian nghiệm thu công việc hơn là làm lại từ đầu.

Nhưng nếu lượt chạy qua đêm dùng -p, chạy theo lịch trên máy chủ, trong CI hoặc trên đám mây, thì máy chủ phát triển và bản dựng chạy nền chỉ hoạt động được 30 phút. Sau đó Claude Code sẽ dừng chúng và công việc qua đêm sẽ bị gián đoạn giữa chừng. Tôi sẽ giải thích giới hạn này ảnh hưởng đến ai, cách tăng giới hạn và việc cần làm nếu lệnh đã dừng. Bắt đầu nhé.

Để được trợ giúp sử dụng dịch vụ, hãy xem tài liệu Ailoot.

Giới hạn này ảnh hưởng đến ai#

Lệnh chạy nền là lệnh Claude khởi chạy rồi để đó trong khi bận làm việc khác. Ví dụ: máy chủ phát triển được khởi chạy bằng npm run dev hoặc bản dựng theo dõi các thay đổi của tệp.

Tài liệu Claude Code cho biết:

Nói cách khác, giới hạn này áp dụng khi bạn không có mặt: lượt chạy có -p, ứng dụng Agent SDK, tác vụ CI hoặc phiên trên đám mây. Không có giới hạn trong thiết bị đầu cuối, ứng dụng máy tính để bàn hoặc VS Code khi bạn tự làm việc trong phiên. Giới hạn được đưa vào từ phiên bản 2.1.285 và áp dụng ở mọi nơi trước phiên bản 2.1.288.

Cách xác định liệu điều này có áp dụng với bạn hay không:

• Bạn mở Claude Code trong thiết bị đầu cuối hoặc VS Code, giao cho nó một nhiệm vụ rồi đi ngủ. Không có giới hạn nếu phiên bản là 2.1.288 trở lên. Trong các phiên bản 2.1.285 đến 2.1.287, giới hạn này cũng áp dụng ở đây. Tôi đã giải thích cách cập nhật lên phiên bản mới nhất trong một bài viết riêng.
• Claude Code được khởi chạy bằng claude -p "task" theo lịch, từ ứng dụng Agent SDK của riêng bạn hoặc trong CI. Giới hạn này áp dụng.
• Nhiệm vụ chạy trong một phiên trên đám mây. Giới hạn này áp dụng.

Khi giao cho các tác tử làm việc độc lập, tôi đưa yêu cầu này vào lời nhắc: “Ghi các điều kiện này và lý do dừng vào kế hoạch làm việc. Kiểm tra để chắc chắn quy trình không phụ thuộc vào cửa sổ mà tôi sẽ đóng hoặc vào chính máy tính.” Giới hạn 30 phút là một trong những lý do đó.

Lệnh chạy nền hoạt động trong bao lâu#

Đồng hồ đếm ngược bắt đầu khi lệnh chuyển sang chế độ nền. Có 2 trường hợp.

Claude khởi chạy lệnh ở chế độ nền ngay lập tức. Lệnh có 30 phút. Nếu Claude chỉ định thời gian khi khởi chạy lệnh (tham số timeout), lệnh có thời gian đó, nhưng không quá 2 giờ.

Lệnh chưa hoàn tất trong lúc Claude chờ. Claude chờ một lệnh thông thường trong 2 phút. Nếu lệnh vẫn chưa hoàn tất, Claude Code không dừng lệnh mà chuyển lệnh sang chế độ nền. Kể từ thời điểm đó, lệnh có 30 phút.

Khi hết thời gian, Claude Code dừng lệnh và thông báo cho Claude:

Background command "<description>" was stopped after reaching its background time limit

Nếu công việc chưa xong, Claude có thể chạy lại lệnh với thời gian dài hơn.

Và thêm một điểm về -p. Với kiểu chạy này, các lệnh nền sẽ kết thúc khoảng 5 giây sau câu trả lời cuối cùng của Claude. Máy chủ được khởi chạy trong lượt chạy qua đêm bằng -p chỉ hoạt động chừng nào lượt chạy còn diễn ra. Giới hạn 30 phút quan trọng khi lượt chạy kéo dài hơn: Claude khởi động máy chủ lúc đầu rồi dành một giờ chạy các lượt kiểm tra trên máy chủ đó.

Cách tổ chức công việc qua đêm trong Claude Code#

Tôi đã chán việc phải điều khiển tác tử cả ngày, nên thay bằng một lời nhắc điều phối duy nhất. Tôi khởi chạy lời nhắc đó vào buổi tối, rồi Claude làm việc suốt đêm, lần lượt thực hiện các giai đoạn: viết, kiểm tra, sửa lỗi và tự commit.

Các nhóm tác tử phụ viết mã, mỗi nhóm có tệp riêng để không cản trở nhau. Một nhóm mới khác sẽ nghiệm thu công việc: rà soát mã, kiểm tra bảo mật và kiểm tra trực tiếp. Nếu phát hiện vấn đề, nhóm sẽ sửa ngay rồi chạy lại các bước kiểm tra. Lời nhắc có dòng: “Nếu hết ngữ cảnh, hãy ghi lại trạng thái; lượt chạy tiếp theo sẽ tiếp tục.”

Trong ví dụ được mô tả, trong 3 ngày, 8 trong số 14 giai đoạn đã hoàn tất theo cách này.

Chỉ cần lưu ý 2 điều. Trình điều phối không thể suy nghĩ thay bạn: trước tiên, hãy viết kế hoạch chi tiết có các giai đoạn, sau đó mới bắt đầu ca làm việc qua đêm. Cách này cũng tiêu tốn nhiều hạn mức đăng ký, nên không đáng thiết lập cho một nhiệm vụ nhỏ. Luôn giới hạn số lần thử, nếu không tác tử sẽ dùng hết hạn mức đăng ký của bạn trong đêm. Tôi đã giải thích cách đặt giới hạn chi tiêu trong một bài viết riêng.

Cách tăng giới hạn#

Lựa chọn 1: yêu cầu Claude. Claude chọn thời gian cho một lệnh cụ thể; bạn không tự đặt thời gian đó. Nhưng bạn có thể ghi trong nhiệm vụ: “Giữ máy chủ phát triển chạy nền trong 2 giờ.” Bằng cách này, bạn không thể vượt quá 2 giờ.

Lựa chọn 2: dùng biến trong tệp cài đặt. Giá trị được tính bằng mili giây. Bạn không thể hạ giới hạn xuống dưới 30 phút và 2 giờ; chỉ có thể tăng chúng.

• BASH_DEFAULT_TIMEOUT_MS nếu được đặt cao hơn 1800000 (30 phút) thì thời gian mặc định 30 phút sẽ thay đổi. Biến này áp dụng cho cả các lệnh Claude khởi chạy ở chế độ nền mà không chỉ định thời gian lẫn các lệnh được chuyển sang chế độ nền sau khi hết thời gian chờ. Nếu đặt cao hơn 7200000 (2 giờ), mức trần cũng tăng.
• BASH_MAX_TIMEOUT_MS nếu được đặt cao hơn 7200000 thì mức trần 2 giờ sẽ tăng. Biến này không thay đổi thời gian mặc định 30 phút: lệnh không có thời gian được chỉ định riêng vẫn sẽ dừng sau 30 phút.

BASH_DEFAULT_TIMEOUT_MS có một tác dụng phụ. Cùng biến này cũng đặt thời gian Claude chờ một lệnh thông thường trước khi chuyển lệnh sang chế độ nền. Đặt thành 1 giờ thì Claude sẽ chờ 1 giờ thay vì 2 phút. Điều đó không gây trở ngại vào ban đêm. Ban ngày, bạn sẽ phải chờ phản hồi lâu hơn khi lệnh mất nhiều thời gian.

Nếu bạn không muốn tìm hiểu chi tiết: nếu cần 3 giờ cho cả lệnh thông thường lẫn mức trần, hãy đặt BASH_DEFAULT_TIMEOUT_MS thành 10800000. Như vậy là đủ; bạn không cần biến thứ hai.

Tệp cài đặt nằm trong thư mục .claude trong thư mục chính của bạn: ~/.claude/settings.json trên macOS và Linux, và %USERPROFILE%\.claude\settings.json trên Windows. Nếu tệp chưa tồn tại, hãy tạo tệp. Giới hạn 1 giờ trông như sau:

{
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "3600000"
  }
}

Nếu tệp đã có khối env, hãy thêm dòng này vào đó. Phiên đang chạy sẽ nhận giá trị mới khi bạn lưu tệp. Việc xóa một biến chỉ có hiệu lực vào lần tiếp theo bạn khởi chạy claude.

Tệp phải nằm trên máy đang chạy tác tử. Để tác tử làm việc qua đêm, máy tính không được chuyển sang chế độ ngủ. Ngoài ra, bạn có thể chạy Claude Code trên một máy chủ từ xa và đặt cấu hình ở đó.

Nếu lệnh đã dừng#

Bạn không cần tự làm gì cả. Claude Code cho Claude biết lý do lệnh dừng, vì vậy trước tiên bạn chỉ cần hỏi Claude chuyện gì đã xảy ra.

Sau đó, hãy làm từng bước:

1. Một lượt chạy dài duy nhất, tối đa 2 giờ. Yêu cầu Claude chạy lại lệnh với thời gian dài hơn.
2. Lệnh thường xuyên cần hơn 30 phút. Đặt BASH_DEFAULT_TIMEOUT_MS cao hơn 1800000 trong tệp cài đặt, như ví dụ phía trên. Nếu cần hơn 2 giờ, hãy đặt thêm BASH_MAX_TIMEOUT_MS cao hơn 7200000 trong tệp đó.
3. Chạy lại lệnh. Tài liệu không đảm bảo điều gì sẽ xảy ra với lệnh đã chạy nền trước khi thay đổi cấu hình.
4. Kiểm tra kết quả của lượt chạy tiếp theo. Nếu báo cáo của Claude lại có cụm từ “stopped after reaching its background time limit”, thì cấu hình chưa áp dụng cho lệnh đó.

Tác tử phụ và quy trình giúp tác tử tiếp tục làm việc khi bạn vắng mặt.

Tôi đã giải thích cách cho tác tử chạy theo vòng lặp suốt đêm trong một bài viết riêng. Còn cách cấu hình Claude Code để nó không làm hỏng dự án trong đêm được giải thích tại đây.

Hãy kiểm tra bước nào khiến lượt chạy qua đêm của bạn dừng lại, rồi đối chiếu nguyên nhân với các giới hạn ở trên.

Tìm hiểu về Ailoot.