Jalankan Claude Code di balik peluncur korporat

Arahkan proses yang dimulai Claude Code dari binernya sendiri, termasuk layanan latar belakang dan setiap sesi tampilan agen, melalui peluncur yang diperlukan dengan CLAUDE_CODE_PROCESS_WRAPPER atau pengaturan processWrapper.

Beberapa organisasi memerlukan setiap proses pada workstation untuk dimulai melalui peluncur wajib. Peluncur menerapkan sandbox, kontrol jaringan, atau injeksi kredensial yang postur keamanan perusahaan bergantung padanya, dan biner yang dimulai tanpanya adalah pelanggaran kebijakan.

CLAUDE_CODE_PROCESS_WRAPPER memulai setiap proses yang diluncurkan Claude Code dari binernya sendiri melalui peluncur Anda: layanan latar belakang, setiap sesi yang dihosting dalam tampilan agen, dan peluncuran ulang Claude Code setelah pembaruan. Atur ke jalur absolut peluncur Anda, dan Claude Code menjalankan peluncur dengan perintah Claude Code sebagai argumennya.

Peluncur yang membungkus perintah claude pada PATH Anda tidak dapat menjangkau proses-proses ini, karena mereka dimulai dari jalur langsung biner tanpa mencari claude.

Apa yang dicakup oleh launcher

Dengan CLAUDE_CODE_PROCESS_WRAPPER diatur, Claude Code memulai setiap proses berikut melalui launcher Anda:

• Layanan latar belakang yang dimulai oleh claude agents dan sesi latar belakang sesuai permintaan.
• Host terminal dan sesi Claude Code di dalam setiap baris tampilan agen, termasuk sesi siaga hangat yang disimpan layanan.
• Sesi yang diluncurkan kembali oleh layanan setelah pembaruan atau kerusakan.
• Peluncuran kembali yang dilakukan Claude Code pada dirinya sendiri untuk menyelesaikan pemasangan pembaruan, termasuk tindakan restart-for-update tampilan agen.
• Proses sesi yang dimulai oleh Remote Control. Memerlukan Claude Code v2.1.210 atau lebih baru.
• Sesi rekan tim split-pane yang dimulai oleh agent teams di tmux atau iTerm2. Pane rekan tim bersifat interaktif daripada proses latar belakang, tetapi Claude Code memulainya dari binernya sendiri, jadi launcher mencakupnya. Memerlukan Claude Code v2.1.210 atau lebih baru.

Di Windows, variabel diabaikan: kontrak launcher bergantung pada exec, yang tidak didukung Windows. Mesin Windows dengan variabel yang diatur menjalankan setiap proses tanpa pembungkus dan terus bekerja, dan satu-satunya sinyal adalah peringatan di debug log. Jika kebijakan launcher Anda mencakup Windows, variabel tidak memenuhinya di sana: hitung mesin Windows sebagai tanpa pembungkus saat Anda merencanakan peluncuran.

Proses yang dimulai di luar launcher

Proses berikut tidak dimulai melalui launcher:

• Sebuah layanan latar belakang yang terpasang yang unitnya ditulis sebelum launcher dikonfigurasi: launchd atau systemd memulai proses itu dari file unitnya. /status dan claude daemon status memperingatkan saat layanan yang berjalan dan launcher yang dikonfigurasi tidak cocok, dan sesi yang dimulai layanan masih dimulai melalui launcher setelah layanan dimulai ulang dengan variabel di pengaturannya.
• Sesi yang Anda mulai sendiri di terminal, yang berjalan sesuai cara Anda menjalankannya. Untuk mencakup sesi ini, letakkan skrip bernama claude di direktori lebih awal di PATH yang menjalankan launcher Anda dengan biner asli; jangan ganti symlink yang dikelola. Self-spawn tidak berkonsultasi dengan PATH, jadi dua launcher tidak pernah bertumpuk.
• Proses pertama dari deep link claude-cli://, yang dimulai langsung oleh penanganan protokol sistem operasi. Semua yang dimulai sesi itu di latar belakang setelahnya berjalan melalui launcher. Untuk menutup jalur ini sepenuhnya, cegah pendaftaran penanganan dengan pengaturan disableDeepLinkRegistration.
• Peluncuran kembali yang dilakukan --worktree dikombinasikan dengan --tmux: multiplexer terminal memulai pane itu, bukan biner Claude Code.
• Host native-messaging yang didaftarkan oleh Claude in Chrome: browser memulainya, bukan biner Claude Code.

Nama proses pembantu di monitor proses

Dengan launcher yang dikonfigurasi, ps dan Activity Monitor tidak lagi menampilkan label claude bg-pty-host dan claude bg-spare Claude Code untuk proses pembantu latar belakang, karena exec launcher membangun kembali daftar argumen. Kehilangan label adalah efek samping, bukan penyembunyian: proses sebaliknya tidak berubah, dan Claude Code mengidentifikasi proses miliknya sendiri berdasarkan jalur biner, tidak pernah berdasarkan nama tampilan.

Atur peluncur

#!/bin/sh
# Pengaturan organisasi Anda: masukkan sandbox, terapkan
# kontrol jaringan, atau injeksikan kredensial.
exec "$@"

{
"env": {
"CLAUDE_CODE_PROCESS_WRAPPER": "/opt/corp/launcher"
}
}

{
"processWrapper": "/opt/corp/launcher"
}

Kontrak peluncur

Ketika peluncur tidak dapat berjalan, Claude Code menolak untuk memulai proses alih-alih memulainya tanpa pembungkus. Di Windows, variabel diabaikan dan proses dimulai tanpa pembungkus. Claude Code memegang skrip ke aturan-aturan ini:

• Akhiri dengan exec "$@". Peluncur yang melahirkan anak dan keluar meninggalkan proses Claude Code yatim piatu yang tidak dapat dilacak layanan latar belakang. Tampilan agen menandai sesi seperti itu gagal dengan pesan yang menyebutkan peluncur, dan layanan mengumpulkan apa yang ditinggalkan peluncur.
• Jangan urutkan ulang, serap, atau tambahkan argumen. Argumen pertama adalah biner Claude Code dan semuanya setelahnya adalah argv-nya.
• Lewatkan setiap variabel lingkungan yang diwarisi melalui ke exec. Menambahkan variabel, seperti kredensial yang disuntikkan, baik-baik saja; menjatuhkan yang diwarisi tidak.
  • Token autentikasi per-sesi, pemilihan model dan penyedia, dan CLAUDE_CODE_PROCESS_WRAPPER itu sendiri semuanya berjalan di lingkungan yang diwarisi, jadi peluncur yang membangun ulangnya dari daftar izin memecahkan sesi yang dimulainya, dan /status melaporkan ketidakcocokan peluncur.
  • Jika peluncur harus memasuki namespace atau sandbox yang mengatur ulang lingkungan, ekspor ulang lingkungan yang diwarisi di dalamnya secara verbatim.
• Capai exec dalam sekitar tiga detik setiap kali peluncur berjalan. Pengiriman latar belakang dingin menjalankan peluncur dua kali berturut-turut sebelum byte pertama output, jadi lakukan pekerjaan lambat seperti pertukaran single sign-on dengan malas atau dari cache.
• Toleransi untuk diinvokasi dari dalam dirinya sendiri. Claude Code menerapkan peluncur ke setiap self-spawn bersarang, jadi peluncur yang memperoleh sumber daya eksklusif harus mendeteksi bahwa itu sudah memegangnya.
• Jangan tulis ke terminal sebelum Claude Code dimulai. Apa pun yang dicetak sebelum exec dilaporkan sebagai penyebab kerusakan jika sesi mati sebelum inisialisasi.

Format nilai peluncur

CLAUDE_CODE_PROCESS_WRAPPER dan pengaturan processWrapper mengambil format yang sama. Untuk sebagian besar peluncur, nilainya adalah jalur absolut skrip, seperti /opt/corp/launcher.

Untuk melewatkan argumen peluncur Anda sendiri, tuliskan setelah jalur. Claude Code menguraikan nilai sebagai daftar argumen, bukan perintah shell:

• Whitespace memisahkan token, dan tanda kutip ganda mengelompokkan token yang berisi spasi.
• Nilai yang dimulai dengan [ dibaca sebagai array string JSON, seperti ["/opt/corp/launcher", "--profile", "cc"].
• Sintaks shell tidak berfungsi: tidak ada ekspansi variabel atau globbing, dan operator yang tidak dikutip seperti ;, |, &, atau $( ditolak sebagai kesalahan konfigurasi daripada diinterpretasikan ulang.

Ketika nilai tidak dapat digunakan, Claude Code menolak untuk memulai proses yang terpengaruh dan melaporkan alasannya.

Hubungan dengan `CLAUDE_CODE_SHELL_PREFIX`

CLAUDE_CODE_PROCESS_WRAPPER membungkus proses Claude Code sendiri dan melewatkan perintah melalui sebagai token argv terpisah untuk peluncur ke exec. CLAUDE_CODE_SHELL_PREFIX membungkus perintah shell yang dijalankan Claude Code atas nama Anda, seperti panggilan alat Bash, hooks, dan perintah yang memulai server MCP stdio, dan melewatkan masing-masing sebagai string yang dikutip shell tunggal dalam $1 untuk pembungkus untuk mengevaluasi ulang. Peluncur yang ditulis untuk satu tidak berfungsi sebagai yang lain.

Sumber daya terkait

• Tampilan agen: sesi latar belakang dan proses supervisor yang dicakup peluncur
• Variabel lingkungan: entri referensi CLAUDE_CODE_PROCESS_WRAPPER
• Pengaturan yang dikelola: berikan blok env di seluruh armada
• Referensi kesalahan peluncur: pesan penolakan dan cara memulihkan