मॉडल और प्रदाता कॉन्फ़िगरेशन (`models.yml`)

यह दस्तावेज़ वर्णन करता है कि कोडिंग-एजेंट वर्तमान में मॉडल को कैसे लोड करता है, ओवरराइड लागू करता है, क्रेडेंशियल्स को हल करता है, और रनटाइम पर मॉडल चुनता है।

मॉडल के व्यवहार को क्या नियंत्रित करता है

प्राथमिक कार्यान्वयन फ़ाइलें:

src/config/model-registry.ts — अंतर्निहित + कस्टम मॉडल, प्रदाता ओवरराइड, रनटाइम खोज, प्रमाणीकरण एकीकरण लोड करता है
src/config/model-resolver.ts — मॉडल पैटर्न को पार्स करता है और प्रारंभिक/smol/slow मॉडल का चयन करता है
src/config/settings-schema.ts — मॉडल से संबंधित सेटिंग्स (modelRoles, प्रदाता परिवहन प्राथमिकताएँ)
src/session/auth-storage.ts — API कुंजी + OAuth रिज़ॉल्यूशन क्रम
packages/ai/src/models.ts और packages/ai/src/types.ts — अंतर्निहित प्रदाता/मॉडल और Model/compat प्रकार

कॉन्फ़िग फ़ाइल का स्थान और विरासत व्यवहार (legacy behavior)

डिफ़ॉल्ट कॉन्फ़िग पथ:

~/.xcsh/agent/models.yml

विरासत व्यवहार अभी भी मौजूद है:

यदि models.yml गायब है और models.json उसी स्थान पर मौजूद है, तो इसे models.yml में माइग्रेट कर दिया जाता है।
स्पष्ट .json / .jsonc कॉन्फ़िग पथ अभी भी समर्थित हैं जब उन्हें प्रोग्रामेटिक रूप से ModelRegistry में पास किया जाता है।

`models.yml` का आकार (shape)

configVersion: 1  # optional — written by auto-config, used for migration detection
providers:
  <provider-id>:
    # provider-level config
equivalence:
  overrides:
    <provider-id>/<model-id>: <canonical-model-id>
  exclude:
    - <provider-id>/<model-id>

configVersion ऑटो-कॉन्फ़िग सिस्टम द्वारा लिखा गया एक वैकल्पिक पूर्णांक है। मौजूद होने पर, xcsh इसका उपयोग पुरानी कॉन्फ़िग का पता लगाने और उन्हें ऑटो-अपग्रेड करने के लिए करता है।

provider-id एक विहित (canonical) प्रदाता कुंजी है जिसका उपयोग चयन और प्रमाणीकरण लुकअप के लिए किया जाता है।

equivalence वैकल्पिक है और ठोस प्रदाता मॉडल के ऊपर विहित मॉडल समूहीकरण को कॉन्फ़िगर करता है:

overrides एक सटीक ठोस चयनकर्ता (provider/modelId) को एक आधिकारिक अपस्ट्रीम विहित आईडी में मैप करता है
exclude एक ठोस चयनकर्ता को विहित समूहीकरण से बाहर रखता है

प्रदाता-स्तर के फ़ील्ड

providers:
  my-provider:
    baseUrl: https://api.example.com/v1
    apiKey: MY_PROVIDER_API_KEY
    api: openai-completions
    headers:
      X-Team: platform
    authHeader: true
    auth: apiKey
    discovery:
      type: ollama
    modelOverrides:
      some-model-id:
        name: Renamed model
    models:
      - id: some-model-id
        name: Some Model
        api: openai-completions
        reasoning: false
        input: [text]
        cost:
          input: 0
          output: 0
          cacheRead: 0
          cacheWrite: 0
        contextWindow: 128000
        maxTokens: 16384
        headers:
          X-Model: value
        compat:
          supportsStore: true
          supportsDeveloperRole: true
          supportsReasoningEffort: true
          maxTokensField: max_completion_tokens
          openRouterRouting:
            only: [anthropic]
          vercelGatewayRouting:
            order: [anthropic, openai]
          extraBody:
            gateway: m1-01
            controller: mlx

अनुमत प्रदाता/मॉडल `api` मान

openai-completions
openai-responses
openai-codex-responses
azure-openai-responses
anthropic-messages
google-generative-ai
google-vertex

अनुमत प्रमाणीकरण/खोज मान

auth: apiKey (डिफ़ॉल्ट) या none
discovery.type: ollama

सत्यापन नियम (वर्तमान)

पूर्ण कस्टम प्रदाता (`models` खाली नहीं है)

आवश्यक:

baseUrl
apiKey जब तक कि auth: none न हो
प्रदाता स्तर या प्रत्येक मॉडल पर api

केवल ओवरराइड प्रदाता (`models` गायब या खाली है)

कम से कम एक को परिभाषित करना चाहिए:

baseUrl
modelOverrides
discovery

खोज (Discovery)

discovery के लिए प्रदाता-स्तर के api की आवश्यकता होती है।

मॉडल मान की जाँच

id आवश्यक है
यदि प्रदान किया गया है तो contextWindow और maxTokens सकारात्मक होना चाहिए

मर्ज और ओवरराइड का क्रम

ModelRegistry पाइपलाइन (रीफ्रेश पर):

@f5-sales-demo/pi-ai से अंतर्निहित प्रदाताओं/मॉडलों को लोड करें।
models.yml कस्टम कॉन्फ़िग को लोड करें।
अंतर्निहित मॉडलों पर प्रदाता ओवरराइड (baseUrl, headers) लागू करें।
modelOverrides लागू करें (प्रति प्रदाता + मॉडल आईडी)।
कस्टम models को मर्ज करें:
- समान provider + id मौजूदा को बदल देता है
- अन्यथा संलग्न (append) करें
रनटाइम-खोजे गए मॉडल (वर्तमान में Ollama और LM Studio) लागू करें, फिर मॉडल ओवरराइड को फिर से लागू करें।

विहित (Canonical) मॉडल तुल्यता और एकत्रीकरण (coalescing)

रजिस्ट्री प्रत्येक ठोस प्रदाता मॉडल को रखती है और फिर उनके ऊपर एक विहित परत बनाती है।

विहित आईडी केवल आधिकारिक अपस्ट्रीम आईडी हैं, उदाहरण के लिए:

claude-opus-4-6
claude-haiku-4-5
gpt-5.3-codex

`models.yml` तुल्यता (equivalence) कॉन्फ़िग

उदाहरण:

providers:
  zenmux:
    baseUrl: https://api.zenmux.example/v1
    apiKey: ZENMUX_API_KEY
    api: openai-codex-responses
    models:
      - id: codex
        name: Zenmux Codex
        reasoning: true
        input: [text]
        cost:
          input: 0
          output: 0
          cacheRead: 0
          cacheWrite: 0
        contextWindow: 200000
        maxTokens: 32768

equivalence:
  overrides:
    zenmux/codex: gpt-5.3-codex
    p-codex/codex: gpt-5.3-codex
  exclude:
    - demo/codex-preview

विहित समूहीकरण के लिए निर्माण क्रम:

equivalence.overrides से सटीक उपयोगकर्ता ओवरराइड
अंतर्निहित मॉडल मेटाडेटा से बंडल किए गए आधिकारिक-आईडी मिलान
गेटवे/प्रदाता वेरिएंट के लिए रूढ़िवादी अनुमानी सामान्यीकरण
ठोस मॉडल की अपनी आईडी पर फ़ॉलबैक

वर्तमान अनुमान (heuristics) जानबूझकर संकीर्ण हैं:

मौजूद होने पर एम्बेडेड अपस्ट्रीम उपसर्गों को हटाया जा सकता है, उदाहरण के लिए anthropic/... या openai/...
बिंदीदार और धराशायी संस्करण वेरिएंट केवल तभी सामान्य हो सकते हैं जब वे किसी मौजूदा आधिकारिक आईडी से मैप करते हों, उदाहरण के लिए 4.6 -> 4-6
अस्पष्ट परिवारों या संस्करणों को बिना किसी बंडल मिलान या स्पष्ट ओवरराइड के मर्ज नहीं किया जाता है

विहित रिज़ॉल्यूशन व्यवहार

जब एकाधिक ठोस वेरिएंट एक विहित आईडी साझा करते हैं, तो रिज़ॉल्यूशन उपयोग करता है:

उपलब्धता और प्रमाणीकरण
config.yml modelProviderOrder
यदि modelProviderOrder सेट नहीं है तो मौजूदा रजिस्ट्री/प्रदाता क्रम

अक्षम या अप्रमाणित प्रदाताओं को छोड़ दिया जाता है।

सत्र की स्थिति और टेप उस ठोस प्रदाता/मॉडल को रिकॉर्ड करना जारी रखते हैं जिसने वास्तव में टर्न निष्पादित किया था।

प्रदाता डिफ़ॉल्ट बनाम प्रति-मॉडल ओवरराइड:

प्रदाता headers आधारभूत (baseline) हैं।
मॉडल headers प्रदाता हेडर कुंजियों को ओवरराइड करते हैं।
modelOverrides मॉडल मेटाडेटा को ओवरराइड कर सकता है (name, reasoning, input, cost, contextWindow, maxTokens, headers, compat, contextPromotionTarget)।
नेस्टेड रूटिंग ब्लॉक के लिए compat को गहराई से मर्ज किया जाता है (openRouterRouting, vercelGatewayRouting, extraBody)।

रनटाइम खोज एकीकरण

अंतर्निहित (Implicit) `Ollama` खोज

यदि ollama को स्पष्ट रूप से कॉन्फ़िगर नहीं किया गया है, तो रजिस्ट्री एक अंतर्निहित खोजने योग्य प्रदाता जोड़ती है:

प्रदाता: ollama
api: openai-completions
बेस URL: OLLAMA_BASE_URL या http://127.0.0.1:11434
प्रमाणीकरण मोड: कुंजी रहित (auth: none व्यवहार)

रनटाइम खोज Ollama पर GET /api/tags कॉल करती है और स्थानीय डिफ़ॉल्ट के साथ मॉडल प्रविष्टियों को संश्लेषित करती है।

अंतर्निहित (Implicit) `llama.cpp` खोज

यदि llama.cpp को स्पष्ट रूप से कॉन्फ़िगर नहीं किया गया है, तो रजिस्ट्री एक अंतर्निहित खोजने योग्य प्रदाता जोड़ती है: नोट: यह openai-completions के बजाय नए anthropic-messages एपीआई का उपयोग कर रहा है।

प्रदाता: llama.cpp
api: openai-responses
बेस URL: LLAMA_CPP_BASE_URL या http://127.0.0.1:8080
प्रमाणीकरण मोड: कुंजी रहित (auth: none व्यवहार)

रनटाइम खोज llama.cpp पर GET models कॉल करती है और स्थानीय डिफ़ॉल्ट के साथ मॉडल प्रविष्टियों को संश्लेषित करती है।

अंतर्निहित (Implicit) `LM Studio` खोज

यदि lm-studio को स्पष्ट रूप से कॉन्फ़िगर नहीं किया गया है, तो रजिस्ट्री एक अंतर्निहित खोजने योग्य प्रदाता जोड़ती है:

प्रदाता: lm-studio
api: openai-completions
बेस URL: LM_STUDIO_BASE_URL या http://127.0.0.1:1234/v1
प्रमाणीकरण मोड: कुंजी रहित (auth: none व्यवहार)

रनटाइम खोज मॉडल प्राप्त करती है (GET /models) और स्थानीय डिफ़ॉल्ट के साथ मॉडल प्रविष्टियों को संश्लेषित करती है।

स्पष्ट प्रदाता खोज

आप खोज को स्वयं कॉन्फ़िगर कर सकते हैं:

providers:
  ollama:
    baseUrl: http://127.0.0.1:11434
    api: openai-completions
    auth: none
    discovery:
      type: ollama

  llama.cpp:
    baseUrl: http://127.0.0.1:8080
    api: openai-responses
    auth: none
    discovery:
      type: llama.cpp

एक्सटेंशन प्रदाता पंजीकरण

एक्सटेंशन रनटाइम पर प्रदाताओं को पंजीकृत कर सकते हैं (pi.registerProvider(...)), जिनमें शामिल हैं:

किसी प्रदाता के लिए मॉडल प्रतिस्थापन/संलग्न करना
नए एपीआई आईडी के लिए कस्टम स्ट्रीम हैंडलर पंजीकरण
कस्टम OAuth प्रदाता पंजीकरण

प्रमाणीकरण और API कुंजी रिज़ॉल्यूशन क्रम

किसी प्रदाता के लिए कुंजी का अनुरोध करते समय, प्रभावी क्रम है:

रनटाइम ओवरराइड (CLI --api-key)
agent.db में संग्रहीत API कुंजी क्रेडेंशियल
agent.db में संग्रहीत OAuth क्रेडेंशियल (रीफ्रेश के साथ)
पर्यावरण चर मानचित्रण (OPENAI_API_KEY, ANTHROPIC_API_KEY, आदि)
ModelRegistry फ़ॉलबैक रिज़ॉल्वर (models.yml से प्रदाता apiKey, env-name-or-literal शब्दार्थ)

models.yml में apiKey व्यवहार:

मान को पहले पर्यावरण चर नाम के रूप में माना जाता है।
यदि कोई पर्यावरण चर मौजूद नहीं है, तो शाब्दिक स्ट्रिंग का उपयोग टोकन के रूप में किया जाता है।

यदि authHeader: true है और प्रदाता apiKey सेट है, तो मॉडल प्राप्त करते हैं:

Authorization: Bearer <resolved-key> हेडर इंजेक्ट किया गया।

कुंजी रहित प्रदाता:

auth: none के रूप में चिह्नित प्रदाताओं को क्रेडेंशियल्स के बिना उपलब्ध माना जाता है।
getApiKey* उनके लिए kNoAuth लौटाता है।

मॉडल उपलब्धता बनाम सभी मॉडल

getAll() लोड की गई मॉडल रजिस्ट्री (अंतर्निहित + मर्ज किए गए कस्टम + खोजे गए) को लौटाता है।
getAvailable() उन मॉडलों को फ़िल्टर करता है जो कुंजी रहित हैं या जिनमें हल करने योग्य प्रमाणीकरण है।

इसलिए एक मॉडल रजिस्ट्री में मौजूद हो सकता है लेकिन जब तक प्रमाणीकरण उपलब्ध न हो तब तक वह चयन योग्य नहीं हो सकता है।

रनटाइम मॉडल रिज़ॉल्यूशन

CLI और पैटर्न पार्सिंग

model-resolver.ts समर्थन करता है:

सटीक provider/modelId
सटीक विहित मॉडल आईडी
सटीक मॉडल आईडी (प्रदाता अनुमानित)
फज़ी/सबस्ट्रिंग मिलान
--models में ग्लोब स्कोप पैटर्न (उदा. openai/*, *sonnet*)
वैकल्पिक :thinkingLevel प्रत्यय (off|minimal|low|medium|high|xhigh)

--provider विरासत (legacy) है; --model को प्राथमिकता दी जाती है।

सटीक चयनकर्ताओं के लिए रिज़ॉल्यूशन प्राथमिकता:

सटीक provider/modelId एकत्रीकरण को बायपास करता है
सटीक विहित आईडी विहित अनुक्रमणिका के माध्यम से हल होती है
सटीक नंगी (bare) ठोस आईडी अभी भी काम करती है
फज़ी और ग्लोब मिलान सटीक पथों के बाद चलते हैं

प्रारंभिक मॉडल चयन प्राथमिकता

findInitialModel(...) इस क्रम का उपयोग करता है:

स्पष्ट CLI प्रदाता+मॉडल
पहला स्कोप्ड मॉडल (यदि फिर से शुरू नहीं हो रहा है)
सहेजा गया डिफ़ॉल्ट प्रदाता/मॉडल
उपलब्ध मॉडलों में ज्ञात प्रदाता डिफ़ॉल्ट (उदा. OpenAI/Anthropic/आदि)
पहला उपलब्ध मॉडल

भूमिका उपनाम और सेटिंग्स

समर्थित मॉडल भूमिकाएँ:

default, smol, slow, plan, commit

pi/smol जैसे भूमिका उपनाम settings.modelRoles के माध्यम से विस्तारित होते हैं। प्रत्येक भूमिका मान एक थिंकिंग चयनकर्ता जैसे :minimal, :low, :medium, या :high को भी संलग्न कर सकता है।

यदि कोई भूमिका किसी अन्य भूमिका को इंगित करती है, तो लक्ष्य मॉडल अभी भी सामान्य रूप से विरासत में मिलता है और संदर्भित भूमिका पर कोई भी स्पष्ट प्रत्यय उस भूमिका-विशिष्ट उपयोग के लिए जीतता है।

संबंधित सेटिंग्स:

modelRoles (रिकॉर्ड)
enabledModels (स्कोप्ड पैटर्न सूची)
modelProviderOrder (वैश्विक विहित-प्रदाता प्राथमिकता)
providers.kimiApiFormat (openai या anthropic अनुरोध प्रारूप)
providers.openaiWebsockets (OpenAI Codex ट्रांसपोर्ट के लिए auto|off|on वेबसॉकेट प्राथमिकता)

modelRoles इनमें से किसी एक को संग्रहीत कर सकता है:

एक ठोस प्रदाता संस्करण को पिन करने के लिए provider/modelId
प्रदाता एकत्रीकरण की अनुमति देने के लिए एक विहित आईडी जैसे gpt-5.3-codex

enabledModels और CLI --models के लिए:

सटीक विहित आईडी उस विहित समूह के सभी ठोस वेरिएंट में विस्तारित होती हैं
स्पष्ट provider/modelId प्रविष्टियां सटीक रहती हैं
ग्लोब्स और फ़ज़ी मैच अभी भी ठोस मॉडल पर काम करते हैं

`/model` और `--list-models`

दोनों सतहें प्रदाता-उपसर्ग वाले मॉडलों को दृश्यमान और चयन योग्य रखती हैं।

वे अब विहित/एकत्रित मॉडलों को भी उजागर करते हैं:

/model में प्रदाता टैब के साथ एक विहित दृश्य शामिल है
--list-models एक विहित अनुभाग और ठोस प्रदाता पंक्तियाँ प्रिंट करता है

एक विहित प्रविष्टि का चयन विहित चयनकर्ता को संग्रहीत करता है। एक प्रदाता पंक्ति का चयन स्पष्ट provider/modelId को संग्रहीत करता है।

संदर्भ पदोन्नति (मॉडल-स्तरीय फ़ॉलबैक श्रृंखलाएं)

संदर्भ पदोन्नति (Context promotion) छोटे-संदर्भ वेरिएंट (उदाहरण के लिए *-spark) के लिए एक अतिप्रवाह पुनर्प्राप्ति तंत्र है जो एपीआई द्वारा संदर्भ लंबाई त्रुटि के साथ किसी अनुरोध को अस्वीकार करने पर स्वचालित रूप से बड़े-संदर्भ वाले भाई-बहन (sibling) को बढ़ावा देता है।

ट्रिगर और क्रम

जब कोई टर्न संदर्भ अतिप्रवाह त्रुटि (उदा. context_length_exceeded) के साथ विफल हो जाता है, तो AgentSession संघनन (compaction) पर वापस आने से पहले पदोन्नति का प्रयास करता है:

यदि contextPromotion.enabled सत्य है, तो पदोन्नति लक्ष्य को हल करें (नीचे देखें)।
यदि कोई लक्ष्य मिल जाता है, तो उस पर स्विच करें और अनुरोध का पुनः प्रयास करें — किसी संघनन की आवश्यकता नहीं है।
यदि कोई लक्ष्य उपलब्ध नहीं है, तो वर्तमान मॉडल पर ऑटो-संघनन (auto-compaction) पर जाएं।

लक्ष्य का चयन

चयन मॉडल-संचालित है, भूमिका-संचालित नहीं:

currentModel.contextPromotionTarget (if configured)`
उसी प्रदाता + एपीआई पर सबसे छोटा बड़े-संदर्भ वाला मॉडल

जब तक क्रेडेंशियल हल नहीं हो जाते (ModelRegistry.getApiKey(...)), उम्मीदवारों को अनदेखा कर दिया जाता है।

`OpenAI Codex` वेबसॉकेट हैंडऑफ़

यदि openai-codex-responses से/में स्विच कर रहे हैं, तो मॉडल स्विच से पहले सत्र प्रदाता स्थिति कुंजी openai-codex-responses बंद कर दी जाती है। यह वेबसॉकेट परिवहन स्थिति को छोड़ देता है ताकि अगला टर्न प्रचारित मॉडल पर साफ तौर पर शुरू हो सके।

दृढ़ता (Persistence) व्यवहार

पदोन्नति अस्थायी स्विचिंग (setModelTemporary) का उपयोग करती है:

सत्र इतिहास में अस्थायी model_change के रूप में दर्ज किया गया
सहेजे गए भूमिका मानचित्रण को फिर से नहीं लिखता है

स्पष्ट फ़ॉलबैक श्रृंखलाओं को कॉन्फ़िगर करना

contextPromotionTarget के माध्यम से मॉडल मेटाडेटा में सीधे फ़ॉलबैक कॉन्फ़िगर करें।

contextPromotionTarget इनमें से किसी एक को स्वीकार करता है:

provider/model-id (स्पष्ट)
model-id (वर्तमान प्रदाता के भीतर हल किया गया)

समान प्रदाता पर स्पार्क (Spark) -> गैर-स्पार्क (non-Spark) के लिए उदाहरण (models.yml):

providers:
  openai-codex:
    modelOverrides:
      gpt-5.3-codex-spark:
        contextPromotionTarget: openai-codex/gpt-5.3-codex

जब समान-प्रदाता बेस मॉडल मौजूद होता है तो अंतर्निहित मॉडल जनरेटर इसे स्वचालित रूप से *-spark मॉडल के लिए निर्दिष्ट करता है।

संगतता और रूटिंग फ़ील्ड

models.yml इस compat उपसमुच्चय (subset) का समर्थन करता है:

supportsStore
supportsDeveloperRole
supportsReasoningEffort
maxTokensField (max_completion_tokens or max_tokens)
openRouterRouting.only / openRouterRouting.order
vercelGatewayRouting.only / vercelGatewayRouting.order

इनका उपभोग OpenAI-completions परिवहन तर्क द्वारा किया जाता है और URL-आधारित ऑटो-डिटेक्शन के साथ जोड़ा जाता है।

व्यावहारिक उदाहरण

स्थानीय `OpenAI`-संगत एंडपॉइंट (कोई प्रमाणीकरण नहीं)

providers:
  local-openai:
    baseUrl: http://127.0.0.1:8000/v1
    auth: none
    api: openai-completions
    models:
      - id: Qwen/Qwen2.5-Coder-32B-Instruct
        name: Qwen 2.5 Coder 32B (local)

पर्यावरण-आधारित कुंजी के साथ होस्ट किया गया प्रॉक्सी

providers:
  anthropic-proxy:
    baseUrl: https://proxy.example.com/anthropic
    apiKey: ANTHROPIC_PROXY_API_KEY
    api: anthropic-messages
    authHeader: true
    models:
      - id: claude-sonnet-4-20250514
        name: Claude Sonnet 4 (Proxy)
        reasoning: true
        input: [text, image]

अंतर्निहित प्रदाता मार्ग + मॉडल मेटाडेटा को ओवरराइड करें

providers:
  openrouter:
    baseUrl: https://my-proxy.example.com/v1
    headers:
      X-Team: platform
    modelOverrides:
      anthropic/claude-sonnet-4:
        name: Sonnet 4 (Corp)
        compat:
          openRouterRouting:
            only: [anthropic]

LiteLLM प्रॉक्सी ऑटो-कॉन्फ़िगरेशन

जब LITELLM_BASE_URL और LITELLM_API_KEY पर्यावरण चर दोनों सेट होते हैं, तो xcsh स्वचालित रूप से LiteLLM प्रॉक्सी के लिए models.yml कॉन्फ़िगरेशन का प्रबंधन करता है।

प्रथम-रन ऑटो-जेनरेशन

यदि models.yml मौजूद नहीं है और LiteLLM env चर का पता चलता है, तो xcsh इसे स्वचालित रूप से उत्पन्न करता है:

# Auto-generated by xcsh for LiteLLM proxy
# API key resolved from LITELLM_API_KEY env var at runtime
configVersion: 1
providers:
  anthropic:
    baseUrl: "https://your-litellm-proxy.example.com/anthropic"
    apiKey: LITELLM_API_KEY

एक डिफ़ॉल्ट config.yml भी समझदार छवि प्रदाता सेटिंग्स के साथ उत्पन्न होता है।

स्टार्टअप सेल्फ-हीलिंग

प्रत्येक स्टार्टअप पर, मॉडल रजिस्ट्री में startupHealthCheck() निम्नलिखित जाँच चलाता है:

स्थिति	कार्रवाई
`models.yml` गायब	env vars से ऑटो-जेनरेट करें
`models.yml` भ्रष्ट या अनपार्स योग्य	`.bak` में बैकअप लें, पुनर्जीवित करें
`baseUrl`, `LITELLM_BASE_URL` से मेल नहीं खाता है	`.bak` में बैकअप लें, नए URL के साथ पुनर्जीवित करें
`configVersion` गायब या पुराना	`.bak` में बैकअप लें, वर्तमान संस्करण के साथ पुनर्जीवित करें
कॉन्फ़िग स्वस्थ है	कोई कार्रवाई नहीं

सभी मरम्मत अधिलेखित (overwriting) करने से पहले .bak बैकअप बनाते हैं। सभी संचालन इडेम्पोटेंट (idempotent) हैं।

CLI कमांड

xcsh setup litellm              # Generate or fix LiteLLM config
xcsh setup litellm --check      # Validate without writing
xcsh setup litellm --check --json  # Machine-readable validation output

आवश्यक पर्यावरण चर

चर	उद्देश्य
`LITELLM_BASE_URL`	LiteLLM प्रॉक्सी URL (उदा. `https://your-proxy.example.com`)। `http://` या `https://` से शुरू होना चाहिए।
`LITELLM_API_KEY`	प्रॉक्सी के लिए API कुंजी। जेनरेट किए गए कॉन्फ़िग में नाम से संदर्भित, रनटाइम पर हल किया गया।

यदि कोई भी चर सेट नहीं है, तो ऑटो-कॉन्फ़िगरेशन चुपचाप छोड़ दिया जाता है।

कॉन्फ़िग वर्ज़निंग

उत्पन्न कॉन्फ़िग में एक configVersion फ़ील्ड शामिल होता है। जब भविष्य के रिलीज़ में उत्पन्न प्रारूप बदलता है, तो xcsh पुरानी कॉन्फ़िग का पता लगाता है और स्वचालित रूप से उन्हें अपग्रेड करता है (बैकअप के साथ)।

विरासत (Legacy) उपभोक्ता चेतावनी

अधिकांश मॉडल कॉन्फ़िगरेशन अब ModelRegistry के माध्यम से models.yml से प्रवाहित होता है।

एक उल्लेखनीय विरासत पथ बना हुआ है: वेब-खोज Anthropic प्रमाणीकरण रिज़ॉल्यूशन अभी भी सीधे src/web/search/auth.ts में ~/.xcsh/agent/models.json पढ़ता है।

यदि आप उस विशिष्ट पथ पर भरोसा करते हैं, तो उस मॉड्यूल के माइग्रेट होने तक JSON संगतता को ध्यान में रखें।

विफलता मोड (Failure mode)

यदि models.yml स्कीमा या सत्यापन जांच में विफल रहता है:

यदि LITELLM_BASE_URL और LITELLM_API_KEY सेट हैं, तो स्टार्टअप हेल्थ चेक ऑटो-रिपेयर का प्रयास करता है (भ्रष्ट फ़ाइल का बैकअप लें, env vars से पुनर्जीवित करें)। यदि मरम्मत सफल होती है, तो रजिस्ट्री निश्चित कॉन्फ़िग को फिर से लोड करती है।
यदि ऑटो-रिपेयर संभव नहीं है (env vars अनसेट, विफलता लिखना), तो रजिस्ट्री अंतर्निहित मॉडलों के साथ काम करती रहती है।
त्रुटि को ModelRegistry.getError() के माध्यम से उजागर किया जाता है और UI/अधिसूचनाओं में सामने लाया जाता है।