Claude apps gateway untuk Amazon Bedrock, Claude Platform di AWS, Google Cloud, dan Microsoft Foundry

Jalankan Claude Code melalui Amazon Bedrock, Claude Platform di AWS, Google Cloud, atau Microsoft Foundry di balik gateway yang di-host sendiri dengan SSO sign-in, akses model per-grup, dan telemetri OTLP.

[!NOTE]

Claude apps gateway dirancang untuk organisasi yang harus — atau lebih suka — merutekan inferensi melalui penyedia cloud mereka sendiri, misalnya untuk memenuhi persyaratan residensi data. Jika Anda tidak memiliki persyaratan ini, dan menginginkan akses ke fitur lain seperti penyediaan SCIM atau Claude Code di web dan mobile, Claude Enterprise mungkin lebih cocok. Lihat halaman ketersediaan fitur untuk perbandingan lengkap semua metode penyebaran.

Claude Code menggunakan satu sign-in dalam satu waktu: sign-in gateway menggantikan login Claude for Teams atau Enterprise. Sesi gateway tidak mengambil pengaturan terkelola server yang Anda tetapkan di konsol admin claude.ai, jadi kirimkan pengaturan tersebut dari blok managed gateway. Jangan sertakan forceLoginMethod dan forceLoginOrgUUID dalam blok tersebut, atau beberapa sesi yang sudah masuk akan keluar saat startup. Lihat Ketersediaan dan keterbatasan untuk mengetahui apa saja yang hilang dari sesi gateway.

Claude apps gateway adalah layanan yang di-host sendiri yang berada di antara klien Claude Code pengembang Anda dan penyedia model Anda. Pengembang masuk dengan penyedia identitas perusahaan Anda (IdP) alih-alih menyimpan kunci API atau kredensial cloud. Gateway menyimpan kredensial upstream, memberlakukan akses model dan pengaturan terkelola berdasarkan grup IdP, dan meneruskan telemetri penggunaan ke tumpukan observabilitas Anda sendiri.

Ini disertakan dalam biner claude, jadi executable yang sama yang menjalankan Claude Code di laptop menjalankan server gateway dengan claude gateway --config gateway.yaml.

Halaman ini mencakup:

• Mengapa Claude apps gateway, apa yang ditambahkannya dibandingkan menjalankan milik Anda sendiri, dan kapan sesuatu yang lain lebih cocok
• Quickstart dengan prasyarat yang membawa gateway dari nol ke pengembang yang masuk
• Menghubungkan pengembang, termasuk menetapkan URL gateway melalui pengaturan terkelola
• Ketersediaan dan keterbatasan mencakup fitur Claude Code mana yang bekerja melalui gateway dan apa yang didukung server

Halaman pendamping menggali lebih dalam. Referensi konfigurasi mencakup setiap opsi dalam file YAML yang ditulis quickstart, dan panduan penyebaran mencakup penyiapan per-IdP, penyebaran Kubernetes dan Cloud Run, serta operasi.

Mengapa Claude apps gateway

Gambaran umum gateway mencakup apa yang dilakukan gateway dan mengapa Anda akan menjalankannya. Claude apps gateway adalah gateway Anthropic sendiri, dibangun ke dalam biner claude dan diuji bersama setiap rilis Claude Code, sehingga ia meneruskan nilai anthropic-beta dan bidang permintaan yang dikirim Claude Code tanpa operator perlu memelihara allowlist terpisah. Setelah di-deploy, ia memberi Anda:

• Kredensial: kunci API upstream atau kredensial cloud hanya ada di infrastruktur Anda. Pengembang melakukan autentikasi dengan SSO perusahaan dan menerima token bearer berumur pendek, jadi offboarding terjadi di IdP Anda. Hapus penyediaan pengguna dan akses gateway mereka kedaluwarsa dalam masa pakai sesi, satu jam secara default.
• Kontrol akses: grup IdP Anda dipetakan ke allowlist model, kebijakan pengaturan terkelola, dan upstream. Gateway memberlakukan akses model di sisi server, menolak permintaan untuk model yang tidak diberikan, dan memilih kebijakan pengaturan terkelola setiap grup, yang diterapkan CLI di tingkat pengaturan terkelola. Tim yang berbeda mendapatkan model, tool, dan izin yang berbeda, dan pengembang tidak dapat menimpa apa yang dikunci kebijakan mereka.
• Pengiriman pengaturan: gateway sendiri mengirimkan pengaturan terkelola ke klien yang sudah masuk, menggantikan pengaturan terkelola server dari konsol admin claude.ai.
• Telemetri: setiap tujuan yang dikonfigurasi menerima metrik OpenTelemetry Protocol (OTLP) dengan hitungan token, model, identitas pengguna, dan latensi secara default, dengan log dan jejak sebagai opt-in per-tujuan.
• Perutean upstream: klien berbicara API Pesan Anthropic ke gateway, dan gateway menerjemahkan untuk setiap upstream, baik Amazon Bedrock, Claude Platform on AWS, Agent Platform Google Cloud, Microsoft Foundry, atau API Anthropic, dengan failover di antara mereka. Anda dapat mengubah wilayah, penyedia, atau urutan failover tanpa pengembang menyadari atau mengonfigurasi ulang.

[!NOTE]

Bidang data gateway sendiri tidak mengirim apa pun ke infrastruktur Anthropic kecuali API Anthropic adalah upstream yang dikonfigurasi. Anda mengontrol ke mana telemetri, log audit, pengaturan terkelola, dan identitas IdP pengembang Anda pergi, dan gateway tidak mengirimkan satu pun dari semua itu ke Anthropic. Untuk lalu lintas lain yang dapat dikirim proses CLI dan cara menutupnya, lihat Compliance posture.

Untuk fitur Claude Code mana yang bekerja melalui gateway dan apa yang didukung server itu sendiri, lihat Ketersediaan dan keterbatasan di bawah. Untuk keputusan seperti biaya, bypass, menjalankan beberapa gateway, dan platform serverless, lihat panduan deployment.

Implementasi gateway lainnya

Jika Anda sudah menjalankan gateway LLM atau gateway API yang memenuhi kebutuhan Anda, terus gunakan; Gateway LLM lainnya mencakup konfigurasi Claude Code terhadapnya.

Panduan kompatibilitas gateway mendokumentasikan apa yang diharapkan Claude Code dari gateway apa pun: endpoint yang dipanggilnya, header dan bidang body yang harus diteruskan, dan apa yang berhenti bekerja ketika semua itu dihapus. Claude apps gateway yang berjalan juga menyajikan referensi protokolnya sendiri di GET /protocol, yang menjelaskan endpoint yang diekspos ke klien Claude Code: SSO sign-in, inferensi, pengiriman pengaturan terkelola, penemuan model, dan telemetri. Ambil dengan curl https://claude-gateway.internal.example.com/protocol dari gateway apa pun yang sudah di-deploy, seperti yang dihasilkan mulai cepat di bawah.

Perubahan breaking pada protokol diumumkan sebelumnya, tetapi kompatibilitas mundur tanpa batas waktu tidak dijamin.

[!NOTE]

Token sign-in gateway mengidentifikasi pengembang yang menyetujui sign-in, bukan program yang menggunakannya. Claude Code melakukan sign-in tanpa client ID atau secret miliknya sendiri, sehingga gateway tidak memiliki cara untuk memverifikasi program mana yang sedang melakukan sign-in. Klien mana pun dapat menetapkan User-Agent dan bidang permintaan lainnya, jadi gunakan semua itu untuk perutean atau metrik, bukan sebagai bukti bahwa suatu permintaan berasal dari Claude Code.

Mulai cepat

Mulai cepat ini menempuh jalur minimal: mendaftarkan klien OAuth di IdP Anda, menulis gateway.yaml, menjalankan gateway bersama Postgres dengan Docker Compose, dan memverifikasi proses masuk dari ujung ke ujung. Panduan ini menggunakan upstream Amazon Bedrock; Claude Platform on AWS, Google Cloud's Agent Platform, Microsoft Foundry, dan Anthropic API juga didukung dengan cara yang sama dengan mengganti blok upstreams seperti yang ditunjukkan dalam referensi konfigurasi. Di akhir, Anda memiliki gateway yang dapat digunakan developer untuk /login.

[!NOTE]

Deploy di jaringan privat Anda. Claude Code hanya terhubung ke gateway yang alamatnya privat. Ini adalah pengaman keamanan, karena gateway tepercaya dapat mengirimkan pengaturan yang menjalankan perintah di mesin developer. Tempatkan gateway di belakang load balancer internal atau VPN dan berikan hostname yang hanya di-resolve ke IP privat. Jika jaringan internal Anda menggunakan penomoran dari ruang IPv4 publik yang dimiliki organisasi Anda, lihat Mengizinkan gateway di ruang alamat publik yang Anda miliki.

Prasyarat

Siapkan hal-hal berikut sebelum memulai:

Jika HTTPS_PROXY atau HTTP_PROXY berlaku untuk host gateway, proses masuk juga memerlukan proxy yang hostname-nya di-resolve ke alamat privat, atau host gateway dimasukkan ke NO_PROXY di mesin developer. Jika mesin tersebut juga mengatur no_proxy, tambahkan host gateway di sana juga; jika tidak, permintaan model tetap melewati proxy.

Langkah-langkah

1. Daftarkan klien OAuth di IdP Anda

Tentukan hostname gateway terlebih dahulu, karena redirect URI harus cocok dengannya. Buat aplikasi web OIDC baru dan atur redirect URI ke https://claude-gateway.<your-domain>/oauth/callback, dengan host yang sama dengan nilai yang Anda atur sebagai listen.public_url pada langkah 3. Catat client_id dan client_secret. Instruksi per IdP ada di Penyiapan penyedia identitas.

2. Sediakan database PostgreSQL

Gunakan PostgreSQL 11 atau lebih baru. Tier terkelola terkecil sudah cukup. Gateway menjalankan migrasi skemanya sendiri saat boot, sehingga role database memerlukan hak untuk membuat dan mengubah tabel; lihat store.

3. Tulis gateway.yaml

Secret dibaca melalui ekspansi ${ENV_VAR} sehingga file itu sendiri dapat disimpan di version control. Gunakan hostname public_url yang di-resolve ke IP privat di jaringan Anda, karena /login menolak alamat publik. Konfigurasi minimal memiliki lima bagian, dan setiap field lainnya memiliki nilai default:

listen:
  host: 0.0.0.0
  port: 8080
  # Required unless host is a loopback address. Used for the IdP
  # redirect_uri and the discovery document.
  public_url: https://claude-gateway.internal.example.com

oidc:
  issuer: https://login.example.com        # must serve /.well-known/openid-configuration
  client_id: 0oa1example2
  client_secret: ${OIDC_CLIENT_SECRET}
  allowed_email_domains: [example.com]        # reject id_tokens outside your org
  userinfo_fallback: true                  # for IdPs whose id_token omits email/groups; harmless otherwise

session:
  jwt_secret: ${GATEWAY_JWT_SECRET}        # openssl rand -base64 32
  ttl_hours: 1                             # also bounds revocation latency on IdP deprovision

store:
  postgres_url: ${GATEWAY_POSTGRES_URL}    # add ?sslmode=require for managed Postgres

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {} # empty: AWS default credential chain
# (IRSA, EC2/ECS task role, env vars, ~/.aws)

# Models are translated per upstream automatically. The built-in catalog
# maps claude-opus-4-8 to us.anthropic.claude-opus-4-8 and so on for every
# Bedrock-supported Claude model. Set false and add a `models:` list to
# expose only specific models.
auto_include_builtin_models: true

Konfigurasi ini sudah cukup untuk loop masuk yang berfungsi dengan katalog model Amazon Bedrock default. Setelah berjalan, tambahkan RBAC per grup dan pengaturan terkelola melalui managed.policies, fan-out telemetri melalui telemetry, serta failover multi-upstream, ARN provisioned-throughput, atau region non-AS melalui models.

[!NOTE]

Upstream Amazon Bedrock memerlukan principal AWS dengan bedrock:InvokeModel dan bedrock:InvokeModelWithResponseStream pada ARN inference-profile/us.anthropic.* dan ARN foundation-model/anthropic.* yang mendasarinya. Upstream ini juga memerlukan formulir use case satu kali dari Anthropic yang telah dikirimkan untuk akun tersebut dari Model catalog di konsol Bedrock.

Sediakan kredensial dengan IRSA di EKS, role task ECS, atau instance profile EC2, bukan kunci statis. Referensi upstreams berisi detail IAM lengkap, matriks kredensial lintas cloud, dan blok auth untuk penyedia lainnya.

4. Jalankan

Build image container di sekitar binary claude yang memenuhi persyaratan image, lalu jalankan bersama Postgres. File Compose mereferensikan image sebagai registry.example.com/claude-gateway:2.1.198; ganti dengan registry dan tag image Anda sendiri:

services:
  gateway:
    image: registry.example.com/claude-gateway:2.1.198
    ports: ["8080:8080"]
    volumes: ["./gateway.yaml:/etc/claude/gateway.yaml:ro"]
    environment:
      OIDC_CLIENT_SECRET: ${OIDC_CLIENT_SECRET}
      GATEWAY_JWT_SECRET: ${GATEWAY_JWT_SECRET}
      GATEWAY_POSTGRES_URL: postgres://gw:pw@postgres/gateway
      # AWS credentials: in production, omit these and use an instance
      # role. For local Compose testing, pass through your own:
      AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}
      AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}
      AWS_SESSION_TOKEN: ${AWS_SESSION_TOKEN}
    depends_on:
      postgres:
        condition: service_healthy
  postgres:
    image: postgres:16-alpine
    environment: { POSTGRES_USER: gw, POSTGRES_PASSWORD: pw, POSTGRES_DB: gateway }
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U gw"]
      interval: 5s
    volumes: ["pgdata:/var/lib/postgresql/data"]
volumes: { pgdata: }

Gateway adalah satu binary Linux yang membaca konfigurasi, terhubung ke Postgres dan menerapkan migrasi skemanya, menjalankan discovery OIDC terhadap IdP Anda, membangun klien upstream, dan mulai mendengarkan.

Boot bersifat fail-closed untuk konfigurasi, koneksi Postgres, discovery OIDC, dan pembuatan klien upstream. Jika salah satu dari itu tidak dapat dijangkau atau salah dikonfigurasi, gateway keluar dengan error alih-alih melayani lalu lintas dalam keadaan terdegradasi.

Boot yang berhasil tidak memvalidasi jalur inferensi, karena kredensial instance Amazon Bedrock dan Google Cloud's Agent Platform di-resolve pada permintaan pertama, bukan saat boot.

Pantau stderr untuk urutan boot. Secara default, baris log menggunakan format [gateway] <timestamp> <level> <message>, dan banner startup, yang dihilangkan di bawah, dicetak di antara baris migrasi dan baris listening. Event audit berupa JSON satu baris dengan field evt. Database baru mencetak satu baris migration N applied per migrasi skema; database yang sudah dimigrasi tidak mencetak apa pun. Anda akan melihat, secara berurutan:

{"ts":"2026-06-10T17:03:21.114Z","evt":"config.load","path":"/etc/claude/gateway.yaml","sha256":"…"}
[gateway] 2026-06-10T17:03:21.395Z info waiting for migration lock (another replica may be migrating; check pg_locks for key 6775156 if this persists)
[gateway] 2026-06-10T17:03:21.408Z info migration 1 applied
…
[gateway] 2026-06-10T17:03:21.431Z info migration 6 applied
[gateway] 2026-06-10T17:03:21.512Z info claude gateway listening on http://0.0.0.0:8080

Gateway juga mencatat peringatan bahwa access_control.allow_cidrs kosong. Hal ini memang diharapkan di sini, karena tidak ada yang membatasi alamat klien mana yang dilayani gateway sampai Anda mengatur allow list. Referensi access_control berisi rentang yang direkomendasikan.

Jika boot keluar sebelum baris claude gateway listening on, baris terakhir stderr menyebutkan masalahnya:

• Postgres yang tidak dapat dijangkau
• role Postgres tanpa izin DDL
• dokumen discovery OIDC yang tidak dapat dijangkau atau tidak valid
• pelanggaran skema konfigurasi beserta path field yang bermasalah

Perbaiki lalu mulai ulang.

Jika Anda sudah memiliki ingress yang melakukan terminasi TLS, lewati Compose dan jalankan binary secara langsung dengan claude gateway --config gateway.yaml. Atur public_url ke origin ingress dan ikat listen ke alamat loopback atau alamat internal cluster.

5. Verifikasi surface autentikasi

Tiga pemeriksaan memastikan gateway dapat mengautentikasi pengguna nyata sebelum Anda membagikannya kepada developer.

Contoh-contoh menggunakan URL publik gateway; untuk penyiapan Compose lokal tanpa ingress, ganti dengan http://localhost:8080 pada dua pemeriksaan pertama. Pemeriksaan ketiga membuka verification_uri_complete, yang dibangun dari public_url, jadi untuk Compose lokal atur public_url: http://localhost:8080 di gateway.yaml, dan tambahkan http://localhost:8080/oauth/callback sebagai redirect URI kedua pada klien OAuth dari langkah 1, karena gateway membangun redirect_uri IdP dari public_url. Tautan verifikasi kemudian terbuka di browser lokal Anda.

Di Windows PowerShell, jalankan curl.exe; curl tanpa ekstensi adalah alias untuk Invoke-WebRequest dan menolak flag-flag ini.

Pertama, ambil dokumen discovery, yang memastikan gateway aktif, konfigurasi valid, dan semua pemeriksaan boot lulus:

curl -s https://claude-gateway.internal.example.com/.well-known/oauth-authorization-server | jq

{
  "issuer": "https://claude-gateway.internal.example.com",
  "device_authorization_endpoint": "…/oauth/device_authorization",
  "token_endpoint": "…/oauth/token",
  "grant_types_supported": ["urn:ietf:params:oauth:grant-type:device_code", "refresh_token"]
}

Respons menyertakan field tambahan, seperti response_types_supported dan scopes_supported.

Kedua, minta otorisasi perangkat, yang memastikan alur masuk perangkat berfungsi dan Postgres dapat dijangkau serta dapat ditulis:

curl -s -X POST https://claude-gateway.internal.example.com/oauth/device_authorization | jq

{
  "device_code": "…",
  "user_code": "WDJB-MJHT",
  "verification_uri": "https://claude-gateway.internal.example.com/device",
  "verification_uri_complete": "https://claude-gateway.internal.example.com/device?user_code=WDJB-MJHT",
  "expires_in": 600,
  "interval": 5
}

Ketiga, uji bagian browser dengan membuka verification_uri_complete di browser dan mengonfirmasi kodenya. Anda seharusnya dialihkan ke halaman masuk IdP Anda, dan setelah masuk, kembali ke gateway dengan konfirmasi bahwa Anda telah masuk.

Gunakan pemeriksaan pertama yang gagal untuk menemukan masalahnya:

• Pemeriksaan pertama gagal: boot tidak selesai; periksa stderr
• Pemeriksaan kedua gagal: Postgres tidak dapat dijangkau dari gateway atau role tidak dapat menulis; periksa connection string dan grant
• Pemeriksaan ketiga tidak mencapai IdP: periksa bahwa redirect URI IdP cocok persis dengan https://<gateway>/oauth/callback
• Pemeriksaan ketiga mencapai IdP tetapi dikembalikan dengan error: baca log audit gateway, yang mencatat setiap penolakan autentikasi beserta alasannya, seperti email domain not allowed

6. Masukkan developer

Langkah terakhir ini dilakukan di mesin developer, bukan di server. Atur forceLoginMethod ke "gateway", forceLoginGatewayUrl ke public_url gateway Anda, dan parentSettingsBehavior ke "merge" di file pengaturan terkelola mesin tersebut, lalu jalankan /login, tekan Enter pada layar Cloud gateway, dan selesaikan proses masuk di browser. Mengatur URL gateway di bawah membahas ketiga kunci tersebut dan cara mendistribusikannya ke setiap mesin developer.

Menghubungkan pengembang

Pengembang terhubung dari laptop mereka sendiri dengan satu kali masuk melalui browser, menggunakan akun kerja perusahaan mereka. Mereka tidak memerlukan akun claude.ai, kunci API, atau langganan, karena permintaan ke model melewati gateway menggunakan kredensial upstream organisasi. Koneksi dikendalikan oleh pengaturan terkelola sisi klien yang Anda dorong melalui MDM, dan bagian ini membahas apa yang dikonfigurasi oleh admin.

CLI mengambil sidik jari sertifikat leaf TLS gateway pada koneksi pertama dan menyematkannya per hostname. CLI memeriksa sematan tersebut lagi saat masuk, saat penyegaran sesi secara diam-diam, dan saat pengambilan pengaturan terkelola, sedangkan permintaan inferensi menggunakan validasi TLS standar tanpa sematan. Permintaan yang dirutekan melalui proxy HTTPS melewati pemeriksaan sematan, jadi tambahkan host gateway ke NO_PROXY agar permintaan tersebut tetap langsung.

Publikasikan sidik jari SHA-256 yang diharapkan bersama URL gateway agar pengembang memiliki sesuatu untuk dibandingkan. Prompt /login menampilkan 16 karakter pertama sidik jari sebagai heksadesimal huruf kecil tanpa titik dua. Untuk mencetak sidik jari lengkap dalam bentuk tersebut dari file sertifikat, jalankan:

openssl x509 -noout -fingerprint -sha256 -in cert.pem | cut -d= -f2 | tr -d : | tr 'A-F' 'a-f'

Ketika sertifikat dirotasi, setiap pengembang akan melihat prompt kepercayaan lagi, jadi perlakukan rotasi sebagai peristiwa terencana dan publikasikan ulang sidik jarinya. Jika kebijakan gateway Anda menyertakan pengaturan yang memerlukan persetujuan, pengembang juga akan melihat dialog persetujuan tersebut lagi setelah menerima sertifikat baru, karena Claude Code mengaitkan memori persetujuan dengan sertifikat yang disematkan.

Gateway dapat mengembalikan field opsional email dalam respons token-nya untuk menyebutkan akun yang digunakan saat masuk. Jika demikian, pengembang mengonfirmasi akun tersebut sebelum Claude Code menyimpan kredensial. Setelah masuk yang dikonfirmasi, /status menampilkan akun tersebut.

Konfirmasi ini memerlukan Claude Code v2.1.275 atau yang lebih baru di mesin pengembang; klien di bawah versi tersebut mengabaikan field ini. Server gateway di dalam binary claude tidak mengembalikan field ini, sehingga proses masuk melaluinya selesai tanpa konfirmasi.

Setelah pengembang masuk, pemilih model menampilkan model-model dalam allowlist availableModels mereka. Pengaturan terkelola diterapkan saat startup dan diperbarui setiap jam, dan telemetri dirutekan ke kolektor Anda.

Sesi diperbarui secara diam-diam sebelum kedaluwarsa ttl_hours. Ketika penyegaran gagal setelah deprovisioning IdP, Claude Code meminta pengembang untuk masuk lagi.

Menetapkan URL gateway

Tiga kunci dimasukkan ke dalam file pengaturan terkelola per OS yang Anda deploy melalui MDM atau langsung di disk. Untuk mesin tanpa pengaturan terkelola, lihat Menetapkan URL gateway di pengaturan pengguna sebagai gantinya. forceLoginMethod dan forceLoginGatewayUrl membuka /login langsung pada layar Cloud gateway dengan URL yang sudah terisi, dan parentSettingsBehavior: "merge" memungkinkan Claude Desktop mengirimkan allowlist egress gateway ke sesi Claude Code yang diluncurkannya, seperti dijelaskan di Mengirimkan kebijakan ke sesi Claude Desktop:

{
  "forceLoginMethod": "gateway",
  "forceLoginGatewayUrl": "https://claude-gateway.internal.example.com",
  "parentSettingsBehavior": "merge"
}

Pengembang menekan Enter untuk terhubung. Prompt sidik jari TLS koneksi pertama tetap muncul. Setelah file berada di mesin, pengembang yang belum menyelesaikan proses masuk gateway akan melihat salah satu pesan yang dijelaskan di Administrator policy requires a Cloud gateway sign-in. Pengembang yang memilih penyedia cloud melalui environment variable seperti CLAUDE_CODE_USE_BEDROCK tidak memerlukan proses masuk gateway.

Pemilih login tidak memiliki opsi gateway, dan dalam pengaturan terkelola, forceLoginMethod saja tanpa URL akan membuat pengembang tertahan pada pesan "Contact your IT administrator". Kunci login harus berada di file yang Anda dorong ke mesin, bukan di blok managed.policies[].cli milik gateway, yang hanya menjangkau klien yang sudah terhubung.

Menetapkan URL gateway di pengaturan pengguna

Pada mesin tanpa pengaturan terkelola, minta setiap pengembang menambahkan forceLoginMethod dan forceLoginGatewayUrl ke file pengaturan pengguna mereka sendiri, ~/.claude/settings.json. Ini memerlukan Claude Code v2.1.295 atau yang lebih baru di mesin pengembang. Contoh ini menyebutkan gateway di claude-gateway.internal.example.com:

{
  "forceLoginMethod": "gateway",
  "forceLoginGatewayUrl": "https://claude-gateway.internal.example.com"
}

Ketika pengembang menjalankan /login di prompt Claude Code, layar Cloud gateway terbuka pada alamat tersebut dan mereka menekan Enter untuk terhubung. Prompt sidik jari TLS koneksi pertama tetap muncul. Batasan berikut berlaku untuk kunci yang ditetapkan dengan cara ini:

• Hanya pengaturan pengguna: Claude Code membaca kedua kunci dari ~/.claude/settings.json, bukan dari .claude/settings.json atau .claude/settings.local.json milik proyek.
• Pengaturan terkelola menonaktifkannya: begitu pengaturan administrator mencapai mesin melalui file pengaturan terkelola, plist macOS atau kebijakan HKLM Windows, atau policy helper, Claude Code mengabaikan gateway yang disebutkan di pengaturan pengguna.

Mengizinkan gateway pada ruang alamat publik milik Anda

Beberapa organisasi memberi nomor jaringan internal mereka dari blok IPv4 publik yang mereka miliki, seperti ruang alamat milik operator sendiri atau /8 lama, sehingga gateway mereka tidak memiliki alamat privat. Cantumkan blok-blok tersebut di pengaturan terkelola gatewayInternalNetworks. /login kemudian menerima gateway di dalam blok yang tercantum ketika mesin pengembang terhubung ke gateway tersebut dari alamat di dalam blok yang sama. Ini memerlukan Claude Code v2.1.268 atau yang lebih baru di mesin pengembang; versi sebelumnya mengabaikan kunci ini dan menerapkan aturan alamat privat.

[!WARNING]

gatewayInternalNetworks ditujukan untuk jaringan internal yang kebetulan diberi nomor dari ruang alamat publik. Kunci ini tidak membuat aman untuk mengekspos gateway ke internet: gateway tepercaya dapat mendorong pengaturan yang menjalankan perintah di mesin pengembang.

Pastikan gateway tidak dapat dijangkau dari luar jaringan Anda dengan aturan firewall atau load balancer Anda. Tetapkan access_control.allow_cidrs milik gateway ke blok yang sama dengan yang Anda deklarasikan di sini. Jika load balancer atau ingress termasuk dalam listen.trusted_proxies, cantumkan juga di sana, karena jika tidak, gateway mencocokkan allow_cidrs dengan alamat frontend itu sendiri, bukan alamat pengembang.

Tambahkan kunci ini ke sumber pengaturan terkelola yang sama dengan kunci login: file pengaturan terkelola, profil MDM, atau kebijakan registry. Claude Code mengabaikannya di pengaturan pengguna, proyek, dan pengaturan yang dikelola server.

Contoh ini mendeklarasikan satu blok. Ganti 203.0.113.0/24 dengan blok Anda sendiri. Itu adalah rentang dokumentasi, dan Claude Code menolaknya.

{
  "gatewayInternalNetworks": ["203.0.113.0/24"]
}

Claude Code memvalidasi daftar tersebut saat /login sebelum menghubungi gateway mana pun:

• Setiap entri adalah blok IPv4 yang ditulis sebagai alamat pertamanya dan prefiks dari /8 hingga /32.
• Daftar berisi paling banyak empat blok, dan tidak ada dua blok yang tumpang tindih.
• Tidak ada blok yang tumpang tindih dengan ruang alamat privat: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.0/8, 169.254.0.0/16, dan 100.64.0.0/10. /login sudah menerima gateway di sana tanpa kunci ini.
• Tidak ada blok yang tumpang tindih dengan ruang yang tidak pernah menjadi jaringan organisasi: 198.18.0.0/15 dan 192.0.0.0/24, yang digunakan klien VPN dan NAT64 sebagai alamat lokal; rentang dokumentasi 192.0.2.0/24, 198.51.100.0/24, dan 203.0.113.0/24; serta rentang yang dicadangkan 0.0.0.0/8, 192.88.99.0/24, dan multicast 224.0.0.0/4. Anda dapat mendeklarasikan blok di dalam 240.0.0.0/4, yang digunakan beberapa jaringan besar sebagai ruang unicast internal.

Blok dari managed-settings.json dan file drop-in managed-settings.d/-nya digabungkan menjadi satu daftar, dan batasan ini berlaku untuk daftar gabungan tersebut. Untuk mempersempit blok, ganti entrinya alih-alih menambahkan entri kedua yang tumpang tindih di drop-in; /login menolak tumpang tindih tersebut.

Jika sebuah entri melanggar aturan, atau nilainya bukan daftar string, Claude Code menolak setiap proses masuk gateway baru di mesin tersebut dan menyebutkan masalahnya di pesan. Proses masuk ke gateway pada alamat privat juga gagal, sedangkan sesi masuk yang sudah ada tetap berfungsi. Coba nilainya di satu mesin sebelum Anda men-deploy-nya. Claude Code juga mencantumkan nilai dengan tipe yang salah di antara pengaturan terkelola tidak valid yang dilaporkannya.

Dengan daftar yang valid, /login menerapkan tiga pemeriksaan pada gateway yang alamatnya berada di dalam blok yang tercantum:

• Setiap alamat yang di-resolve dari hostname gateway berada di dalam blok yang satu itu. Claude Code menolak nama yang juga memiliki record di luar blok tersebut, termasuk alamat privat dan IPv6.
• Mesin pengembang terhubung dari dalam blok yang sama. Claude Code menolak mesin di balik NAT, di dalam container atau WSL2, atau pada VPN yang kumpulan alamatnya berada di luar blok, dan menyebutkan alamat asal koneksi mesin tersebut.
• Koneksinya langsung. Jika HTTPS_PROXY berlaku untuk host gateway, /login menolak dan menyebutkan entri NO_PROXY yang perlu ditambahkan.

Ketika ketiganya lolos, prompt kepercayaan menambahkan baris yang menyebutkan alamat mesin, alamat gateway, dan blok yang dideklarasikan yang memuat keduanya.

Kunci ini tidak mengubah apa pun untuk gateway lain: proses masuk ke gateway pada alamat privat berfungsi seperti sebelumnya, dan proses masuk ke gateway pada alamat publik di luar semua blok yang tercantum tetap ditolak seperti sebelumnya.

Blok yang dideklarasikan mempersempit siapa yang dapat masuk tetapi tidak membuktikan di mana sebuah mesin berada, jadi deklarasikan hanya ruang alamat yang dikendalikan organisasi Anda. Blok yang dibagikan dengan tenant lain, seperti rentang publik penyedia cloud, memungkinkan siapa pun di dalamnya lolos pemeriksaan yang sama.

Mengirimkan kebijakan ke sesi Claude Desktop

Claude Desktop menjalankan tab-tabnya pada sesi Claude Code tersemat dan mengirimkan permintaan model mereka melalui gateway. Claude Desktop meneruskan kebijakan ke setiap sesi tersebut, yang dibangun dari konfigurasi yang disajikan gateway kepadanya di /user/bootstrap. Konfigurasi tersebut memuat allowlist model, tool yang dinonaktifkan, dan allowlist egress yang diturunkan dari blok cli atau code kebijakan yang cocok, ditambah overlay desktop.

Kunci lain dalam blok tersebut, seperti hook, env, dan aturan izin terbatas seperti Bash(npm *), menjangkau klien yang masuk melalui /login. Di bawah code, kunci-kunci tersebut juga menjangkau sesi tab Code ketika kondisi untuk tab Code terpenuhi. Kunci-kunci tersebut tidak menjangkau sesi Cowork atau Chat. Claude Desktop membaca URL gateway dari konfigurasi terkelolanya sendiri dan masuk dengan alurnya sendiri, terpisah dari kunci forceLoginMethod dan forceLoginGatewayUrl di Menetapkan URL gateway.

Pengaturan yang diteruskan oleh proses peluncur adalah pengaturan induk. Claude Code mengabaikan pengaturan induk di mesin mana pun yang memiliki sumber terkelola yang di-deploy admin, kecuali sumber yang mengirimkan kebijakan menetapkan parentSettingsBehavior: "merge".

Mesin mana yang memerlukan opt-in

Mesin yang hanya menjalankan Claude Desktop memerlukannya. Claude Desktop sendiri menerapkan daftar model dan daftar tool yang dinonaktifkan ke sesi tersemat, tetapi allowlist egress hanya mencapai sesi tersebut sebagai pengaturan induk, dalam bentuk aturan domain WebFetch dan aturan jaringan sandbox. Tanpa opt-in, sesi tersebut berjalan tanpa pembatasan egress, dan tidak ada yang memperingatkan Anda. Gateway tetap menolak permintaan inferensi untuk model yang tidak diberikan oleh kebijakan.

Allowlist marketplace plugin juga hanya mencapai sesi tersemat sebagai pengaturan induk. Ketika Anda menonaktifkan marketplace plugin yang ditambahkan pengguna di konfigurasi terkelola Claude Desktop, Claude Desktop 2.16120.0 atau yang lebih baru menyembunyikan marketplace yang tidak disediakan organisasi Anda dan menolak instalasi dari marketplace tersebut. Untuk menghentikan sesi tersemat memuat plugin yang sudah diinstal dari marketplace tersebut, Claude Desktop mengirimkan daftar strictKnownMarketplaces sebagai pengaturan induk. Tanpa opt-in, Claude Code mengabaikan daftar tersebut, dan plugin-plugin itu tetap dimuat.

Mesin tempat pengembang masuk melalui /login tidak memerlukannya; setiap sesi Claude Code mengambil kebijakannya dari gateway.

Armada yang policyHelper-nya menyediakan pengaturan terkelola tidak dapat menggunakannya: Claude Code tidak pernah menggabungkan pengaturan induk pada armada tersebut, karena Claude Code membaca pengaturan terkelola hanya dari output helper.

Menetapkan opt-in

Deploy cuplikan pengaturan terkelola dari Menetapkan URL gateway, cerminkan ke sumber sisi klien mana pun yang peringkatnya lebih tinggi dari file tersebut, lalu verifikasi.

1. Deploy opt-in di file pengaturan terkelola

Cuplikan di atas sudah menyertakan parentSettingsBehavior: "merge", sehingga file yang Anda dorong ke mesin sudah memuatnya.

2. Cerminkan cuplikan ke sumber mana pun yang peringkatnya lebih tinggi dari file

Claude Code membaca parentSettingsBehavior hanya dari sumber yang dipilih. Menambahkan kunci kebijakan apa pun ke sebuah sumber dapat menjadikan sumber tersebut sebagai sumber yang dipilih, jadi di sumber sisi klien, cerminkan seluruh cuplikan, bukan hanya parentSettingsBehavior. Pengaturan terkelola sisi klien membahas armada yang mengirimkan kebijakan melalui Group Policy atau profil konfigurasi. Plist managed-preferences di macOS atau kebijakan HKLM di Windows peringkatnya lebih tinggi dari file managed-settings.json, dan pengaturan terkelola jarak jauh milik gateway sendiri peringkatnya lebih tinggi dari keduanya, jadi pada mesin yang masuk ke gateway, tetapkan juga parentSettingsBehavior di blok cli atau code kebijakan gateway.

3. Periksa sumber mana yang dipilih

Pada mesin yang hanya menjalankan Claude Desktop, panggil resolveSettings() milik Agent SDK dan baca policyOrigin pada entri managed di daftar sources-nya. Nilainya menyebutkan sumber sisi klien yang dipilih, plist, hklm, atau file, yang merupakan sumber yang harus memuat cuplikan tersebut.

Sesi Cowork dan Chat tidak mengambil kebijakan gateway, sehingga blok gateway bukan sumber yang dipilih untuk sesi tersebut.

Sesi tab Code mengambilnya ketika pengaturan kebijakan berada di bawah code dan kondisi untuk tab Code terpenuhi. Pengaturan code gateway kemudian menjadi sumber yang dipilih untuk sesi tersebut.

Membatasi pengaturan induk

Setelah Anda men-deploy parentSettingsBehavior: "merge", proses host mana pun yang meluncurkan Claude Code dapat menyediakan pengaturan induk, bukan hanya Claude Desktop tetapi juga aplikasi Agent SDK atau ekstensi IDE.

Claude Code menyaring pengaturan induk terhadap allowlist kunci yang bersifat membatasi, tetapi beberapa kunci yang diizinkan dapat memberikan akses alih-alih membatasinya. Kecuali Anda menetapkan kunci allowManaged*Only, aturan allow izin dan allowlist sandbox yang disediakan host tetap berlaku. Aturan deny dan ask dalam kebijakan Anda tetap berlaku dalam kedua kasus; aturan tersebut dievaluasi sebelum aturan allow mana pun.

Claude Code meneruskan entri sandbox.credentials yang disediakan induk dalam bentuk yang dipangkas:

• Entri deny: diteruskan hanya dengan path atau name-nya dan mode.
• Entri file dengan mode: mask: diteruskan hanya sebagai sentinel, sebagai mask seluruh file yang injectHosts-nya berupa daftar kosong, sehingga proxy tidak pernah mengganti nilai asli untuk entri yang disediakan induk di platform mana pun. Semua field structured-masking juga dibuang, sehingga pola ekstraksi yang disediakan induk tidak dapat menggantikan mask yang lebih ketat yang ditetapkan sumber lain untuk path yang sama.
• Entri envVars dengan mode: mask: tidak diteruskan. deny adalah satu-satunya pembatasan yang dapat diekspresikan saluran induk melalui entri envVars.
• awsPairs dan sigv4: diteruskan hanya sebagai pembatasan. Dari sigv4, hanya nilai deny yang dipertahankan, dan induk yang mendefinisikan blok sigv4 sama sekali akan mematok ketiga bentuk permintaan, streaming, presigned, dan sigv4a, ke deny. Pasangan awsPairs tidak pernah diteruskan dalam bentuk yang dapat menandatangani ulang; pasangan yang menyebutkan salah satu variabel AWS konvensional diganti dengan entri inert yang tetap menekan pemasangan otomatis AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, dan AWS_SESSION_TOKEN.

Men-deploy kunci pengunci

Untuk menjaga pengaturan induk sedekat mungkin dengan hanya-pembatasan sejauh yang didukung filter, tambahkan kelima kunci allowManaged*Only, beserta allowlist yang diaturnya, ke sumber yang sama dengan opt-in merge:

{
  "forceLoginMethod": "gateway",
  "forceLoginGatewayUrl": "https://claude-gateway.internal.example.com",
  "parentSettingsBehavior": "merge",
  "allowManagedPermissionRulesOnly": true,
  "allowManagedMcpServersOnly": true,
  "allowManagedHooksOnly": true,
  "allowedMcpServers": [{ "serverUrl": "https://mcp.internal.example.com/*" }],
  "sandbox": {
    "network": {
      "allowManagedDomainsOnly": true,
      "allowedDomains": ["github.com", "*.npmjs.org"]
    },
    "filesystem": {
      "allowManagedReadPathsOnly": true,
      "denyRead": ["~/"],
      "allowRead": ["~/projects"]
    }
  }
}

Kebijakan OS, seperti kebijakan registry HKLM atau plist managed-preferences, peringkatnya lebih tinggi dari file ini, jadi kirimkan seluruh cuplikan melaluinya alih-alih melalui file. Pengaturan terkelola jarak jauh milik gateway peringkatnya lebih tinggi dari sumber kebijakan OS dan file tetapi hanya menjangkau klien yang terhubung. Cerminkan kunci pengunci, allowlist, dan opt-in merge ke blok cli atau code kebijakan dan tetap deploy file ini, karena mesin yang tidak pernah terhubung mendapatkan kebijakannya hanya dari file.

Perilaku kunci pengunci di berbagai sumber

Menetapkan satu kunci pengunci tidak membatasi yang lain; setiap kunci didokumentasikan di referensi pengaturan.

Dari sumber admin di bawah pemenang, kedua kunci pengunci sandbox tetap berlaku, dan allowManagedPermissionRulesOnly tetap memblokir aturan allow dan additionalDirectories yang disediakan induk. Pada Claude Code v2.1.273 atau yang lebih baru, kunci pengunci server MCP juga berlaku dari sumber di bawah pemenang, dan selama kunci tersebut aktif, daftar allowedMcpServers terkelola berasal dari sumber admin berprioritas tertinggi yang menetapkannya.

Kunci pengunci hook dan efek allowManagedPermissionRulesOnly pada aturan milik pengembang sendiri memerlukan sumber pemenang secara default; di bawah opt-in merge managedSourcesBehavior di cara Claude Code menggabungkan sumber terkelola, Claude Code menerapkan nilai paling ketat yang ditetapkan sumber mana pun untuk setiap kunci pengunci. Pada armada policyHelper, Claude Code membaca kunci pengunci hanya dari output helper.

Setiap kunci pengunci membuat Claude Code mengabaikan entri milik pengembang sendiri untuk pengaturan tersebut, jadi sertakan allowlist organisasi Anda di samping kunci pengunci:

• Domain jaringan: mengunci dengan daftar domain terkelola yang kosong memblokir semua lalu lintas keluar yang di-sandbox.
• Server MCP: mengunci tanpa allowedMcpServers di sumber admin mana pun maupun di pengaturan yang disediakan induk akan memuat setiap server yang tidak diblokir oleh deniedMcpServers.
• Path baca: entri allowRead hanya mengizinkan kembali path di dalam wilayah denyRead, jadi pasangkan dengan denyRead terkelola.

Pengaturan yang tidak dicakup kunci pengunci

Pengaturan yang disediakan induk berikut lolos filter bahkan dengan kelima kunci pengunci ditetapkan:

• forceLoginOrgUUID: Claude Code menghormati nilai yang disediakan induk ketika pengaturan terkelola yang diterapkannya tidak menetapkan UUID organisasi. Proses masuk gateway tidak memeriksa kunci ini. UUID organisasi dalam pengaturan terkelola yang diterapkan Claude Code memblokir nilai induk dan menjadi UUID organisasi yang ditegakkan Claude Code. Jika armada Anda mematok organisasi Anthropic, lihat Sumber terkelola mana yang menyediakan kunci login untuk mengetahui di mana menetapkan forceLoginOrgUUID.
• allowedMcpServers: Claude Code menghormati allowlist yang disediakan induk ketika tidak ada daftar admin yang berlaku. allowManagedMcpServersOnly tidak memblokirnya, karena kunci pengunci menegakkan daftar mana pun yang menang sebagai nilai terkelola, termasuk daftar yang disediakan induk ketika tidak ada sumber admin yang menyediakan daftar. Daftar di sumber admin berprioritas tertinggi memblokir daftar induk dan menjadi daftar yang ditegakkan Claude Code, jadi tetapkan allowedMcpServers di sana, di samping kunci pengunci. Sebelum v2.1.223, nilai untuk salah satu kunci di sumber admin mana pun memblokir nilai induk.
• availableModels: Claude Code menghormati daftar model yang disediakan induk ketika sumber terkelola pemenang tidak menetapkannya. Jika armada Anda membatasi model, tetapkan availableModels di sumber pemenang.
• allowedProviders: Claude Code menghormati allowlist penyedia API yang disediakan induk ketika sumber terkelola pemenang tidak menetapkannya. Jika armada Anda membatasi penyedia API mana yang dapat digunakan pengembang, tetapkan allowedProviders di sumber pemenang. Memerlukan Claude Code v2.1.285 atau yang lebih baru.
• strictKnownMarketplaces: Claude Code menghormati allowlist marketplace plugin yang disediakan induk ketika sumber terkelola pemenang tidak menetapkannya. Claude Desktop 2.16120.0 atau yang lebih baru mengirimkannya ketika konfigurasi terkelolanya menonaktifkan marketplace plugin yang ditambahkan pengguna. Jika armada Anda membatasi marketplace, tetapkan strictKnownMarketplaces di sumber pemenang. Memerlukan Claude Code v2.1.282 atau yang lebih baru.
• blockedMarketplaces: blocklist marketplace yang disediakan induk lolos dan ditambahkan ke blocklist apa pun yang ditetapkan sumber terkelola, karena blocklist hanya dapat membatasi lebih lanjut. Memerlukan Claude Code v2.1.282 atau yang lebih baru.
• strictPluginOnlyCustomization: kunci ini lolos filter terlepas dari kunci pengunci apa pun, dan membuat Claude Code mengabaikan kustomisasi milik pengembang sendiri, termasuk hook pelindung. Tidak ada kunci pengunci yang memblokirnya.

Jika Anda menetapkan managedSourcesBehavior ke "merge", periksa nilai sumber mana yang berlaku untuk setiap jenis kunci.

Cara kunci hook dan skill dalam pengaturan induk berlaku

Kunci yang diteruskan aplikasi Anda dalam opsi managedSettings milik Agent SDK adalah pengaturan induk. Pada mesin tempat administrator men-deploy pengaturan terkelola, Claude Code mengabaikan pengaturan induk kecuali administrator mengizinkan host penyemat menambahkan kebijakan.

Jika Anda meneruskan disableAllHooks: true di managedSettings:

• Berhenti: hook pengguna, proyek, dan lokal, ditambah hook yang dideklarasikan di frontmatter agent atau di opsi settings milik SDK.
• Tetap berjalan: callback hook SDK aplikasi Anda dan hook administrator dari pengaturan terkelola. Aplikasi Anda tidak dapat menonaktifkan hook administrator.

Meneruskan kunci-kunci ini di managedSettings memerlukan Claude Code v2.1.309 atau yang lebih baru, atau TypeScript Agent SDK v0.3.309 atau yang lebih baru.

Menghubungkan Claude Desktop

Claude Desktop terhubung ke gateway yang sama melalui kunci MDM yang berbeda: tetapkan bootstrapUrl di konfigurasi terkelola Claude Desktop ke <listen.public_url>/user/bootstrap, dan ikutsertakan kebijakan pengguna dengan kunci desktop. Overlay Claude Desktop membahas kedua bagian tersebut. Memerlukan Claude Code v2.1.203 atau yang lebih baru di server gateway. Setelah terhubung, Claude Desktop mengirimkan permintaan model dari setiap tab yang diaktifkan melalui gateway.

Claude Desktop memasukkan pengembang melalui penyedia identitas gateway dengan langkah SSO browser yang sama, lalu mengambil konfigurasinya dari gateway alih-alih dari Anthropic. Akses model dan kebijakan mengikuti aturan per grup yang sama dengan CLI. Pengembang yang menggunakan CLI dan Claude Desktop masuk ke masing-masing secara terpisah; sesi gateway tidak dibagikan di antara keduanya.

Pipeline CI dan mesin jarak jauh

Tidak ada alur token layanan untuk pipeline tanpa pengawasan. Proses masuk gateway selalu menjalankan alur perangkat browser, sehingga job CI tanpa pengembang yang menyetujui proses masuk tidak dapat melakukan autentikasi; konfigurasikan job tersebut langsung terhadap penyedia Anda. Deploy forceLoginMethod dan forceLoginGatewayUrl ke mesin pengembang dan jangan tetapkan di runner CI. Pada mesin yang pengaturan terkelolanya menetapkan keduanya, sesi yang melakukan autentikasi dengan ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, atau apiKeyHelper keluar saat startup.

Setelah pengembang masuk, setiap sesi Claude Code di mesin tersebut menggunakan sesi gateway, termasuk eksekusi claude -p non-interaktif dan sesi yang dimulai oleh Agent SDK. Claude Code menerapkan kebijakan gateway ke masing-masing sesi tersebut.

Alur perangkat memisahkan CLI yang melakukan polling dari browser yang menyetujui, sehingga mesin pengembangan jarak jauh tanpa layar tetap berfungsi: pengembang menjalankan /login melalui SSH di mesin jarak jauh dan membuka tautan verifikasi di browser pada laptop mereka.

Apa yang ditegakkan pada pengembang

Jaminan berikut berlaku untuk setiap sesi yang masuk melalui /login. Sesi tersemat yang diluncurkan Claude Desktop mendapatkan kebijakannya seperti dijelaskan di Mengirimkan kebijakan ke sesi Claude Desktop, dan poin telemetri menjelaskan ke mana ekspor mereka dikirim.

• Akses model: permintaan untuk model yang tidak diberikan kebijakan mengembalikan 400, dan pemilih /model difilter ke allowlist availableModels kebijakan. Ini termasuk model yang digunakan sesi saat dimulai sebelum pengembang memilih model; lihat Memulai sesi pada model yang diizinkan kebijakan.
• Tujuan telemetri: dalam sesi yang masuk melalui /login, CLI mengirimkan ekspor OTLP/HTTP-nya ke gateway alih-alih ke OTEL_EXPORTER_OTLP_ENDPOINT yang ditetapkan secara lokal, kecuali sebuah kebijakan menyebutkan kolektor Anda sebagai endpoint. Gateway meneruskan ekspor yang diterimanya ke tujuan di telemetry.forward_to.
  • Dalam sesi tersemat yang diluncurkan Claude Desktop, CLI mengirimkan ekspornya ke OTEL_EXPORTER_OTLP_ENDPOINT yang dikonfigurasi. CLI melampirkan token sesi gateway ke ekspor tersebut hanya ketika endpoint itu mengarah ke gateway itu sendiri.
  • Tanpa tujuan yang dikonfigurasi untuk suatu sinyal, gateway menerima dan membuangnya.
  • Jika Anda sudah mengumpulkan telemetri Claude Code secara langsung, tambahkan kolektor Anda sebagai tujuan forward_to, atau sebutkan dalam kebijakan untuk melewati relay.
• Kredensial: token gateway adalah satu-satunya kredensial sesi. Profil Anthropic dan login claude.ai sebelumnya diabaikan selama masuk, sehingga pengembang tidak perlu keluar dari claude.ai terlebih dahulu. Untuk kredensial ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, atau apiKeyHelper yang dikonfigurasi, atau kunci API yang disimpan oleh login Claude Console sebelumnya, lihat Administrator policy requires a Cloud gateway sign-in.
• Pengaturan terkelola: kunci yang dikunci tidak dapat ditimpa secara lokal. CLI menerapkan kebijakan saat startup dan menerapkan perubahan pada setiap polling per jam, kecuali perubahan yang hanya berlaku pada peluncuran berikutnya.
• Startup saat gateway tidak dapat dijangkau: sesi yang sudah masuk keluar saat startup dengan error setelah sekitar 10 detik alih-alih dimulai tanpa pengaturannya.
• Startup setelah gateway mengakhiri sesi: lihat Menegakkan startup fail-closed untuk peluncuran yang terbuka dalam keadaan keluar dari gateway dan peluncuran yang keluar ketika gateway menjawab dengan 401.
• Deprovisioning: sesi yang penggunanya dinonaktifkan di IdP kedaluwarsa dalam ttl_hours ketika penyegaran berikutnya gagal.
• Keluar: /logout menghapus kredensial gateway dari mesin pengembang.
  • Ketika dokumen discovery gateway mengiklankan revocation_endpoint pada skema, host, dan port URL gateway itu sendiri, /logout juga mengirimkan token yang tersimpan ke endpoint tersebut sehingga gateway dapat mengakhiri sesi di sisinya. Permintaan ini bersifat best effort, sehingga proses keluar selesai di mesin pengembang baik endpoint menjawab maupun tidak. Pencabutan ini memerlukan Claude Code v2.1.275 atau yang lebih baru di mesin pengembang.
  • Server gateway di dalam binary claude tidak mengiklankannya, sehingga keluar dari server tersebut hanya mengakhiri sesi di mesin pengembang. Untuk memaksa sesi keluar di sisi server, lihat Rotasi secret JWT.

Apa yang dapat dilihat organisasi

Telemetri penggunaan membawa identitas pengembang, jumlah token, model, dan latensi ke kolektor organisasi. Gateway tidak mencatat atau menyimpan konten prompt atau completion. Apakah telemetri yang lebih kaya seperti log dan trace dikumpulkan, yang dapat mencakup perintah dan path file, merupakan pilihan per tujuan organisasi.

Ketersediaan dan keterbatasan

Tabel mencakup fitur Claude Code mana yang bekerja ketika pengembang terhubung melalui gateway, dan apa yang didukung server gateway itu sendiri. Di mana sesuatu tidak didukung, kolom Catatan memberikan alternatif.

Gateway mengirimkan nilai anthropic-beta yang dikirim CLI ke setiap upstream, jadi operator tidak mempertahankan allowlist beta. Untuk Amazon Bedrock, yang mengabaikan header, gateway memindahkan nilai ke bidang anthropic_beta badan permintaan; upstream lainnya menerima header seperti yang dikirim.

Langkah berikutnya

Quickstart meninggalkan Anda dengan konfigurasi minimal yang berjalan di bawah Docker Compose. Untuk membawanya lebih jauh:

• Perluas gateway.yaml di luar konfigurasi minimal, misalnya untuk menambahkan RBAC per-grup, failover multi-upstream, atau tujuan telemetri. Referensi konfigurasi mencakup setiap opsi.
• Pindah dari Compose ke penyebaran produksi di Kubernetes atau Cloud Run, siapkan IdP Anda dengan benar, dan tinjau model keamanan. Panduan penyebaran dan operasi mencakup penyiapan per-IdP, persyaratan gambar kontainer, probe kesehatan, dan pemecahan masalah.
• Letakkan batas pengeluaran pada pengembang atau grup individual sehingga beban kerja yang liar tidak dapat mengonsumsi seluruh komitmen Anda. Spend limits mencakup API admin dan cara penegakan bekerja.
• Untuk contoh lengkap yang dikerjakan di AWS, dengan ECS Fargate atau EKS, Amazon RDS, dan Secrets Manager, lihat Deploy on AWS.
• Untuk contoh lengkap yang dikerjakan di Google Cloud, dengan Cloud Run, Cloud SQL, dan Secret Manager, lihat Deploy on Google Cloud.