وكيل Claude Code: توجيه Claude وGPT-5 وGemini عبر بوابة TrueFoundry للذكاء الاصطناعي

Introduction

Claude Code is the most powerful AI coding assistant available today. Engineers who adopt it rarely go back. But when dozens or hundreds of engineers start using it at the same time, a new problem appears: Claude Code, by default, talks directly to Anthropic's API. Every developer authenticates with their own key, uses Anthropic models exclusively, and generates API spend that is completely invisible to the platform team until the monthly invoice arrives.

A Claude Code proxy is the answer. By pointing Claude Code at a proxy endpoint instead of directly at Anthropic, you gain a centralized control point for every model call across your entire engineering organization: visibility into who is spending what, the ability to enforce budget caps before they're exceeded, access to models from any provider - GPT-5, Gemini 2.5 Pro, Llama via Bedrock - through the same interface Claude Code already knows, and the ability to deploy gateway configuration once and have it apply to all developers without touching individual machines.

TrueFoundry AI Gateway is the enterprise-grade Claude Code proxy. It is a drop-in Anthropic-compatible endpoint that Claude Code connects to with a single environment variable change. Once connected, every Claude Code request flows through the gateway giving you observability, cost controls, multi-model routing, and enterprise security policies that apply to the whole organization, not just the developers who remember to configure them.

This guide explains exactly what a Claude Code proxy does, why TrueFoundry AI Gateway is the right one for enterprise engineering teams, and how to configure it, including for both standard API key and Claude Max subscription flows.

What Is a Claude Code Proxy?

Claude Code ships with a single configuration knob for changing its backend: the ANTHROPIC_BASE_URL environment variable. When set, Claude Code sends all its API requests - messages, model calls, streaming responses to that URL instead of to https://api.anthropic.com.

That one variable is the foundation of every Claude Code proxy. A proxy is any server that:

1. Accepts Anthropic-format API requests from Claude Code
2. Adds controls, routing, or observability at the proxy layer
3. Forwards requests to the actual model provider (Anthropic, OpenAI, Google, Bedrock, on-prem)
4. Returns responses back to Claude Code in the format it expects

The simplest possible proxy is a reverse proxy with logging. The most sophisticated is an enterprise AI gateway that handles authentication, budget enforcement, model routing across providers, semantic caching, guardrails, and full audit trails - all transparently, with no changes to how Claude Code behaves for the developer.

Why do teams build or adopt a Claude Code proxy?

• Cost control: Multiple developers using Claude Code with individual Anthropic keys generate spend that is invisible until month-end. A proxy intercepts every request and enforces per-developer daily limits before costs exceed budget.
• Multi-model access: Claude Code's interface is powerful, but Claude models are not always the best or most cost-effective choice for every task. A proxy lets you route haiku-tier tasks to GPT-4o-mini or Gemini Flash, and opus-tier tasks to the best available model without any client-side changes.
• Enterprise security: Direct API keys on developer laptops are a security liability. A proxy centralizes credentials: developers authenticate to the proxy, and the proxy holds provider keys. No Anthropic key ever needs to live on a developer machine.
• Team-wide governance: Individual developers can configure their own ANTHROPIC_BASE_URL. But enforcing it across an entire team requires a centralized deployment mechanism - MDM, server-managed settings, or a shared project .claude/settings.json checked into version control.

Why TrueFoundry AI Gateway Is the Right Claude Code Proxy

There are three ways to proxy Claude Code: build your own, use a simple reverse proxy, or use a purpose-built AI gateway. Building your own means owning the maintenance, security, and reliability of a production API gateway. A simple reverse proxy adds logging but none of the controls. TrueFoundry AI Gateway gives you everything an enterprise engineering team actually needs without building or maintaining it.

TrueFoundry AI Gateway is a unified proxy layer between Claude Code and your model providers. It accepts the same Anthropic API format that Claude Code already speaks, so Claude Code never needs to know it's talking to a gateway rather than directly to Anthropic. Behind the gateway, you can connect any provider: Anthropic direct, AWS Bedrock, Google Vertex AI, Azure OpenAI, OpenAI, or your own on-prem models.

Here is what Claude Code actually sees:

Claude Code  →  ANTHROPIC_BASE_URL (TrueFoundry Gateway)  →  Anthropic / OpenAI / Gemini / Bedrock / On-prem

Every Claude Code request that flows through TrueFoundry gains, automatically:

~3–4ms p95 gateway overhead, 350+ RPS on a single vCPU. At Claude Code response times (seconds, not milliseconds), the gateway adds no perceptible latency.

Step 1: Point Claude Code at TrueFoundry AI Gateway

The core configuration is a single environment variable:

export ANTHROPIC_BASE_URL="https://<your-truefoundry-gateway-url>"

For persistent configuration - which is what you want for production use - edit Claude Code's settings.json. Two paths are supported:

• Global (applies to all projects): ~/.claude/settings.json
• Project-specific (checked into version control): .claude/settings.json in your project directory

Standard API Key Configuration

Use this when developers authenticate with a TrueFoundry API key (the recommended enterprise pattern — no Anthropic keys on developer machines):‍

{
  "env": {
    "ANTHROPIC_BASE_URL": "{GATEWAY_BASE_URL}",
    "ANTHROPIC_AUTH_TOKEN": "your-truefoundry-api-key",
    "ANTHROPIC_MODEL": "anthropic/claude-4-sonnet-20250514",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "anthropic/claude-4-opus-20250514",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "anthropic/claude-4-sonnet-20250514",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "anthropic/claude-3-5-haiku-20241022",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
    "ANTHROPIC_CUSTOM_HEADERS": "x-tfy-anthropic-beta: context-management-2025-06-27"
  }
}

What each field does:

• ANTHROPIC_BASE_URL — redirects all Claude Code requests to TrueFoundry
• ANTHROPIC_AUTH_TOKEN — TrueFoundry API key; authenticates the developer to the gateway (replaces Anthropic API key)
• ANTHROPIC_MODEL — the default model for Claude Code sessions
• ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_HAIKU_MODEL — map Claude Code's built-in model aliases (/model opus, /model sonnet, /model haiku) to your TrueFoundry-configured models
• CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS — disables experimental Claude Code features for stable gateway behavior
• ANTHROPIC_CUSTOM_HEADERS — forwards the x-tfy-anthropic-beta header to Anthropic for beta features like context management

Important: Claude Code detects model capabilities (extended thinking, ToolSearch, beta tool blocks) by string-matching the model ID. Make sure ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, and ANTHROPIC_DEFAULT_HAIKU_MODEL contain a recognizable Anthropic model ID like claude-opus-4-7، claude-sonnet-4-6، أو claude-haiku-4-5. إذا كنت تستخدم نموذجًا افتراضيًا من TrueFoundry، فتأكد من أن اسم عرضه يحتوي على معرف النموذج الأساسي - على سبيل المثال your-account/claude-haiku-4-5 — لضمان نجاح مطابقة السلسلة.

تكوين اشتراك Claude Code Max

إذا كان فريقك يستخدم اشتراكات Claude Code Max، فإن Claude Code يحجز Authorization لرأس المصادقة لحساب Anthropic. استخدم x-tfy-api-key في ANTHROPIC_CUSTOM_HEADERS بدلاً من ذلك:‍

{
  "env": {
    "ANTHROPIC_BASE_URL": "{GATEWAY_BASE_URL}",
    "ANTHROPIC_CUSTOM_HEADERS": "x-tfy-api-key: your-truefoundry-api-key\nX-TFY-LOGGING-CONFIG: {\"enabled\": true}",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "anthropic/claude-4-opus-20250514",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "anthropic/claude-4-sonnet-20250514",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "anthropic/claude-3-5-haiku-20241022"
  }
}

لماذا هذا النمط جيد لمستخدمي Max:

• تحتفظ باشتراكك في Anthropic Max لمصادقة جلسة Claude Code - يمر رأس Authorization إلى Anthropic كما هو
• TrueFoundry تُصادق بشكل منفصل عبر x-tfy-api-key - تتحكم البوابة في الطلب بينما تتولى Anthropic الفوترة عبر اشتراكك
• تحصل على حوكمة مركزية (الرؤية، الحصص، التحكم في الوصول المستند إلى الدور، السجلات، الضوابط الوقائية) دون تغيير سير عملك اليومي مع Claude Code

راجع وثائق TrueFoundry Claude Code للحصول على دليل التكامل الكامل، و تكامل Claude Code Max لنسخة اشتراك Max.

الخطوة 2: استخدم GPT-5 وGemini وأي نموذج آخر عبر Claude Code

هنا يتحول وكيل Claude Code من مجرد مريح إلى تحويلي. بمجرد أن يتم توجيه Claude Code عبر TrueFoundry، يمكنه الوصول إلى أي نموذج من أي مزود وليس Anthropic فقط. يمكنك إضافة حسابات المزودين في لوحة تحكم بوابة TrueFoundry (OpenAI، Google Vertex AI، AWS Bedrock، Azure OpenAI، xAI، أو نشرك الخاص محليًا)، وتصبح هذه النماذج متاحة عند نفس نقطة نهاية البوابة.

توجيه أسماء Claude Code المستعارة إلى نماذج غير Anthropic

لاستخدام GPT-5 لخانة "opus" في Claude Code (فئة النموذج الأكثر قدرة لديك)، ما عليك سوى تحديث الاسم المستعار للنموذج:

{
  "env": {
    "ANTHROPIC_BASE_URL": "{GATEWAY_BASE_URL}",
    "ANTHROPIC_AUTH_TOKEN": "your-truefoundry-api-key",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "openai-main/gpt-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "anthropic/claude-4-sonnet-20250514",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "google-vertex/gemini-2.5-flash",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

في هذا التكوين:

• /model opus → GPT-5 (لمهام الهندسة المعمارية والتخطيط المعقدة)
• /model sonnet → Claude Sonnet 4 (لمهام البرمجة القياسية)
• /model haiku → Gemini 2.5 Flash (للمهام السريعة والخفيفة مثل التحقق من البريد الإلكتروني، وعمليات البحث السريعة)

تجربة المطور متطابقة. لا يزال المطورون يستخدمون /model opus أو --model haiku. لا يحتاجون إلى معرفة أي مزود يقف وراء كل اسم مستعار، أو إدارة بيانات الاعتماد لـ OpenAI أو Google.

استخدام النماذج الافتراضية للتوجيه المتقدم

النماذج الافتراضية من TrueFoundry تتيح لك إنشاء معرف نموذج واحد يوجه الطلبات عبر مزودين متعددين باستخدام توجيه قائم على الوزن أو الأولوية أو زمن الاستجابة. وجّه اسمًا مستعارًا لنموذج Claude Code إلى نموذج افتراضي، وستتولى البوابة منطق التوجيه بشفافية.

مثال: التراجع القائم على الأولوية عبر المزودين

إذا وصل حسابك الأساسي في Anthropic إلى حدود المعدل، فسيتم التراجع تلقائيًا إلى Bedrock Claude، ثم إلى GPT-4 - دون أن يلاحظ أي مطور:

routing_config:
  type: priority-based-routing
  load_balance_targets:
    - target: anthropic-main/claude-sonnet-4-20250514
      priority: 0
      fallback_status_codes: ["429", "500", "502", "503"]
    - target: bedrock-main/claude-sonnet-4-20250514
      priority: 1
      fallback_status_codes: ["429", "500"]
    - target: openai-main/gpt-4o
      priority: 2

مثال: تقييم A/B القائم على الوزن

اختبر نموذجًا جديدًا على 10% من حركة مرور Claude Code قبل الالتزام به للفريق بأكمله:‍


routing_config:
  type: weight-based-routing
  load_balance_targets:
    - target: anthropic-main/claude-4-sonnet-20250514
      weight: 90
    - target: openai-main/gpt-5
      weight: 10

ثم وجّه الاسم المستعار "sonnet" الخاص بـ Claude Code إلى هذا النموذج الافتراضي. 10% من طلبات Claude Code sonnet تذهب إلى GPT-5 مع مقاييس التكلفة والجودة الكاملة في لوحة تحكم البوابة لمقارنة النتائج.

الخطوة 3: ضوابط المؤسسة التي تنطبق على كل طلب من Claude Code

بمجرد أن يتم توجيه Claude Code عبر TrueFoundry، يرث كل طلب حوكمة على مستوى المؤسسة ليس لأن المطورين يقومون بتكوينها، ولكن لأنه يتم فرضها على طبقة البوابة.

حدود الميزانية: أوقف تجاوز التكاليف قبل حدوثها

تحديد الميزانية الهرمي في TrueFoundry يتم تفعيلها قبل استهلاك الرمز، وليس بعد وصول الفاتورة الشهرية. تتراكم القواعد وتتحد:

يحصل كبار المهندسين على 50 دولارًا في اليوم. أما الباقون فيحصلون افتراضيًا على 10 دولارات في اليوم. ويبلغ إجمالي إنفاق Opus على مستوى المؤسسة بأكملها 1000 دولار شهريًا كحد أقصى — لذا حتى لو كان كل مطور ضمن حده الشخصي، لا يمكن تجاوز ميزانية النموذج على مستوى المؤسسة.

تحديد معدل الاستخدام: حماية البيئات المحلية وبيئات التحكم

تحديد معدل الاستخدام عند البوابة يتعامل مع ثلاثة سيناريوهات خاصة بـ Claude Code:

• مسارات CI: يجب أن تخضع عمليات تشغيل Claude Code في CI لتحديد معدل الاستخدام بشكل مستقل عن جلسات المطورين التفاعلية. فمجموعة الاختبار التي تستدعي Claude Code لمراجعة الكود يجب ألا تستهلك نفس الحصة المخصصة لجلسة برمجة نشطة للمطور.
• نماذج التطوير مقابل نماذج الإنتاج: تتيح لك حدود معدل الاستخدام المحددة بالنطاق حسب البيانات الوصفية توجيه environment: dev الطلبات إلى نموذج أقل تكلفة وتحديد معدل طلباتها — دون التأثير على الإنتاج.
• حماية وحدات معالجة الرسوميات المحلية: إذا كنت تشغل نماذج محلية كهدف أساسي لـ Claude Code، فحدد معدل استخدام نقطة النهاية المحلية وانتقل تلقائيًا إلى واجهة برمجة تطبيقات السحابة عندما تكون السعة مشبعة.

# Limit Claude Code in CI to 500 requests/day on GPT-4
- id: ci-pipeline-limit
  when:
    models: ['openai-main/gpt-4']
    metadata:
      environment: ci
  limit_to: 500
  unit: requests_per_day

إسناد التكلفة: اعرف بالضبط من ينفق ماذا

يُنسب كل طلب Claude Code تتم معالجته بواسطة TrueFoundry تلقائيًا إلى المستخدم المصادق عليه. تعرض لوحة تحكم التحليلات التكلفة مفصلة حسب المطور والفريق والنموذج والتاريخ - ويمكن تصفيتها بواسطة أي علامة بيانات وصفية تمررها عبر X-TFY-METADATA الرأس.

للفرق التي تستخدم تخصيص التكلفة على أساس المشروع، قم بوسم طلبات Claude Code بـ project_id أو feature البيانات الوصفية، ويتم ربط كل طلب تلقائيًا بمركز التكلفة الصحيح:‍


{
  "env": {
    "ANTHROPIC_CUSTOM_HEADERS": "X-TFY-METADATA: {\"team\": \"platform\", \"project_id\": \"infra-2026\"}"
  }
}

يتم تصدير جميع التتبعات عبر OpenTelemetry إلى Grafana أو Datadog أو Splunk، أو مكدس المراقبة الحالي لديك.

الخطوة 4: النشر عبر فريق الهندسة بأكمله

تكوين إعدادات مطور واحد settings.json أمر سهل. فرض تكوين وكيل (proxy) متسق على كل مطور في مؤسستك يتطلب استراتيجية نشر. تدعم TrueFoundry ثلاثة أساليب:

الخيار أ: الإعدادات المدارة المدفوعة بواسطة MDM (موصى به للمؤسسات)

ادفع ملف managed-settings.json إلى كل جهاز تابع للشركة عبر حل MDM الخاص بك (مثل Jamf، Kandji، Mosyle، Intune) واحمه من التعديل على مستوى نظام التشغيل. هذا هو الإعدادات المدارة من نقطة النهاية نهج.‍


{
  "model": "sonnet",
  "availableModels": ["sonnet", "haiku"],
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-gateway.internal.corp",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "anthropic/claude-4-opus-20250514",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "anthropic/claude-4-sonnet-20250514",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "anthropic/claude-3-5-haiku-20241022"
  }
}

مسارات على مستوى النظام:

• نظام macOS: /Library/Application Support/ClaudeCode/managed-settings.json
• نظام Linux: /etc/claude-code/managed-settings.json

هذا التكوين مقاوم للتلاعب، ويُطبق فورًا عند بدء التشغيل دون الاعتماد على الشبكة، ولا يتطلب أي إجراء من المطور. يتم توجيه كل جهاز يستقبل ملف تعريف MDM تلقائيًا عبر TrueFoundry.

الخيار ب: الإعدادات المدارة من الخادم عبر وحدة تحكم Anthropic الإدارية

قم بتكوين الإعدادات مركزيًا عبر وحدة تحكم Claude الإدارية (إعدادات المسؤول ← Claude Code ← الإعدادات المدارة). يتم تسليم الإعدادات من خوادم Anthropic عندما يقوم المطورون بالمصادقة باستخدام بيانات اعتماد مؤسستهم - لا حاجة لنشر الملفات.

لا يتطلب هذا النهج بنية تحتية لإدارة الأجهزة المحمولة (MDM) ويعمل على أجهزة BYOD. يتم تسليم الإعدادات وقت المصادقة ويصعب على المستخدمين تجاوزها.

الخيار ج: ملف settings.json على مستوى المشروع في التحكم بالإصدار

قم بتثبيت .claude/settings.json إلى الجذر لكل مستودع. أي مطور يقوم باستنساخ المستودع وتشغيل Claude Code في هذا الدليل يستخدم تلقائيًا إعدادات المشروع بما في ذلك عنوان URL لبوابة TrueFoundry وتكوين النموذج.‍


# Check into your monorepo or template repository
.claude/settings.json

هذا هو الخيار الأقل تعقيدًا للفرق التي لديها هياكل مستودعات موحدة. يرث المطورون الجدد تكوين الوكيل بمجرد استنساخهم.

الخطوة 5: إضافة VS Code و SDK لوكيل Claude

ملحق VS Code

يعمل ملحق Claude Code VS Code بسلاسة مع TrueFoundry بمجرد تهيئة واجهة سطر الأوامر (CLI). الملحق ليس مستقلاً - فهو يتطلب تثبيت وتهيئة واجهة سطر الأوامر Claude Code أولاً.‍


# macOS/Linux: Launch VS Code from terminal to inherit shell environment
code .

يستخدم الملحق تلقائيًا إعدادات واجهة سطر الأوامر الخاصة بك (عنوان URL الأساسي، مفاتيح API، أسماء النماذج المستعارة). لا حاجة لإعداد منفصل.

ملاحظة لمستخدمي macOS/Linux: لا ترث تطبيقات الواجهة الرسومية (GUI) متغيرات بيئة shell افتراضيًا. قم دائمًا بتشغيل VS Code من طرفية تم فيها تهيئة Claude Code لضمان أن الملحق يلتقط ANTHROPIC_BASE_URL.

مجموعة تطوير برامج وكيل Claude

تعمل مجموعة تطوير برامج وكيل Claude (الوريث لمجموعة تطوير برامج Claude Code) مع إعداداتك الحالية .claude/settings.json عبر TrueFoundry. حدد setting_sources=["project"] لتحميل تهيئة البوابة الخاصة بك برمجيًا:

from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
    prompt="Analyze my codebase for security vulnerabilities",
    options=ClaudeAgentOptions(
        setting_sources=["project"],  # Loads .claude/settings.json with TrueFoundry config
        max_turns=5,
        allowed_tools=["Read", "Grep", "Glob"]
    )
):
    if message.type == "result":
        print(message.result)

تعمل جميع تهيئات TrueFoundry - Anthropic Direct، AWS Bedrock، Google Vertex AI - بشكل متطابق مع مجموعة تطوير برامج الوكيل (Agent SDK).

وكيل Claude Code ذاتي الصنع مقابل بوابة TrueFoundry للذكاء الاصطناعي