Claude Code လုံခြုံသော စီမံကိန်း နှင့် Relay API လုပ်ထုံးကောင်း

Claude Code နှင့် custom API integration များသည် prompt ထက်ပို၍ ပို့သည်၊ environment metadata၊ routing ရွေးချယ်မှုနှင့် retry အပြုအမူများကို ထုတ်ပြီး upstream စနစ်များက အကောင့် ကျန်းမာရေးနှင့် ဆက်စပ်နိုင်သည်။ ဤလမ်းညွန်သည် operational safety ကို ဦးစားပေးသည်၊ ကြားခံမှတ်တမ်းတိုင်တန်သော shell configuration၊ gateway ရွေးချယ်မှုနှင့် quota တင်းကျပ်လာသောအခါ graceful failover။ ရည်မှန်းချက်မှာ ယုံကြည်စိတ်ချရသော engineering workflow ဖြစ်ပြီး Anthropic မူဝါဒကို လွဲကျော်ခြင်း မဟုတ်ပါ။

သန့်ရှင်းသော အခြေခံနဲ့ စပါ၊ CLI variable များ ချိန်မီမီ environment cleanup and IP setup နှင့် VPN and proxy selection ကို ပြီးအောင်လုပ်ပါ။ relay သို့မဟုတ် multi-model router လုပ်ဆောင်ပါက degradation လမ်းကြောင်းများအတွက် domestic and open-source alternatives ကို ဖတ်ပါ။

1. Claude Code လုံခြုံရေး configuration များ

Claude Code သည် စဖွင့်ချိန်တွင် shell environment variable များကို ဖတ်သည်။ timezone၊ proxy သို့မဟုတ် base URL မတူညီမှုသည် ရှုပ်ထွေးသော error များ ထွက်စေနိုင်သည်၊ သို့မဟုတ် client သည် browser session ထက် မတူပြားစွာ လုပ်ဆောင်နိုင်သည်။ terminal ကို နောက်မှ စဉ်းစားရမည့် အရာမဟုတ် ဦးစားပေး environment အဖြစ် သတ်မှတ်ပါ။

အဓိက environment variable များ

# ~/.zshrc or ~/.bashrc — load in every interactive shell

# 1. Declare custom Anthropic-compatible endpoints explicitly
export ANTHROPIC_BASE_URL="https://your-gateway.example.com"
export ANTHROPIC_API_KEY="sk-your-key"

# 2. When using a trusted first-party-shaped gateway, reduce client mismatch warnings
export _CLAUDE_CODE_ASSUME_FIRST_PARTY_BASE_URL=1

# 3. Align terminal timezone with your documented operating region
export TZ=Asia/Tokyo   # or America/Los_Angeles — match proxy geo

# 4. Route CLI HTTPS through the same clean proxy as your browser (if required)
export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
export NO_PROXY="localhost,127.0.0.1,.internal"

Configuration စစ်ဆေးစာရင်း

1. တစ်ခုတည်းသော အမှန်တရား အရင်းအမြစ်: env var များကို ~/.zshrc (macOS) သို့မဟုတ် shell က source လုပ်သော ~/.claude/env ဖိုင်တွင် သိမ်းပါ၊ terminal tab တစ်ခုတည်းတွင် ad hoc export မလုပ်ပါနှင့်။
2. စဖွင့်မီ အတည်ပြုပါ: Claude Code စတင်သည့် အတူတူညီသော window တွင်ပင် env | grep -E 'ANTHROPIC|TZ|PROXY' ကို run ပါ။
3. browser နှင့် CLI geography ကိုက်ညီပါစေ: browser profile သည် anti-detect tool ဖြင့် Tokyo timezone သုံးပါက CLI သည် Asia/Shanghai မသတင်းပို့သင့်ပါ။
4. base URL ပြောင်းလဲမှုများကို မှတ်တမ်းတင်ပါ: တိုက်ရိုက် Anthropic မှ relay သို့ပြောင်းသောအခါ ANTHROPIC_BASE_URL နှင့် အတွင်းပိုင်း runbook နှစ်ခုလုံး ပြင်ပြီး အဖွဲ့ဝင်များ endpoint မရောအောင် စီမံပါ။
5. လျှို့ဝှက်ချက် သန့်ရှင်းမှု: API key များကို repo သို့ commit မလုပ်ပါနှင့်၊ env ဖိုင်တွင် chmod 600 သုံးပြီး relay key များကို သုံးလတိုင်း rotate လုပ်ပါ။

_CLAUDE_CODE_ASSUME_FIRST_PARTY_BASE_URL လုပ်သော အရာနှင့် မလုပ်သော အရာ

ဤ flag သည် Claude Code အား မူလမဟုတ်သော ANTHROPIC_BASE_URL ကို client-side အချို့စစ်ဆေးမှုများတွင် စံ Anthropic endpoint ဟု မှတ်ယူရန် ပြောသည်။ အဖွဲ့အစည်းက အတည်ပြုထားသော အတွင်းပိုင်း gateway လည်ပတ်သောအခါ ပွတ်တိုက်မှု လျှော့ချပေးသည်။ ၎င်းသည် server-side policy၊ billing သို့မဟုတ် eligibility ကို မပြောင်းပါ။ client metadata ကို မည်သို့ ဆက်လက် အကဲဖြတ်နိုင်သည်ကို Claude steganography and risk model တွင် ကြည့်ပါ။

မကြာခဏ ဖြစ်သော misconfiguration ပြဿနာများ

• split-brain proxy: browser သည် VPN သုံးပြီး CLI မသုံးပါ၊ request များသည် မတူညီသော ASN များမှ ထွက်သည်။ လက္ခဏာ၊ web chat အလုပ်လုပ်ပြီး CLI သည် 403 ပြန်သည်။
• သက်တမ်းကုန်နေသော NO_PROXY: 127.0.0.1 ပေါ်ရှိ local gateway သည် corporate proxy ကို bypass လုပ်ရမည်၊ မလုပ်ပါက loop များသည် connection reset ဖြင့် ကျရှုံးသည်။
• API key scope မှား: organization key နှင့် project key များသည် rate limit အောက်တွင် မတူညီစွာ အပြုအမူ လုပ်သည်၊ Anthropic console တွင် key အမျိုးအစား အတည်ပြုပါ။
• interactive vs non-interactive shell: Claude Code ခေါ်သော CI job များသည် env ဖိုင်တစ်ခုတည်းကို source လုပ်ရမည်၊ laptop များ၏ login shell များသည် ပျောက်နေသော export များကို မကြာခဏ ဖုံးကွယ်ထားသည်။

2. API relay gateway ရွေးချယ်ခြင်း

api.anthropic.com သို့ တိုက်ရိုက်ဝင်ရောက်မှု routing သို့မဟုတ် procurement ဖြင့် ကန့်သတ်ထားသောအခါ protocol fidelity ထိန်းသိမ်းနိုင်ပါက relay များသည် availability တိုးနိုင်သည်။ အရည်မပြည့်သော gateway သည် header များကို ငြိမ်းချင်းဖယ်ရှား၊ prompt များ ပြန်ရေးခြင်း သို့မဟုတ် latency spike ထည့်ပြီး မော်ဒယ် အရည်အသွေး ကျဆင်းသကဲ့သို့ မြင်ရစေနိုင်သည်။

Gateway အကဲဖြတ်မှု ဇယား

Prompt Cache ထိန်းသိမ်းမှု (ကုန်ကျစရိတ် သက်ရောက်မှု)

Anthropic prompt caching သည် ထပ်ခါ input ကုန်ကျမှု၏ 90% အထိ လျှော့နိုင်သည်။ cache header ဖယ်သော relay များသည် လှည့်တိုင်း full-price input token တောင်းသည်၊ system prompt ရှည်သောအခါ 4×–10× အံ့သြစရာ မကြာခဏ ဖြစ်သည်။ request နှစ်ခုတန် စမ်းသပ်ပါ။

# Request 1: create cache
curl -s "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: prompt-caching-2024-07-15" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-20250514","max_tokens":64,
       "system":[{"type":"text","text":"'$(python3 -c "print('x'*5000)")'",
         "cache_control":{"type":"ephemeral"}}],
       "messages":[{"role":"user","content":"ping"}]}'

# Request 2: expect cache_read_input_tokens > 0 in usage

အသေးစိတ် optimization စနစ်များကို API advanced optimization တွင် ကြည့်ပါ။

production မတိုင်မီ operational due diligence

• 24 နာရီ synthetic probe (15 မိနစ်တိုင်း message တစ်ခု) လုပ်ပြီး p95 latency နှင့် error rate တိုင်းပါ။
• request ID နမူနာ log လုပ်ပါ၊ အက်ပ်သည် incident များတွင် gateway log နှင့် upstream ID ဆက်စက်နိုင်ကြောင်း အတည်ပြုပါ။
• ဒေတာကိုင်တွယ်မှု သဘောတူစာချုပ် စစ်ဆေးပါ၊ relay အချို့သည် prompt log ရေး၍ abuse ရှာသည်၊ regulated workload အတွက် လက်မခံနိုင်ပါ။
• source code ကိုင်တွယ်သောအခါ opaque public reseller ထက် အဖွဲ့အစည်း ထိန်းချုပ်သော gateway (self-hosted LiteLLM၊ VPC ပေါ် One-API) ကို ဦးစားပေးပါ။

အကောင့် အဆင့်တည်ငြိမ်မှု သည် registration သန့်ရှင်းမှုနှင့် ဆက်စပ်နေသေးသည်၊ relay သုံးစဉ် org အသစ် ဖွင့်သောအခါ account registration and payment antiban ကို ကြည့်ပါ။

3. Rate limit (429) နှင့် smooth failover

Anthropic rate limit များသည် organization နှင့် model tier အဆင့်တွင် အသုံးချသည်၊ API key တစ်ခုတည်း သီးသန့် မဟုတ်ပါ။ burst agent၊ parallel CI job နှင့် ကန့်သတ်မထားသော retry loop များသည် မျှဝေထားသော quota ကုန်စေပြီး တူညီသော org ၏ မသက်ဆိုင်သော service များကို ပိတ်ဆို့နိုင်သည်။

ကန့်သတ်မှု အမျိုးအစားများ (ရိုးရှင်း)

Retry နှင့် failover စနစ်

// TypeScript — retry 429/529, failover on sustained pressure
async function callClaudeWithFallback(prompt: string, opts: CallOpts) {
  const maxRetries = 4;
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await callClaudeAPI(prompt, opts);
    } catch (error: any) {
      const status = error?.status;
      if (status === 429 || status === 529) {
        const delay = Math.min(30_000, 500 * 2 ** attempt + Math.random() * 250);
        await sleep(delay);
        continue;
      }
      if (status === 403) throw error; // surface auth issues
      throw error;
    }
  }
  console.warn('Claude quota saturated; failing over to backup upstream');
  return await callFallbackAPI(prompt, opts); // DeepSeek / GLM / local — see alternatives guide
}

Concurrency ထိန်းချုပ်မှု

• CI တွင် token bucket: organization တစ်ခုလျှင် parallel agent job (ဥပမာ အများဆုံး 3 ခု concurrent) ကန့်သတ်ပါ။
• Request coalescing: ဖြစ်နိုင်သမျှ file အလိုက် API call တစ်ခုတည်းအစား lint fix ငယ် များကို batch လုပ်ပါ။
• Circuit breaker: 429 ဆက်တိုက် N ခု နောက် 60 စက္ကန့် circuit ဖွင့်ပြီး အလိုအလျောက် fallback သို့ လွှဲပါ၊ retry storm ကို တားပါ။
• Observability: မက်ထရစ် ထုတ်ပါ၊ claude_requests_total{status}၊ fallback_invocations_total၊ p95 latency။ fallback rate သည် 10 မိနစ် 15% ကျော်ပါက alert ပေးပါ။

403 နှင့် 429၊ တူညီစွာ မကိုင်တွယ်ပါနှင့်

429 သည် ယာယီ ဖိအား ဖြစ်သည်၊ backoff ပြီး ဆက်လုပ်ပါ။ 403 သည် မကြာခဏ credential ပယ်ချခြင်း၊ ဒေသကန့်သတ်မှု သို့မဟုတ် အကောင့်အခြေအနေ ပြောင်းလဲမှုကို ညွှန်ပြသည်။ ရောဂါရှာခြင်းမရှိဘဲ အခြား key ဖြင့် 403 retry သည် enforcement ကို မြန်စေနိုင်သည်။ infrastructure rotate မလုပ်မီ error အမျိုးအစားခွဲရန် troubleshooting guide သုံးပါ။

FAQ

စနစ် timezone မှန်ပြီးသားဆိုလျှင် TZ သတ်မှတ်ရမလား။

OS timezone၊ proxy exit geo နှင့် browser profile တိမ်းညှိပြီးပါက explicit TZ သည် ပိုလိုအပ်ချက်မရှိနိုင်သော်လည်း CI container များသည် မကြာခဏ UTC default ဖြစ်သည်။ explicit export ဖြင့် laptop နှင့် server အလိုက် အပြုအမူ တိကျစေသည်။

ကုမ္ပဏီ source code အတွက် public API reseller သည် "လုံခြုံ" ဖို့ ရပါသလား။

တတိယပါတီ subprocessors အခြား တူညီစွာ သတ်မှတ်ပါ၊ log၊ retention နှင့် subprocessors စာရင်း စစ်ပါ။ proprietary code အတွက် VPC ပေါ် self-hosted relay သည် anonymous reseller ထက် သေချာ လုံခြုံသည်။

gateway ပြောင်းလိုက်လျှင် cache ခြောက်သက်သောက်ချက် ဘာလို့ ပျောက်သွားသလဲ။

အများဆုံး relay က anthropic-beta header များ ဖယ် သို့မဟုတ် system block များကို ပြန်စီပြီး cache key မမှန်စေသည်။ gateway ပြောင်းတိုင်း request နှစ်ခု cache test ပြန်လုပ်ပါ။

browser နှင့် Claude Code အတွက် proxy မတူကွဲ သုံးလို့ရမလား။

နည်းပညာအရ ရနိုင်သော်လည်း divergence အန္တရာယ် တိုးသည်။ သီးခြား profile တွင်စမ်းသပ် အကောင့် မခွဲသားပါက Claude traffic အားလုံး တူညီသော မှတ်တမ်းတင်ထားသော egress လမ်းကြောင်းကို ဦးစားပေးပါ။

429 ဖြစ်သောအခါ Claude Code က ဘယ် fallback model သုံးသင့်သလဲ။

Claude Code တွင် built-in multi-model failover မရှိ၊ gateway (One-API/LiteLLM) တွင် အကောင်အထည်ဖော် သို့မဟုတ် Claude Code ယာယီပိတ်ပြီး backup API ချိန်သော IDE plugin သုံးပါ။ routing table အတွက် domestic and open-source alternatives ကြည့်ပါ။

"curl တွင် အလုပ်လုပ်၊ Claude Code တွင် မအောင်မြင်" ကို ဘယ်လို debug လုပ်မလဲ။

1. Header ကွာချက်၊ mitmproxy သို့မဟုတ် gateway access log ဖြင့် curl နှင့် CLI ကို မှတ်ယူပါ။
2. စဖွင့်သော shell တွင် env အတည်ပြုပါ၊ IDE ထည့်သွင်းထားသော terminal များသည် login rc ဖိုင်ကို မကြာခဏ ကျော်သည်။
3. Node/fetch proxy agent စစ်ပါ၊ version အချို့သည် GLOBAL_AGENT_HTTP_PROXY မသတ်မှတ်ပါက HTTPS_PROXY ကို လျစ်လျူရှုသည်။
4. corporate network တွင် TLS interception စစ်ဆေးပါ။

first-party base URL ဟု ယူဆခြင်းသည် Anthropic billing ကို သက်ရောက်မလား။

မသက်ရောက်ပါ။ billing သည် တကယ် request ဝန်ဆောင်သည့် upstream နှင့် ချိတ်ထားသော API key နှင့် organization ကို လိုက်သည်။ gateway သည် Anthropic သို့ forward လုပ်ပါက Anthropic ကို ပေးချေသည်၊ model ပြောင်းလျှင် gateway ခေါ်သည့် provider ကို ပေးချေသည်။