Chạy Claude Code sau corporate launcher

Bài viết được dịch tự động từ bài viết gốc, chưa được kiểm tra lại bởi con người. Chỉ những bài viết có dấu tick xanh cạnh tiêu đề là đã được kiểm tra.

Một số tổ chức yêu cầu mọi tiến trình trên máy trạm phải khởi động qua một launcher bắt buộc. Launcher áp sandbox, kiểm soát mạng, hoặc chèn credential mà chính sách bảo mật công ty phụ thuộc vào - một binary khởi động mà không qua nó là vi phạm chính sách.

CLAUDE_CODE_PROCESS_WRAPPER khiến mọi tiến trình Claude Code khởi động từ binary của chính nó chạy qua launcher của bạn: background service, mọi session nó host trong agent view, và các lần Claude Code tự khởi động lại sau khi update. Đặt biến này thành đường dẫn tuyệt đối tới launcher - Claude Code sẽ chạy launcher với lệnh Claude Code làm tham số.

Một launcher chỉ wrap lệnh claude trên PATH không thể chạm tới các tiến trình này, vì chúng khởi động trực tiếp từ đường dẫn binary mà không tra cứu claude.

Launcher bao phủ những gì

Khi đặt CLAUDE_CODE_PROCESS_WRAPPER, Claude Code khởi động các tiến trình sau qua launcher:

Background service mà claude agents và background session khởi động khi cần.
Terminal host và session Claude Code bên trong mỗi dòng agent view, kể cả session warm standby mà service giữ sẵn.
Session mà service respawn sau update hoặc crash.
Lần Claude Code tự relaunch để hoàn tất cài update, kể cả hành động restart-for-update trong agent view.
Tiến trình worker Remote Control mà background service quản lý (từ v2.1.210).
Session teammate split-pane mà agent teams khởi động trong tmux hoặc iTerm2 (từ v2.1.210).

Trên Windows, biến này bị bỏ qua: hợp đồng launcher phụ thuộc vào exec, mà Windows không hỗ trợ. Nếu chính sách launcher của bạn bao phủ cả Windows, tính biến này là chưa đáp ứng ở đó.

Tiến trình không khởi động qua launcher

Một background service đã cài mà unit được viết trước khi launcher được cấu hình: launchd/systemd khởi động tiến trình đó từ file unit của nó.
Một session bạn tự khởi động trong terminal, chạy theo cách bạn gọi nó. Để bao phủ các session này, đặt một script tên claude ở thư mục đứng trước trên PATH chạy launcher của bạn với binary thật; đừng thay symlink được quản lý.
Tiến trình đầu tiên của một claude-cli:// deep link, do trình xử lý protocol của hệ điều hành khởi động trực tiếp.
Lần relaunch mà --worktree kết hợp --tmux thực hiện: terminal multiplexer khởi động pane đó, không phải binary của Claude Code.
Native-messaging host mà Claude in Chrome đăng ký: trình duyệt khởi động nó.

Thiết lập launcher

Viết script launcher tại một đường dẫn tuyệt đối, ví dụ /opt/corp/launcher. Claude Code chạy nó với toàn bộ lệnh Claude Code làm tham số, và script phải kết thúc bằng exec "$@" để thay thế chính nó bằng Claude Code:
```
#!/bin/sh
# Thiết lập của tổ chức bạn: vào sandbox, áp kiểm soát
# mạng, hoặc chèn credential.
exec "$@"
```
Cấp quyền chạy bằng chmod +x.

Nếu trước đây bạn thay thế symlink ~/.local/bin/claude bằng launcher, khôi phục lại symlink gốc trong cùng thay đổi. Symlink bị thay khiến session wrap đầu tiên khởi động background service qua cả hai launcher cùng lúc, và đưa bản cài vào trạng thái externally managed.
Đặt CLAUDE_CODE_PROCESS_WRAPPER trong settings, không phải shell export, vì background service khởi động khi cần và không bao giờ đọc lại shell profile.

Cho một máy, thêm vào ~/.claude/settings.json. Để triển khai toàn tổ chức, đặt cùng block trong managed settings:
```
{
  "env": {
    "CLAUDE_CODE_PROCESS_WRAPPER": "/opt/corp/launcher"
  }
}
```
Setting processWrapper mang cùng giá trị dưới dạng key top-level có tên (từ v2.1.210):
```
{
  "processWrapper": "/opt/corp/launcher"
}
```
CLAUDE_CODE_PROCESS_WRAPPER có độ ưu tiên cao hơn khi cả hai đặt.

Project và local settings không thể cấu hình launcher - Claude Code bỏ qua CLAUDE_CODE_PROCESS_WRAPPER trong .claude/settings.json hoặc .claude/settings.local.json (kèm cảnh báo trong debug log), và không bao giờ đọc key processWrapper từ các file đó.
Khởi động lại background service và session: một service đang chạy và session claude đang mở chỉ đọc biến này một lần lúc khởi động. Chạy claude daemon stop --any để dừng service on-demand; lệnh tiếp theo cần nó (như claude agents) sẽ khởi động bản đã wrap. Khởi động lại session claude đang mở của bạn sau đó.
Xác minh: chạy /status trong session - mục Self-exec hiển thị lệnh khởi động đã resolve và cảnh báo khi background service đang chạy không khớp. claude daemon status in cùng thông tin từ shell.

Hợp đồng launcher

Khi launcher không chạy được, Claude Code từ chối khởi động tiến trình thay vì chạy không wrap. Claude Code giữ script theo các quy tắc:

Kết thúc bằng exec "$@": launcher fork một child rồi thoát sẽ để lại tiến trình Claude Code mồ côi mà background service không theo dõi được.
Không sắp xếp lại, gộp, hoặc thêm tham số vào đầu: tham số đầu tiên là binary Claude Code, phần còn lại là argv của nó.
Truyền mọi biến môi trường kế thừa qua exec: thêm biến (như credential được chèn) là được; bỏ biến kế thừa thì không.
Chạm tới exec trong khoảng 3 giây mỗi lần chạy: một dispatch nền lạnh chạy launcher hai lần liên tiếp trước byte đầu ra đầu tiên, nên việc chậm (như xác thực SSO) nên làm lười biếng hoặc dùng cache.
Chịu được việc bị gọi từ bên trong chính nó: Claude Code áp launcher cho mọi self-spawn lồng nhau.
Không ghi ra terminal trước khi Claude Code khởi động: bất kỳ thứ gì in ra trước exec sẽ được báo là nguyên nhân crash nếu session chết trước khi khởi tạo.

Định dạng giá trị launcher

CLAUDE_CODE_PROCESS_WRAPPER và setting processWrapper cùng định dạng. Với hầu hết launcher, giá trị là đường dẫn tuyệt đối tới script, như /opt/corp/launcher.

Để truyền tham số riêng cho launcher, viết chúng sau đường dẫn. Claude Code parse giá trị như một danh sách tham số, không phải shell command:

Khoảng trắng phân tách token, dấu ngoặc kép nhóm token chứa khoảng trắng.
Giá trị bắt đầu bằng [ được đọc như một JSON string array, ví dụ ["/opt/corp/launcher", "--profile", "cc"].
Cú pháp shell không hoạt động: không có mở rộng biến hay globbing, và một toán tử không quote như ;, |, &, $( bị từ chối như lỗi cấu hình.

Quan hệ với `CLAUDE_CODE_SHELL_PREFIX`

CLAUDE_CODE_PROCESS_WRAPPER wrap các tiến trình của chính Claude Code và truyền lệnh dưới dạng token argv riêng biệt cho launcher exec. CLAUDE_CODE_SHELL_PREFIX wrap các shell command mà Claude chạy thay bạn (tool Bash, hook, lệnh khởi động MCP server dạng stdio) và truyền mỗi lệnh dưới dạng một chuỗi shell-quoted duy nhất trong $1. Một launcher viết cho cái này không hoạt động như cái kia.

Phuc Tran

Software Engineer | Learning Claude