options yang Anda berikan saat memulainya. Halaman ini menunjukkan cara menyusun objek options dan apa file pengaturan serta variabel lingkungan yang mengontrolnya.
Untuk setiap tipe opsi dan default, lihat referensi Options (TypeScript) dan ClaudeAgentOptions (Python).
Berikan opsi ke sesi
Setiap panggilanquery() menerima objek opsi: Options di TypeScript, ClaudeAgentOptions di Python. Setiap bidang bersifat opsional, dan sesi yang dimulai tanpa opsi berjalan dengan default SDK. Contoh di bawah mengonfigurasi sesi baca-saja yang merangkum TODO terbuka proyek. Pasangan dibaca sebagai TypeScript / Python di mana ejaan berbeda:
model: memilih modelallowedTools/allowed_tools: pra-menyetujui daftar alat baca-sajamaxTurns/max_turns: membatasi jumlah gilirancwd: menetapkan direktori kerja
cwd ke salah satu proyek Anda sendiri dan jalankan contohnya. Ringkasan TODO terbuka proyek tersebut akan dicetak saat pesan hasil tiba.
allowedTools (TypeScript) atau allowed_tools (Python) pra-menyetujui alat yang terdaftar, sehingga panggilan ke alat tersebut berjalan tanpa menunggu persetujuan. Alat di luar daftar tetap tersedia. Ketika Claude memanggil alat yang tidak terdaftar, mode izin menentukan apakah panggilan berjalan. Untuk informasi lebih lanjut, lihat Aturan izin dan penolakan.
Muat file pengaturan
File pengaturan menyediakan konfigurasi di luar objek opsi. Dua opsi mengontrol cara memuatnya:settingSources/setting_sources: mengontrol sumber sistem file mana yang dimuat: pengguna, proyek, dan lokal. File pengaturan dan file CLAUDE.md tiba melalui sumber ini.settings: memuat jalur file pengaturan atau string JSON sebaris dalam bahasa apa pun, dan TypeScript juga menerima objek pengaturan. Bentuk apa pun yang Anda berikan menggantikan pengaturan sistem file pengguna, proyek, dan lokal; hanya pengaturan kebijakan terkelola yang lebih tinggi. Referensi mendokumentasikan urutan preseden lengkap di bawah Preseden pengaturan untuk TypeScript dan Preseden pengaturan untuk Python.
[] untuk menonaktifkan pengaturan pengguna, proyek, dan lokal. Untuk informasi lebih lanjut, lihat Gunakan fitur Claude Code di SDK.
Pilih model
Kecuali opsimodel, pengaturan Anda, atau lingkungan Anda memilih model, sesi baru dimulai pada model default Claude Code. Untuk urutan sumber tersebut, lihat Atur model Anda. Atur model untuk menetapkan model tertentu, atau untuk memilih model yang lebih kecil untuk agen yang lebih cepat dan lebih murah. Nilai mengambil alias model atau nama model lengkap; alias dan versi yang mereka selesaikan terdaftar di bawah Alias model.
Atur fallbackModel (TypeScript) atau fallback_model (Python) untuk menamai model cadangan. Ketika model utama kelebihan beban atau tidak tersedia, sesi beralih ke cadangan. Model utama dicoba ulang di awal setiap giliran pengguna, sehingga sesi kembali ke model utama setelah pemadaman berlalu.
Di kedua bahasa, opsi menerima model tunggal atau daftar cadangan yang dipisahkan koma. Untuk urutan dan batas rantai, lihat Rantai model fallback. Di TypeScript, fallback yang sama dengan model melempar kesalahan saat startup.
Contoh di bawah menunjukkan daftar fallback di TypeScript dan fallback tunggal di Python:
Parameter permintaan Messages API Messages API
temperature, top_p, dan max_tokens tidak memiliki bidang pada objek opsi di kedua bahasa. Atur tingkat upaya atau batas pengeluaran sebagai gantinya, atau panggil Messages API ketika Anda memerlukan parameter tersebut secara langsung.Atur variabel lingkungan
Opsienv menetapkan variabel lingkungan untuk proses Claude Code yang menjalankan sesi Anda. Apakah nilai Anda menggantikan lingkungan yang diwariskan atau menggabungkannya berbeda menurut bahasa:
- TypeScript:
envmenggantikan lingkungan subproses - Python: SDK menggabungkan nilai Anda di atas lingkungan yang diwariskan, dan nilai Anda menggantikan nilai yang diwariskan
process.env ke dalam env untuk menyimpan variabel yang diwariskan seperti PATH, HOME, dan ANTHROPIC_API_KEY. Ketika Anda membiarkan env tidak diatur, subproses mewarisi lingkungan Anda di kedua bahasa.
Contoh merutekan lalu lintas API melalui gateway dengan menetapkan ANTHROPIC_BASE_URL.
Atur direktori kerja
Aturcwd untuk menjalankan sesi di direktori tertentu. Ketika Anda membiarkan cwd tidak diatur, sesi berjalan di direktori kerja proses Anda. Tidak ada SDK yang memiliki setter untuk cwd. Untuk menjalankan di direktori berbeda, mulai sesi lain dengan cwd tersebut.
Claude Code membaca direktori kerja untuk menentukan:
- Pengaturan dan hook proyek: pengaturan dan hook proyek mana yang dimuat
- Skills: di mana skill sesi ditemukan
- Penyimpanan sesi: proyek mana yang sesi tersimpan miliknya
additionalDirectories (TypeScript) atau add_dirs (Python). Untuk cakupan hibah tersebut, lihat Direktori tambahan memberikan akses file, bukan konfigurasi.
Batasi giliran dan pengeluaran
Batasi giliran dan pengeluaran denganmaxTurns / max_turns dan maxBudgetUsd / max_budget_usd. Kedua batas dimatikan saat tidak diatur. Ketika sesi mencapai batas, jalankan berakhir dengan pesan hasil yang subtipe-nya menamai batas, error_max_turns atau error_max_budget_usd. Apa yang terjadi selanjutnya berbeda menurut mode input:
query()sekali jalan: SDK menghasilkan hasil batas dan kemudian melempar, jadi bungkus loop dalam blok try untuk melanjutkan melewati kesalahan- Input streaming: sesi tetap hidup melewati hasil batas, dan hitungan giliran maksimal dimulai ulang untuk setiap pesan antrian. Total anggaran terakumulasi di seluruh pesan, dan setelah pengeluaran mencapai batas, pesan nanti dalam percakapan yang sama berakhir dengan hasil anggaran yang sama.
/clearmemulai anggaran dari awal
0 secara berbeda:
maxTurns/max_turns:0menjalankan sesi tanpa batas giliran, sama dengan membiarkan opsi tidak diaturmaxBudgetUsd/max_budget_usd: CLI menolak0sebagai jumlah yang tidak valid saat startup, dan sesi tidak pernah berjalan
Ubah konfigurasi di tengah sesi
Ketika Anda memulai sesi dengan input streaming, Anda dapat mengganti model dan mode izinnya saat berjalan. Tempat Anda memanggil setter berbeda menurut bahasa:- TypeScript: metode pada objek yang
query()kembalikan - Python: metode pada
ClaudeSDKClient, karenaquery()mengembalikan iterator biasa tanpa metode kontrol
setModel()/set_model(): mengganti model. Panggilnya tanpa model untuk beralih ke model default Claude Code daripadamodelyang Anda berikan dalam opsi.setPermissionMode()/set_permission_mode(): mengganti mode izin
applyFlagSettings() dan updateSettings():
applyFlagSettings(): menerapkan pengaturan saat runtime, seperti dalamawait session.applyFlagSettings({ effortLevel: "high" }). Metode mengambil kunci file pengaturan daripada bidang opsi, jadi periksa referensiapplyFlagSettings()untuk skema dan untuk kunci mana yang berlaku di tengah sesi.updateSettings(): menulis set kunci yang diizinkan ke file pengaturan lokal proyek, seperti dalamawait session.updateSettings("localSettings", { outputStyle: "Explanatory" }). Kunci yang ditulis berlaku pada permintaan sesi berikutnya dan bertahan untuk sesi nanti yang memuat pengaturanlocal. Baris metode dalam tabel metode menamai kunci yang diizinkan dan lantai versi.
First turn model: claude-sonnet-5, kemudian Second turn model: claude-opus-5 setelah pengalihan.
Setiap model memiliki cache prompt-nya sendiri, jadi setelah pengalihan di tengah sesi, permintaan berikutnya menghitung ulang percakapan lengkap tanpa cache pada tarif model baru. Untuk informasi lebih lanjut, lihat Mengganti model.
Konfigurasi fitur spesifik
Tabel di bawah memetakan setiap opsi ke fitur yang dikonfigurasinya. Untuk opsi yang tidak dicakup halaman ini, lihat referensi TypeScript dan Python. Jika Anda tahu tujuan Anda tetapi tidak tahu opsi mana yang melayaninya, mulai dari Pilih fitur yang tepat.Langkah berikutnya
Untuk melihat konfigurasi yang disusun menjadi agen yang berfungsi:- Quickstart: bangun dan jalankan agen pertama dari awal hingga akhir
- Contoh: temukan proyek lengkap yang dapat dijalankan atau resep Claude Cookbook yang dipandu yang cocok dengan apa yang ingin Anda bangun
- Isolasi multi-penyewa: isolasi pengaturan dan memori setiap penyewa dengan
settingSources/setting_sources,env, dancwd