Panduan Sambung Claude Code ke API Pihak Ketiga: Konfigurasi ANTHROPIC_BASE_URL & Penyelesaian Masalah

Secara lalai, Claude Code menghantar semua request ke API rasmi Anthropic. Apabila laluan rasmi tidak stabil dari rangkaian anda, atau anda mahu urus kunci, bil dan pertukaran model di satu tempat, menghalakan Claude Code ke endpoint pihak ketiga yang serasi dengan Anthropic ialah penyelesaian paling langsung. Panduan ini hanya menyentuh konfigurasi sebenar: apa yang diubah, cara sahkan ia berfungsi, dan di mana mula memeriksa apabila berlaku masalah.

Fahami dahulu: Claude Code ialah "klien"

Definisi: Claude Code membaca sekumpulan kecil environment variable untuk menentukan ke mana request dihantar, kunci mana yang digunakan, dan model mana yang dijalankan. Selagi endpoint sasaran melaksanakan format request/response Anthropic Messages API, Claude Code berfungsi dengannya sama seperti dengan API rasmi — tool calling, streaming dan sesi berbilang giliran bergantung pada keserasian endpoint.

Penggantian base URL ialah keupayaan yang didokumenkan, bukan laluan belakang. EXAIV menyediakan endpoint serasi Anthropic; lihat halaman persediaan rasmi untuk versi ringkas.

Environment variable yang menentukan

Kaedah 1: settings.json (disyorkan, kekal)

Claude Code membaca environment variable dari ~/.claude/settings.json, terpakai bagi setiap sesi dan mudah distandardkan merentas pasukan. Contoh untuk EXAIV:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "env": {
    "ANTHROPIC_BASE_URL": "https://exaiv.com/api/ai/v1/anthropic",
    "ANTHROPIC_API_KEY": "YOUR_EXAIV_API_KEY",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  },
  "model": "claude-opus-5-5"
}

Mulakan semula claude selepas menyimpan. Untuk hadkan pada satu projek, letakkan struktur sama dalam .claude/settings.json di akar projek.

Kaedah 2: environment variable sementara (ujian pantas)

Tanpa ubah sebarang fail — export dalam shell semasa:

export ANTHROPIC_BASE_URL="https://exaiv.com/api/ai/v1/anthropic"
export ANTHROPIC_API_KEY="YOUR_EXAIV_API_KEY"

# Pengesahan minimum
claude --print "say hi"

Jika ia membalas, endpoint sudah aktif. Untuk kekal, dua baris export boleh dimasukkan ke ~/.zshrc atau ~/.bashrc — tetapi ia menjejaskan semua arahan claude. Jika anda juga mempunyai langganan rasmi, lebih baik guna settings.json aras projek supaya tidak tertumpah kredit pihak ketiga.

Di mana lihat model yang tersedia

Endpoint yang menentukan model yang wujud. Katalog penuh EXAIV (Claude, GPT, Gemini, DeepSeek, Kimi dan lain-lain) di halaman model; tukar model dalam Claude Code melalui ANTHROPIC_MODEL atau arahan /model dalam sesi.

Penyelesaian masalah: periksa mengikut turutan tetap

Siapa yang dapat manfaat daripada sambungan pihak ketiga

Bukan semua pengguna Claude Code perlu ini. Tiga senario dengan pulangan paling jelas:

Pengguna dengan laluan rasmi tidak stabil. Di sesetengah wilayah, mencapai endpoint rasmi kerap tamat masa — terhenti di tengah sesi coding adalah pembunuh produktiviti sebenar. Melalui gateway serasi yang lebih dekat, laluan lebih pendek dan kesinambungan sesi jelas bertambah baik.

Pengguna berat. Claude Code menggunakan token jauh lebih banyak daripada sembang biasa — setiap panggilan tool dan setiap bacaan fail dikira ke dalam context. Jika digunakan setiap hari, bayar ikut guna pada harga unit lebih rendah boleh memberi perbezaan bulanan yang ketara. Anggaran bezanya patut berdasarkan penggunaan sebenar anda, bukan nombor pemasaran mana-mana pihak.

Pasukan yang mahu satu pintu. Apabila pasukan menjalankan Claude Code, Cursor dan skrip dalaman serentak, menghalakan semua tool ke satu gateway dengan satu set kunci dan satu bil jauh lebih mudah dikawal berbanding akaun berasingan setiap tool. EXAIV menyediakan endpoint serasi OpenAI mahupun Anthropic — satu kunci meliputi dua protokol.

Cara kira kos: mulakan dengan pakej percubaan

EXAIV mengebil dalam kredit bayar ikut guna: beli pakej sekali sahaja, setiap panggilan ditolak mengikut harga model, tiada yuran langganan. Peringkat terendah ialah pakej terkecil yang disenaraikan di halaman harga — cukup untuk satu kitaran pengesahan sebenar:

1. Daftar dan jana kunci API dalam konsol
2. Konfigur Claude Code seperti di atas
3. Jalankan tugasan harian sebenar sejam dua, perhatikan lengkung baki dalam konsol
4. Anggarkan kos bulanan, kemudian putuskan naik pakej atau tidak

Setiap model ada harganya sendiri, harga tepat berada di halaman harga secara masa nyata — sebab itu artikel ini tidak pernah menulis nombor tetap bagi setiap panggilan: harga mengikut perubahan rasmi, halaman masa nyata sentiasa paling tepat.

Penggunaan pasukan: satu konfigurasi, sifar leret

Perangkap terbesar pasukan ialah setiap orang konfigur berbeza. Amalan yang berkesan:

Masukkan templat settings.json ke dalam repo. Simpan fail contoh tanpa kunci di akar projek; anggota baru salin dan isi kunci masing-masing. Lima minit siap.

Keluarkan kunci seorang demi seorang, jangan kongsi. Setiap ahli guna kunci sendiri dengan penggunaan jelas dalam konsol. Masalah mudah dikesan, dan berhenti kerja bermakna cabut satu kunci tanpa ganggu orang lain.

Asingkan konteks dengan skrip wrapper. Jika ahli turut memegang langganan rasmi, tulis skrip alias yang menunjuk ke konfigurasi aras projek supaya kuota rasmi dan pihak ketiga tidak terpakai bersilang.

Asas keselamatan

Kunci API ialah kredensial dompet. Empat peraturan asas:

• Kunci tidak pernah masuk git. Fail konfigurasi berkunci sebenar dikeluarkan daripada kawalan versi; dalam repo hanya templat tanpa kunci
• Putar berkala. Jana semula kunci dalam konsol dari semasa ke semasa dan tarik balik yang lama; syak bocor, tukar serta-merta
• Kebenaran minimum. Jangan tampal kunci dalam log CI, kod frontend atau sembang
• Pantau anomali. Jika kadar penurunan baki menyimpang daripada biasa, tarik balik kunci dahulu, siasat kemudian

Rujukan pantas persediaan ikut OS

Selebihnya — pemetaan model, turutan penyelesaian masalah, amalan keselamatan — serupa di semua platform.

Mengapa pemetaan tier lebih penting daripada disangka

Claude Code tidak hanya memanggil model utama pilihan anda. Di latar belakang ia menembak banyak request kecil — meringkas output tool, menulis mesej commit, carian pantas — dan request itu ditanda tier Sonnet atau Haiku. Jika endpoint anda tidak mempunyai model lalai tepat untuk tier tersebut, panggilan gagal atau fallback secara tidak diduga.

Itulah yang diselesaikan ANTHROPIC_DEFAULT_SONNET_MODEL dan ANTHROPIC_DEFAULT_HAIKU_MODEL: menghalakan request bertanda tier ke model yang benar-benar wujud di endpoint. Corak paling ringkas dan stabil ialah menetapkan kedua-duanya sama dengan model utama anda; memetakan tier Haiku ke model lebih murah ialah pengoptimuman biasa selepas semuanya stabil. Logik sama digunakan dalam gateway: semak halaman model untuk tahu apa yang ada, kemudian petakan tier ke model yang anda pasti tersedia.

Penalaan timeout dan rangkaian

Dua pembolehubah menyelesaikan hampir semua aduan sambungan:

• API_TIMEOUT_MS — giliran agen yang kompleks boleh sah mengambil masa beberapa minit; timeout pihak klien terlalu pendek membunuh request yang sebenarnya berjaya. Jika giliran terpotong tanpa mesej ralat, naikkan nilainya.
• Proxy bertindih — jika shell anda turut menetapkan HTTP_PROXY/HTTPS_PROXY, request mungkin berpusing melalui proxy tempatan sebelum sampai ke gateway. Apabila base URL betul tetapi sambungan tetap gagal, uji dengan pembolehubah proxy dilepas sebelum mengubah perkara lain.

Kedua-duanya tidak wajib secara lalai — ia dua knob pertama untuk diputar apabila tetapan betul tetapi laluan rangkaian salah.

Kajian kes penyahpepijatan sebenar

Corak kegagalan paling biasa, dari mula hingga akhir, supaya anda boleh padankan kes sendiri:

Seorang pembangun mengedit settings.json, menjalankan claude --print "say hi", dan menerima 401 authentication_error. Naluri menyalahkan endpoint. Yang dibuat pula ialah senarai semak:

1. Environment variables — kunci dalam settings.json betul, tetapi pembangun turut sempat export ANTHROPIC_API_KEY lama dalam shell yang sama hari itu. Pembolehubah shell mengatasi settings.json; kunci lapuk itulah yang dihantar. unset ANTHROPIC_API_KEY dan cuba semula — panggilan kini memulangkan teks
2. Base URL — tiada apa perlu dibaiki; ia betul dari mula
3. Kunci — kunci itu sendiri sah sejak awal; ia cuma dilindungi (shadowed)
4. Model ID — model utama yang dikonfigur wujud di endpoint; tetapi tugasan latar yang merujuk model Sonnet lalai gagal. Memetakan ANTHROPIC_DEFAULT_SONNET_MODEL ke model utama yang sama membuang ralat terakhir
5. Rangkaian — tidak pernah sampai ke sana; masalah ada di lapisan satu dan tiga

Jumlah masa daripada kekecewaan ke persediaan berfungsi: kira-kira empat minit, sebaik senarai semak menggantikan agakan. Pengajarannya umum: setiap lapisan sama ada berfungsi atau menunjuk ke lapisan seterusnya — jangan sesekali nyahpepijat dua lapisan serentak.

Satu tabiat yang menjimatkan masa: uji endpoint dahulu, bukan klien

Sebelum menyentuh sebarang konfigurasi, buktikan dahulu endpoint hidup dengan curl telanjang — tanpa Claude Code, tanpa SDK:

curl https://exaiv.com/api/ai/v1/anthropic/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"claude-opus-5-5","max_tokens":32,"messages":[{"role":"user","content":"hi"}]}'

Jika curl ini membalas, keseluruhan persoalan mengecil kepada konfigurasi klien. Jika gagal, anda tahu masalahnya di kunci atau rangkaian — bukan di Claude Code. Satu minit ujian ini menjimatkan berjam-jam meneka.

FAQ

Bacaan berkaitan

• Halaman persediaan Claude Code — versi ringkas di laman
• Rujukan Anthropic Messages API — format request/response
• Harga — harga model masa nyata