> ## Documentation Index
> Fetch the complete documentation index at: https://docs.one.fim.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Variables d'environnement
> Référence de configuration complète pour FIM One.
Toute la configuration se fait via `.env`. Copiez `example.env` et remplissez vos valeurs :
```bash theme={null}
cp example.env .env
```
## Niveaux de Configuration
Chaque intégration a un niveau de configuration indiquant son importance :
| Niveau | Signification | Comportement si non configuré |
| -------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------- |
| **Requis** | Dépendance système essentielle | Le système génère une erreur — le chat et les fonctions principales ne fonctionnent pas |
| **Recommandé** | Activateur de fonctionnalité significative | Dégradation progressive — la fonctionnalité est visiblement indisponible mais le système fonctionne |
| **Optionnel** | Capacité d'amélioration | Dégradation transparente — le système fonctionne correctement, la capacité est simplement absente |
> **Remarque** : Les modèles configurés par l'administrateur (Admin → page Modèles) peuvent remplacer les variables d'environnement LLM. La vérification de santé considère les deux sources.
***
## Frontend (Développement local uniquement)
Le frontend a un fichier env séparé **uniquement pour le développement local** : `frontend/.env.local`.
> **Ce fichier n'est PAS utilisé dans Docker.** À l'intérieur du conteneur Docker, Next.js proxifie `/api/*` vers le backend Python en interne (le port 8000 est interne au conteneur), donc aucun fichier env frontend n'est nécessaire.
Pour le développement local, les valeurs par défaut fonctionnent directement — vous n'avez **pas** besoin de créer `frontend/.env.local` sauf si votre backend s'exécute sur un port non-standard.
Si vous devez remplacer les valeurs, créez `frontend/.env.local` manuellement :
```bash theme={null}
echo 'NEXT_PUBLIC_API_URL=http://localhost:9000' > frontend/.env.local
```
| Variable | Par défaut | Description |
| --------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NEXT_PUBLIC_API_URL` | `http://localhost:8000` *(auto)* | URL du backend que le **navigateur** utilise pour les appels API directs (redirections OAuth, streaming). Détectée automatiquement à partir de `window.location` si non définie — remplacez-la uniquement si votre backend s'exécute sur un port non-standard localement. |
> **Note au moment de la compilation** : les variables `NEXT_PUBLIC_*` sont intégrées au bundle JS au moment de `pnpm build`. Les modifier à l'exécution (par ex. via le fichier `.env` racine) n'a aucun effet — c'est pourquoi elles se trouvent dans `frontend/.env.local` pour le développement local uniquement.
## LLM (Requis)
| Variable | Requis | Par défaut | Description |
| --------------------------------- | ------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `LLM_API_KEY` | **Oui** | — | Clé API du fournisseur LLM |
| `LLM_BASE_URL` | Non | `https://api.openai.com/v1` | URL de base de toute API compatible OpenAI |
| `LLM_MODEL` | Non | `gpt-4o` | Modèle principal — utilisé pour la planification, l'analyse et l'agent ReAct |
| `FAST_LLM_MODEL` | Non | *(revient à `LLM_MODEL`)* | Modèle rapide — utilisé pour l'exécution des étapes DAG (moins cher, plus rapide) |
| `LLM_TEMPERATURE` | Non | `0.7` | Température d'échantillonnage par défaut |
| `LLM_CONTEXT_SIZE` | Non | `128000` | Taille de la fenêtre de contexte pour le LLM principal |
| `LLM_MAX_OUTPUT_TOKENS` | Non | `64000` | Nombre maximum de tokens de sortie par appel pour le LLM principal |
| `FAST_LLM_API_KEY` | Non | *(revient à `LLM_API_KEY`)* | Clé API du fournisseur du modèle rapide. À utiliser lorsque le modèle rapide est hébergé par un fournisseur différent du modèle principal |
| `FAST_LLM_BASE_URL` | Non | *(revient à `LLM_BASE_URL`)* | URL de base du fournisseur du modèle rapide |
| `FAST_LLM_TEMPERATURE` | Non | *(revient à `LLM_TEMPERATURE`)* | Température d'échantillonnage pour le modèle rapide |
| `FAST_LLM_CONTEXT_SIZE` | Non | *(revient à `LLM_CONTEXT_SIZE`)* | Taille de la fenêtre de contexte pour le LLM rapide |
| `FAST_LLM_MAX_OUTPUT_TOKENS` | Non | *(revient à `LLM_MAX_OUTPUT_TOKENS`)* | Nombre maximum de tokens de sortie par appel pour le LLM rapide |
| `LLM_REASONING_EFFORT` | Non | *(désactivé)* | Niveau de réflexion étendue pour les modèles supportés (série OpenAI o, Gemini 2.5+, Claude). Valeurs : `low`, `medium`, `high`. LiteLLM traduit cela automatiquement au format natif de chaque fournisseur. La chaîne de pensée du modèle est affichée dans l'étape « thinking » de l'interface utilisateur. |
| `LLM_REASONING_BUDGET_TOKENS` | Non | *(auto à partir de l'effort)* | Budget de tokens explicite pour la réflexion Anthropic (minimum 1024). Pour OpenAI/Gemini, le niveau d'effort est utilisé directement. Effectif uniquement lorsque `LLM_REASONING_EFFORT` est défini. |
| `FIM_GPT5_RESPONSES_MODE` | Non | `native` | Quel protocole les modèles GPT-5.x utilisent. `native` communique directement avec l'API OpenAI Responses et rejoue le raisonnement chiffré de chaque tour, de sorte que le modèle conserve sa chaîne de pensée entre les appels d'outils. `bridge` utilise la traduction chat-completions de LiteLLM, qui fonctionne mais redérive le raisonnement à chaque tour. `off` force les complétions de chat simples, où le raisonnement est désactivé chaque fois que des outils sont présents. Ne définissez que si vous déboguez ; les points de terminaison sans route `/v1/responses` se rabattent sur leur propre solution. S'applique à GPT-5.x uniquement. |
| `LLM_JSON_MODE_ENABLED` | Non | `true` | Basculeur global pour `response_format=json_object`. Définissez à `false` si votre fournisseur rejette l'injection de préfixe assistant de LiteLLM (par exemple, relais AWS Bedrock → `ValidationException` à la 2e itération d'agent et au-delà). Lorsque désactivé, les appels structurés ignorent le mode JSON et reviennent à l'extraction regex en texte brut — aucune perte de qualité. S'applique à tous les modèles (configurés par ENV et Admin). |
| `LLM_TOOL_CHOICE_ENABLED` | Non | `true` | Basculeur global pour `tool_choice` forcé dans l'extraction de sortie structurée (Niveau 1 — Appel de fonction natif). Définissez à `false` si votre modèle retourne des erreurs avec la sélection d'outil forcée (par exemple, les modèles en mode réflexion qui rejettent `tool_choice='specified'`). Lorsque désactivé, les appels structurés ignorent le FC natif et commencent à partir du mode JSON. Remplacement par modèle disponible dans Paramètres → Modèles → Avancé. |
| `REASONING_LLM_MODEL` | Non | *(revient à `LLM_MODEL`)* | Nom du modèle pour le niveau de réflexion. Utilisé pour les tâches nécessitant une analyse approfondie (par exemple, planification DAG, analyse de plan) |
| `REASONING_LLM_API_KEY` | Non | *(revient à `LLM_API_KEY`)* | Clé API du fournisseur du modèle de réflexion |
| `REASONING_LLM_BASE_URL` | Non | *(revient à `LLM_BASE_URL`)* | URL de base du fournisseur du modèle de réflexion |
| `REASONING_LLM_TEMPERATURE` | Non | *(revient à `LLM_TEMPERATURE`)* | Température d'échantillonnage pour le modèle de réflexion |
| `REASONING_LLM_CONTEXT_SIZE` | Non | *(revient à `LLM_CONTEXT_SIZE`)* | Taille de la fenêtre de contexte pour le modèle de réflexion |
| `REASONING_LLM_MAX_OUTPUT_TOKENS` | Non | *(revient à `LLM_MAX_OUTPUT_TOKENS`)* | Nombre maximum de tokens de sortie par appel pour le modèle de réflexion |
| `REASONING_LLM_EFFORT` | Non | *(revient à `LLM_REASONING_EFFORT`)* | Niveau d'effort de réflexion pour le niveau de modèle de réflexion. Valeurs : `low`, `medium`, `high` |
| `REASONING_LLM_BUDGET` | Non | *(revient à `LLM_REASONING_BUDGET_TOKENS`)* | Budget de tokens pour la réflexion (principalement Anthropic). Remplace le budget calculé automatiquement pour le niveau de réflexion |
| `LLM_SUPPORTS_VISION` | Non | `true` *(optimiste)* | Contrôle si l'OCR de document en mode ENV (via MarkItDown + `markitdown-ocr`) est tenté. S'applique uniquement lorsqu'**aucun groupe de modèles actif n'est configuré dans Admin → Modèles** (mode ENV pur). Lorsque la valeur par défaut `true` est en vigueur, `convert_to_markdown` et l'ingestion RAG supposent que `LLM_MODEL` supporte la vision et l'appellent pour l'OCR d'image — c'est le comportement correct pour tous les choix courants (`gpt-4o`, `claude-3-5-sonnet`, `gemini-1.5-pro/flash`). Définissez à `false` lorsque votre `LLM_MODEL` configuré par ENV ne supporte **pas** la vision (par exemple, `deepseek-v3`, `qwen-chat`, `llama-3.1`, `gpt-3.5-turbo`, `o1-mini`) pour ignorer l'appel de vision défaillant et passer directement à l'extraction texte uniquement. Lorsqu'un groupe de modèles actif existe dans le panneau Admin → Modèles, cet indicateur est ignoré et les indicateurs `supports_vision` du groupe prennent le relais — le choix curé par l'administrateur est toujours la source de vérité en mode DB. |
> **Ordre de résolution** : Préférence utilisateur → Modèles Admin (DB) → Secours ENV. Si un modèle admin avec le rôle « General » est configuré dans Admin → Modèles, ces variables ENV servent de secours uniquement. Le contrôle de santé considère les deux sources.
### Résolution OCR MarkItDown
L'outil intégré `convert_to_markdown` et le pipeline d'ingestion RAG utilisent tous deux [MarkItDown](https://github.com/microsoft/markitdown) de Microsoft + le plugin officiel [`markitdown-ocr`](https://github.com/microsoft/markitdown/tree/main/packages/markitdown-ocr) pour extraire du texte à partir de documents — y compris l'OCR sur les images intégrées et les pages PDF numérisées lorsqu'un LLM capable de vision est disponible.
**Ordre de résolution du LLM Vision** (première correspondance gagne) :
| # | Source | Justification de la priorité |
| - | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 1 | **LLM principal** de l'agent si `supports_vision=True` | Cohérence : même clé API, même bucket de facturation, même pool de limite de débit que la conversation. |
| 2 | **ModelGroup → Fast Model** actif si `supports_vision=True` | Les modèles rapides (`gpt-4o-mini`, `claude-haiku`, `gemini-1.5-flash`) sont l'outil OCR idéal — bon marché, faible latence, généralement multimodaux. |
| 3 | **ModelGroup → General Model** actif si `supports_vision=True` | Fallback de qualité lorsque le modèle principal n'est pas dans le groupe. |
| 4 | **LLM principal ENV** (`LLM_MODEL`) | Fallback optimiste pour le mode ENV pur. Utilisé uniquement lorsqu'aucun ModelGroup actif n'existe. Contrôlé par `LLM_SUPPORTS_VISION`. |
**Les modèles de reasoning ne sont jamais préférés pour l'OCR.** Les niveaux de reasoning (`o1`, `o3-mini`, `DeepSeek-R1`) manquent historiquement de support vision et ne sont pas l'outil approprié pour l'OCR de toute façon — l'OCR est une tâche de perception, pas de délibération. Si un espace de travail n'a qu'un modèle de reasoning avec `supports_vision=True`, il sera toujours sélectionné via le chemin du LLM principal, mais le résolveur ne le classe pas activement au-dessus des modèles rapides/généraux.
**Fallback sans régression** : lorsqu'aucun modèle capable de vision n'est trouvé à aucun niveau, l'OCR est silencieusement désactivé et MarkItDown s'exécute en mode texte uniquement. L'OCR des images intégrées dans Word/PowerPoint/Excel devient indisponible (comme avant le lancement de cette fonctionnalité), mais toute autre extraction de texte (titres, tableaux, texte de paragraphe) continue de fonctionner sans modification. **Il n'y a jamais de cas où l'ajout de cette fonctionnalité a rendu l'extraction pire que le comportement précédent.**
**Les fournisseurs non-OpenAI (Anthropic, Google Gemini, etc.)** sont pris en charge de manière transparente : le LLM résolu est enveloppé dans un `LiteLLMOpenAIShim` qui achemine les appels `chat.completions.create(...)` via `litellm.completion()`, qui gère la traduction du format de message spécifique au fournisseur (par exemple, le bloc d'image `source.type="base64"` d'Anthropic). Un seul shim couvre chaque fournisseur que LiteLLM supporte — l'ajout d'un nouveau fournisseur ne coûte aucune modification de code dans FIM One.
### Réflexion étendue (Raisonnement)
Lorsque `LLM_REASONING_EFFORT` est défini, FIM One active la capacité de réflexion étendue du modèle afin que la chaîne de pensée interne soit affichée dans l'étape « thinking » de l'interface utilisateur. FIM One utilise [LiteLLM](https://github.com/BerriAI/litellm) pour traduire automatiquement le paramètre d'effort de raisonnement dans le format natif de chaque fournisseur.
#### Fournisseurs pris en charge
Les fournisseurs qui acceptent la réflexion, la façon dont chacun est activé, les valeurs `effort` qu'il accepte, et l'endroit où le texte de raisonnement se termine sont enregistrés une seule fois, avec des ancres de code, dans [le tableau C de la matrice des capacités des fournisseurs](/architecture/llm-provider-guide#provider-capability-matrix). Ce tableau est la liste faisant autorité ; cette page documente uniquement les variables.
FIM One résout le fournisseur à partir de `LLM_BASE_URL` (plus un champ de fournisseur explicite lorsqu'un est configuré) et mappe la demande au format API correct. Les URL inconnues sont traitées comme compatibles avec OpenAI.
#### Avertissements importants
**Les proxies tiers / points de terminaison personnalisés ne sont pas garantis.**
Si votre `LLM_BASE_URL` pointe vers un proxy API tiers (par exemple, OpenRouter, one-api, passerelle personnalisée), LiteLLM tentera d'acheminer correctement en fonction de l'URL. Cependant, si votre proxy s'attend à un format non standard, le raisonnement peut ne pas fonctionner comme prévu. Consultez la documentation du proxy pour connaître le format de paramètre attendu.
#### Contraintes de température avec le raisonnement
Certains fournisseurs restreignent `temperature` quand le raisonnement est actif. **Tous ces éléments sont appliqués automatiquement ; laissez `LLM_TEMPERATURE` à la valeur qui convient à votre charge de travail.**
* **Anthropic** : nécessite `temperature=1` quand la réflexion étendue est activée. Le générateur de requêtes épingle la valeur sur les routes Anthropic, donc votre température configurée est remplacée pour ces appels plutôt que rejetée.
* **Anthropic, modèles stricts** (Opus 4.7 et 4.8, Fable 5, Mythos 5) : rejettent `temperature`, `top_p` et `top_k` complètement, avec ou sans raisonnement. FIM One supprime `temperature` de la requête pour ces modèles.
* **OpenAI GPT-5.x** : ne supporte que `temperature=1`. Le filtrage `drop_params` de LiteLLM supprime les valeurs non supportées.
Définir `LLM_TEMPERATURE=1` manuellement pour satisfaire Anthropic est inutile et vous coûte la capacité d'exécuter une température inférieure sur chaque appel sans raisonnement.
#### Comment fonctionne `LLM_REASONING_BUDGET_TOKENS`
Cette variable n'est **pertinente que sur le chemin de réflexion Anthropic hérité** (Claude 4.5 et versions antérieures, routées en tant que `anthropic/`). Elle y remplace le budget calculé automatiquement et est envoyée en tant que `budget_tokens` à l'intérieur du paramètre `thinking`. Les modèles à réflexion adaptative (Opus 4.6 et versions plus récentes, Sonnet 4.6, Fable 5, Mythos 5) prennent un niveau d'effort au lieu d'un budget et ignorent entièrement cette variable. Lorsqu'elle n'est pas définie, le budget est dérivé de `LLM_MAX_OUTPUT_TOKENS` x ratio d'effort :
| `LLM_REASONING_EFFORT` | Ratio de budget | Exemple (max\_tokens = 64000) |
| ---------------------- | --------------- | ----------------------------- |
| `low` | 20% | 12 800 tokens |
| `medium` | 50% | 32 000 tokens |
| `high` | 80% | 51 200 tokens |
Le budget minimum est de 1 024 tokens (minimum absolu d'Anthropic).
Pour OpenAI et Gemini, le fournisseur gère l'allocation de tokens en interne en fonction du niveau `reasoning_effort` — `LLM_REASONING_BUDGET_TOKENS` n'a aucun effet.
## Exécution de l'agent
### Agent ReAct
| Variable | Requis | Défaut | Description |
| ----------------------------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `REACT_MAX_ITERATIONS` | Non | `20` | Nombre maximal d'itérations d'appels d'outils par requête ReAct. Plus élevé = plus approfondi mais plus lent et plus coûteux |
| `REACT_MAX_TURN_TOKENS` | Non | `0` | Disjoncteur d'urgence : nombre maximal cumulé de tokens (prompt + completion sur toutes les itérations) par tour ReAct unique. La valeur par défaut `0` = illimité. **Ceci n'est PAS pour le contrôle quotidien des tokens** — utilisez `token_quota` par utilisateur pour cela. C'est une soupape de sécurité de dernier recours pour les scénarios extrêmes comme un agent bloqué dans une boucle infinie d'appels d'outils. Atteindre cette limite abandonne la tâche en cours d'exécution, gaspillant tous les tokens consommés jusqu'à présent et renvoyant un résultat incomplet. Gardez à `0` sauf si vous avez un problème spécifique d'agent incontrôlable à contenir |
| `REACT_TOOL_SELECTION_THRESHOLD` | Non | `12` | Lorsque le nombre total d'outils enregistrés dépasse ce seuil, un appel LLM léger sélectionne le sous-ensemble le plus pertinent avant chaque requête |
| `REACT_TOOL_SELECTION_MAX` | Non | `6` | Nombre maximal d'outils à conserver après sélection intelligente (effectif uniquement lorsque le nombre d'outils dépasse `REACT_TOOL_SELECTION_THRESHOLD`) |
| `REACT_SELF_REFLECTION_INTERVAL` | Non | `6` | Injecter une invite d'auto-réflexion tous les N appels d'outils pour aider l'agent à se réorienter et éviter les boucles |
| `REACT_TOOL_OBS_TRUNCATION` | Non | `8000` | Nombre maximal de caractères par observation d'outil lors de la synthèse de la réponse finale. Les valeurs plus élevées préservent plus de données structurées (JSON, tableaux) au prix de plus de tokens |
| `REACT_TOOL_RESULT_BUDGET` | Non | `40000` | Budget de tokens agrégé pour tous les résultats d'outils dans une session unique. Lorsque le total des tokens de résultats d'outils dépasse ce plafond, les nouveaux résultats sont tronqués avec un avis. Prévient l'encombrement du contexte causé par les grandes réponses API (par exemple, 5 appels de connecteur renvoyant 8K chacun). Définissez à `0` pour désactiver le plafond |
| `REACT_COMPLETION_CHECK_SKIP_CHARS` | Non | `800` | Ignorer l'appel LLM de vérification post-réponse lorsque la réponse finale de l'agent dépasse ce nombre de caractères. Les réponses longues et détaillées n'ont pas besoin d'un aller-retour de vérification « ai-je oublié quelque chose ? ». Définissez plus bas pour ignorer plus agressivement ; définissez à une valeur très élevée pour toujours exécuter la vérification |
| `REACT_CYCLE_DETECTION_THRESHOLD` | Non | `2` | Lorsque le même outil est appelé avec des arguments identiques ce nombre de fois d'affilée, un avertissement déterministe est injecté indiquant à l'agent d'essayer une approche différente. Contrairement à l'auto-réflexion (qui s'appuie sur le LLM remarquant la boucle), c'est une vérification basée sur le hachage qui ne peut pas être contournée. S'applique également aux étapes DAG |
| `REACT_COMPLETION_CHECK_MIN_TOOLS` | Non | `3` | Nombre minimal d'appels d'outils avant le déclenchement de la liste de vérification d'achèvement. Les tâches simples (1-2 appels d'outils) ignorent la vérification pour éviter une latence inutile. Définissez à `1` pour une vérification toujours active. S'applique également aux étapes DAG |
| `REACT_TURN_PROFILE_ENABLED` | Non | `true` | Émettre des journaux de synchronisation au niveau des phases par tour (`memory_load`, `compact`, `tool_schema_build`, `llm_first_token`, `llm_total`, `tool_exec`). Une ligne de journal structuré par tour. Définissez à `false` pour désactiver complètement le profilage (zéro surcharge) |
| `REACT_PLAN_TOOL_ENABLED` | Non | `true` | Enregistrer l'outil `update_plan` todo afin que l'agent écrive et maintienne une liste de contrôle de plan pendant les tâches multi-étapes. Automatiquement ignoré pour les agents d'étapes DAG et les agents sans outils |
| `REACT_PLAN_REMINDER_INTERVAL` | Non | `3` | Tours d'outils sans appel `update_plan` avant qu'un rappel de plan obsolète (intégrant la liste de contrôle complète) soit réinjecté dans la conversation, afin que le plan survive à la compaction du contexte |
| `REACT_PLAN_REPEAT_THRESHOLD` | Non | `4` | Tours consécutifs appelant le même outil (avec des arguments différents) avant qu'un rappel indique à l'agent de changer d'approche au lieu de répéter des appels infructueux. Les appels exactement dupliqués sont traités séparément par la détection de cycle |
| `REACT_PLAN_NUDGE_AFTER` | Non | `5` | Tours d'outils sans plan enregistré avant une suggestion ponctuelle d'écrire le plan. S'applique uniquement lorsque l'outil de plan est activé |
| `REACT_FINISH_SIGNAL` | Non | `true` | Réponse FINAL-first sur le chemin du chat : l'agent termine sa boucle d'outils sur un signal `finish` puis écrit la réponse comme un tour véritablement diffusé en tokens. Définissez à `false` pour restaurer les réponses de boucle en ligne avec relecture en mémoire tampon |
| `REACT_MAX_CONTINUATIONS` | Non | `3` | Nombre maximal de tours de continuation lorsque la réponse du modèle est coupée par la limite de tokens de sortie du fournisseur (`finish_reason=length`). Les segments tronqués sont assemblés en une réponse transparente, à la fois dans la boucle d'agent et dans la synthèse diffusée |
| `REACT_BACKGROUND_TOOLS_ENABLED` | Non | `true` | Offrir une option `run_in_background` sur les outils lents (exécution Python/shell/node en bac à sable). L'agent obtient immédiatement un identifiant de tâche et continue de travailler ; le résultat arrive sous la forme d'un message `` lorsque l'outil se termine |
| `REACT_BG_WAIT_TIMEOUT` | Non | `300` | Nombre maximal de secondes à attendre pour les outils d'arrière-plan toujours en cours d'exécution lorsque l'agent souhaite finaliser sa réponse. Les tâches non terminées dans la fenêtre sont annulées avec une notification de délai d'attente explicite |
| `DAG_CHECKPOINT_EVIDENCE_CHARS` | Non | `4000` | Plafond de preuves par étape dans le fichier de point de contrôle de reprise d'accident DAG (`data/dag_checkpoints/`). Les résumés d'étapes sont stockés en intégralité |
| `DAG_CHECKPOINT_MAX_AGE_HOURS` | Non | `24` | Les points de contrôle DAG plus anciens que cela sont ignorés au chargement, de sorte que les restes d'accident obsolètes ne reprennent jamais dans une exécution nouvelle |
| `LLM_RATE_LIMIT_PER_USER` | Non | `true` | Utiliser des compartiments de limite de débit à clé par utilisateur au lieu d'un compartiment global unique au processus. Empêche un utilisateur bruyant de priver tous les autres sur le même worker. Le débit sous-jacent est codé en dur à 60 requêtes/min et 100K tokens/min par compartiment — ce paramètre contrôle uniquement si le compartiment est partagé (global) ou partitionné (par utilisateur). Définissez à `false` pour revenir au compartiment global hérité (non recommandé) |
### Planificateur DAG
| Variable | Requis | Par défaut | Description |
| -------------------------------- | ------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MAX_CONCURRENCY` | Non | `5` | Nombre maximal d'étapes parallèles dans l'exécuteur DAG |
| `DAG_STEP_MAX_ITERATIONS` | Non | `15` | Nombre maximal d'itérations d'appels d'outils au sein de chaque étape DAG |
| `DAG_STEP_TIMEOUT` | Non | `600` | Délai d'expiration de l'exécution d'une étape en secondes. Les étapes dépassant ce délai sont marquées comme échouées et leurs dépendances sont ignorées en cascade |
| `DAG_MAX_REPLAN_ROUNDS` | Non | `3` | Nombre maximal de tentatives de re-planification autonome lorsque l'objectif n'est pas atteint. Les interruptions utilisateur (injection) sont illimitées et ne sont pas comptabilisées dans ce budget |
| `DAG_REPLAN_STOP_CONFIDENCE` | Non | `0.8` | S'applique uniquement lorsque l'agent juge l'objectif **inatteignable** (demande impossible, capacité manquante, ressource inaccessible) : arrêter les tentatives à partir de cette certitude ou au-delà. Un livrable manquant ou inachevé est toujours re-planifié indépendamment de la confiance — seul `DAG_MAX_REPLAN_ROUNDS` limite ces tentatives |
| `DAG_VERIFY_TRUNCATION` | Non | `2000` | Nombre maximal de caractères de la sortie d'étape envoyés au vérificateur d'étape LLM pour l'évaluation de la qualité |
| `DAG_ANALYZER_TRUNCATION` | Non | `10000` | Nombre maximal de caractères par résultat d'étape lors du formatage pour l'analyseur post-exécution |
| `DAG_STEP_EVIDENCE_CHARS` | Non | `16000` | Nombre maximal de caractères de sortie d'outil brute (récupérations web, résultats de recherche, lectures de fichiers) conservés par étape comme « preuve source » faisant autorité. Ceci est fourni à l'analyseur et à la synthèse finale aux côtés du résumé de l'étape, de sorte que les affirmations factuelles de la réponse (totaux, énumérations, sévérités) puissent être vérifiées par rapport à la source au lieu de faire confiance à un résumé qui peut avoir silencieusement supprimé ou mal étiqueté des éléments. Définir à `0` pour désactiver la capture de preuve |
| `DAG_REPLAN_RECENT_TRUNCATION` | Non | `500` | Nombre maximal de caractères par résultat d'étape du tour le plus récent lors de la construction du contexte de re-planification |
| `DAG_REPLAN_OLDER_TRUNCATION` | Non | `200` | Nombre maximal de caractères par résultat d'étape des tours antérieurs lors de la construction du contexte de re-planification. Les tours antérieurs sont tronqués plus agressivement pour économiser le contexte |
| `DAG_TOOL_CACHE` | Non | `true` | Mettre en cache les appels d'outils identiques au sein d'une seule exécution DAG. Seuls les outils explicitement marqués comme `cacheable` (outils en lecture seule comme la recherche, la récupération de connaissances) sont mis en cache. Définir à `false` pour désactiver entièrement la mise en cache |
| `DAG_STEP_VERIFICATION` | Non | `false` | Vérification générique de la qualité basée sur LLM après chaque étape DAG. En cas d'échec, l'étape est relancée une fois avec des commentaires. **Désactivé par défaut** — ajoute de la latence à chaque étape et est rarement nécessaire ; la plupart des sorties d'étape sont acceptables sans re-vérification. À utiliser uniquement lorsque vous observez des résultats d'étape de faible qualité fréquents |
| `DAG_CITATION_VERIFICATION` | Non | `true` | Vérification de l'exactitude des citations pour les étapes de domaines spécialisés. **Condition préalable** : la requête doit d'abord être classée comme domaine spécialisé par le classificateur de domaine LLM (voir `ESCALATION_DOMAINS`). Lorsque le domaine est détecté ET que cet indicateur est `true`, chaque étape terminée est analysée pour les citations juridiques/médicales/financières et vérifiée pour l'exactitude — détectant les numéros d'articles hallucés, les références de cas fabriquées et les citations réglementaires incorrectes. Si la classification de domaine retourne `null` (requête générale), la vérification des citations ne s'exécute pas indépendamment de ce paramètre |
| `DAG_CITATION_VERIFY_TRUNCATION` | Non | `6000` | Nombre maximal de caractères du résultat d'étape envoyés à l'invite de vérification des citations |
### Classification des domaines
Contrôle la couche de détection de domaine indépendante basée sur LLM qui s'exécute **avant** l'exécution de ReAct et DAG. Lorsqu'une requête est classée comme appartenant à un domaine spécialisé, le système active les fonctionnalités sensibles au domaine : escalade du modèle vers le modèle de raisonnement, instructions SOP spécifiques au domaine et vérification des citations (DAG uniquement).
| Variable | Requis | Par défaut | Description |
| -------------------- | ------ | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ESCALATION_DOMAINS` | Non | `legal,medical,financial,tax,compliance,patent` | Liste séparée par des virgules des domaines spécialisés. Un LLM rapide classe chaque requête par rapport à cette liste. En cas de correspondance, le système : (1) bascule vers le modèle de raisonnement pour une plus grande précision, (2) injecte des instructions SOP spécifiques au domaine (par exemple, vérifier les citations via la recherche avant d'écrire), (3) active la vérification des citations pour les étapes DAG. Ajoutez des domaines personnalisés selon les besoins (par exemple, `legal,education,construction`) |
### Context Guard
Contrôle la gestion automatique de la fenêtre de contexte qui empêche les conversations de dépasser la limite du modèle.
| Variable | Requis | Par défaut | Description |
| ------------------------------ | ------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CONTEXT_GUARD_DEFAULT_BUDGET` | Non | `32000` | Budget de jetons par défaut pour la gestion de la fenêtre de contexte. Lorsque la conversation dépasse cette limite, les messages plus anciens sont compactés |
| `CONTEXT_GUARD_MAX_MSG_CHARS` | Non | `50000` | Limite de caractères stricte pour tout message unique. Les messages dépassant cette limite sont tronqués comme filet de sécurité |
| `CONTEXT_GUARD_KEEP_RECENT` | Non | `4` | Nombre de messages les plus récents à conserver lors de la compaction de l'historique de conversation |
### Garde-fous de contenu
Noms de garde-fous séparés par des virgules qui inspectent le *contenu* des entrées ou sorties. Indépendants de la porte de permission d'outil (`core/hooks/*`) et de la couche de sécurité (`core/security/*`). Voir [Garde-fous de contenu](/configuration/guardrails) pour l'image complète.
| Variable | Requis | Par défaut | Description |
| -------------------------------- | ------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `FIM_GUARDRAILS_INPUT` | Non | `jailbreak` | Garde-fous d'entrée actifs. Le détecteur regex `jailbreak` par défaut interrompt le tour avant que des jetons LLM ne soient dépensés lorsque des phrases de dépassement d'invite connues sont détectées. Définir sur vide pour désactiver. Les noms inconnus sont enregistrés et ignorés |
| `FIM_GUARDRAILS_OUTPUT` | Non | (vide) | Garde-fous de sortie actifs. Actuellement fournis : `max_length` (limite le nombre de caractères de la réponse). Exécutés après que l'agent produit sa réponse finale |
| `FIM_GUARDRAIL_MAX_OUTPUT_CHARS` | Non | `50000` | Limite de caractères utilisée par le garde-fou de sortie `max_length`. Effectif uniquement lorsque `max_length` est listé dans `FIM_GUARDRAILS_OUTPUT` |
### Espace de travail de l'agent
| Variable | Requis | Par défaut | Description |
| ----------------------------- | ------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `WORKSPACE_OFFLOAD_THRESHOLD` | Non | `8000` | Lorsqu'une sortie d'outil dépasse ce nombre de caractères, elle est enregistrée dans un fichier d'espace de travail et un aperçu tronqué est injecté dans le contexte de conversation |
| `WORKSPACE_PREVIEW_CHARS` | Non | `2000` | Nombre de caractères d'aperçu à inclure dans les références d'espace de travail tronquées |
| `WORKSPACE_CLEANUP_MAX_HOURS` | Non | `72` | Les fichiers d'espace de travail plus anciens que ce nombre d'heures sont éligibles au nettoyage automatique |
### Système
| Variable | Requise | Par défaut | Description |
| --------------------------- | ------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ~~`SYSTEM_PROMPT_RESERVE`~~ | — | — | **Supprimée.** Précédemment, elle soustrayait une réserve fixe de 4K du budget de contexte pour les invites système. Cela causait un double comptage car ContextGuard inclut déjà l'invite système lors de l'estimation des jetons de la liste de messages. La formule du budget est maintenant `(context_size - max_output_tokens) × 0.92` (la marge absorbe l'erreur d'estimation des jetons), et la taille réelle de l'invite système est comptabilisée dynamiquement |
## Outils Web (Optionnel)
| Variable | Requis | Par défaut | Description |
| --------------------- | ------ | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `JINA_API_KEY` | Non | — | Clé API Jina. Alimente le backend de recherche **par défaut** et agit comme solution de secours partagée pour **fetch, embedding et reranker** quand aucune clé spécifique au service n'est définie. Obtenez la vôtre sur [jina.ai](https://jina.ai/) |
| `TAVILY_API_KEY` | Non | — | Clé API Tavily Search. Requise quand `WEB_SEARCH_PROVIDER=tavily` ; également utilisée par la détection automatique si le fournisseur n'est pas défini |
| `BRAVE_API_KEY` | Non | — | Clé API Brave Search. Requise quand `WEB_SEARCH_PROVIDER=brave` ; également utilisée par la détection automatique si le fournisseur n'est pas défini |
| `EXA_API_KEY` | Non | — | Clé API Exa Search. Requise quand `WEB_SEARCH_PROVIDER=exa` ; également utilisée par la détection automatique si le fournisseur n'est pas défini. Voir [Exa](/integrations/exa). Obtenez la vôtre sur [exa.ai](https://exa.ai/) |
| `WEB_SEARCH_PROVIDER` | Non | `jina` | Sélecteur de fournisseur de recherche : `jina` (par défaut) / `tavily` / `brave` / `exa`. Préférez définir ceci explicitement quand vous utilisez un fournisseur non-par défaut |
| `WEB_FETCH_PROVIDER` | Non | `jina` (si clé définie, sinon `httpx`) | Fournisseur de fetch : `jina` (utilise l'API Jina Reader) / `httpx` (requête HTTP directe, aucune clé API nécessaire) |
> **Conseil de démarrage rapide** : Définir simplement `JINA_API_KEY` active la pile de recherche web par défaut, plus fetch, embedding et reranking — une clé, quatre services. Basculez la recherche vers Tavily, Brave ou Exa avec `WEB_SEARCH_PROVIDER` et la clé API correspondante.
## RAG et Base de Connaissances (Recommandé)
### Intégration
L'intégration convertit le texte en vecteurs pour la recherche de base de connaissances. FIM One utilise le point de terminaison standard compatible OpenAI **`/v1/embeddings`**, il fonctionne donc avec n'importe quel fournisseur qui expose cette interface — pas seulement Jina.
| Variable | Requis | Par défaut | Description |
| --------------------- | ------ | ---------------------------- | --------------------------------------------- |
| `EMBEDDING_API_KEY` | Non | *(revient à `JINA_API_KEY`)* | Clé API pour le fournisseur d'intégration |
| `EMBEDDING_BASE_URL` | Non | `https://api.jina.ai/v1` | URL de base pour le fournisseur d'intégration |
| `EMBEDDING_MODEL` | Non | `jina-embeddings-v3` | Identifiant du modèle |
| `EMBEDDING_DIMENSION` | Non | `1024` | Dimension du vecteur |
**Exemples de fournisseurs** — définissez simplement les trois variables pour basculer :
| Fournisseur | `EMBEDDING_BASE_URL` | `EMBEDDING_MODEL` | `EMBEDDING_DIMENSION` |
| ----------------------- | ----------------------------- | ------------------------ | --------------------- |
| **Jina** *(par défaut)* | `https://api.jina.ai/v1` | `jina-embeddings-v3` | `1024` |
| **OpenAI** | `https://api.openai.com/v1` | `text-embedding-3-small` | `1536` |
| **Voyage** | `https://api.voyageai.com/v1` | `voyage-3` | `1024` |
| **Ollama** *(local)* | `http://localhost:11434/v1` | `nomic-embed-text` | `768` |
**Modifier le modèle d'intégration ou la dimension invalide tous les vecteurs de base de connaissances existants.** Les anciens vecteurs ont été calculés dans un espace d'intégration différent — la précision de la récupération se dégradера silencieusement. Vous devez **reconstruire tous les index de base de connaissances** après le basculement.
### Récupération
| Variable | Requis | Par défaut | Description |
| ---------------- | ------ | ----------- | ----------------------------------------------------------------------------------------------- |
| `RETRIEVAL_MODE` | Non | `grounding` | `grounding` (pipeline complet avec citations et scoring de confiance) ou `simple` (RAG basique) |
### Réorganiseur
Le réorganiseur reclasse les documents récupérés pour améliorer la pertinence. Trois fournisseurs sont pris en charge — sélectionnez via `RERANKER_PROVIDER` ou laissez le système détecter automatiquement à partir des clés API disponibles.
| Variable | Requis | Par défaut | Description |
| ----------------------- | ------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| `RERANKER_PROVIDER` | Non | *(auto-détection)* | `jina` / `cohere` / `openai`. Si non défini : utilise Cohere si `COHERE_API_KEY` est défini, sinon Jina |
| `RERANKER_MODEL` | Non | `jina-reranker-v2-base-multilingual` | Identifiant du modèle (s'applique aux fournisseurs Jina et OpenAI) |
| `COHERE_API_KEY` | Non | — | Clé API Cohere (sélectionne automatiquement le réorganiseur Cohere quand défini et `RERANKER_PROVIDER` n'est pas défini) |
| `COHERE_RERANKER_MODEL` | Non | `rerank-multilingual-v3.0` | Modèle de réorganiseur spécifique à Cohere |
> **Jina** utilise `JINA_API_KEY` (à partir des outils Web ci-dessus). **OpenAI** réutilise `LLM_API_KEY` / `LLM_BASE_URL` — aucune clé supplémentaire nécessaire. **Cohere** nécessite sa propre `COHERE_API_KEY`.
> Le réorganiseur est **optionnel** — la recherche de base de connaissances fonctionne sans lui en utilisant le score de fusion. L'intégration est **recommandée** pour les fonctionnalités de base de connaissances.
### Magasin vectoriel
| Variable | Requis | Par défaut | Description |
| ------------------ | ------ | --------------------- | --------------------------------------------------------------------------------------------------- |
| `VECTOR_STORE_DIR` | Non | `./data/vector_store` | Répertoire pour les données du magasin vectoriel LanceDB (basé sur fichier, zéro services externes) |
***
## Exécution de Code
| Variable | Requis | Défaut | Description |
| ---------------------- | ------ | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CODE_EXEC_BACKEND` | Non | `local` | `local` (exécution directe sur l'hôte) ou `docker` (conteneurs isolés) |
| `DOCKER_PYTHON_IMAGE` | Non | `python:3.11-slim` | Image Docker pour l'exécution Python |
| `DOCKER_NODE_IMAGE` | Non | `node:20-slim` | Image Docker pour l'exécution Node.js |
| `DOCKER_SHELL_IMAGE` | Non | `python:3.11-slim` | Image Docker pour l'exécution shell |
| `DOCKER_MEMORY` | Non | *(défaut Docker)* | Limite de RAM par conteneur (ex. `256m`, `512m`, `1g`) |
| `DOCKER_CPUS` | Non | *(défaut Docker)* | Quota CPU par conteneur (ex. `0.5`, `1.0`) |
| `SANDBOX_TIMEOUT` | Non | `120` | Délai d'exécution par défaut en secondes |
| `DOCKER_HOST_DATA_DIR` | Non | *(non défini)* | Chemin absolu côté hôte du montage de volume `./data`. Requis pour les déploiements DooD (Docker-outside-of-Docker) ; `docker-compose.yml` le définit automatiquement via `${PWD}/data`. |
> **Sécurité** : Le mode `local` exécute le code généré par l'IA directement sur l'hôte. Pour les déploiements accessibles sur Internet ou multi-utilisateurs, définissez toujours `CODE_EXEC_BACKEND=docker`.
## Artefacts d'outil
Limites de taille pour les fichiers produits par l'exécution d'outils (exécution de code, rendu de modèle, génération d'image).
| Variable | Requis | Par défaut | Description |
| --------------------- | ------ | ------------------ | ---------------------------------------------------------- |
| `MAX_ARTIFACT_SIZE` | Non | `10485760` (10 MB) | Taille maximale d'un fichier artefact unique en octets |
| `MAX_ARTIFACTS_TOTAL` | Non | `52428800` (50 MB) | Taille totale maximale des artefacts par session en octets |
***
## Traitement des documents (Optionnel)
Contrôle le traitement des fichiers PDF/DOCX téléchargés pour la consommation par LLM. Les modèles compatibles avec la vision (GPT-4o, Claude 3/4, Gemini) peuvent recevoir les pages PDF sous forme d'images rendues pour une meilleure fidélité.
| Variable | Requis | Par défaut | Description |
| --------------------------- | ------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `DOCUMENT_PROCESSING_MODE` | Non | `auto` | `auto` (vision si le modèle la supporte), `vision` (toujours rendre les pages), `text` (toujours extraire le texte uniquement) |
| `DOCUMENT_VISION_DPI` | Non | `150` | DPI pour le rendu des pages PDF. Plus élevé = meilleure qualité, plus de tokens |
| `DOCUMENT_VISION_MAX_PAGES` | Non | `20` | Nombre maximum de pages à rendre sous forme d'images par PDF |
> **Remarque** : Le support de la vision par modèle est configuré via le bouton `supports_vision` dans Admin → Models. Lorsqu'il n'est pas explicitement défini, le système détecte automatiquement la capacité de vision à partir du nom du modèle.
## Génération d'images (Optionnel)
| Variable | Requis | Par défaut | Description |
| -------------------- | ------ | -------------------------------- | -------------------------------------------------------------------------------------------------- |
| `IMAGE_GEN_PROVIDER` | Non | `google` | `google` (API native Gemini) ou `openai` (API compatible OpenAI `/v1/images/generations`) |
| `IMAGE_GEN_API_KEY` | Non | — | Clé Google AI Studio (`google`) ou clé proxy/OpenAI (`openai`) |
| `IMAGE_GEN_MODEL` | Non | `gemini-3.1-flash-image-preview` | Modèle de génération d'images (par ex. `dall-e-3`, `gemini-nano-banana-2`) |
| `IMAGE_GEN_BASE_URL` | Non | *(par fournisseur)* | Google : `https://generativelanguage.googleapis.com/v1beta` ; OpenAI : `https://api.openai.com/v1` |
***
## Email (SMTP) (Recommandé)
Enregistre automatiquement l'outil intégré `email_send` lorsque `SMTP_HOST`, `SMTP_USER` et `SMTP_PASS` sont tous définis.
| Variable | Requis | Par défaut | Description |
| ------------------------ | ------ | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SMTP_HOST` | Cond. | — | Nom d'hôte du serveur SMTP |
| `SMTP_PORT` | Non | `465` | Port SMTP |
| `SMTP_SSL` | Non | `ssl` | Mode TLS : `ssl` (port 465) / `tls` (STARTTLS, port 587) / `none` ou `""` (plain, identifiants envoyés en clair). Toute autre valeur est rejetée plutôt que de revenir silencieusement au mode plain. |
| `SMTP_USER` | Cond. | — | Nom d'utilisateur de connexion SMTP |
| `SMTP_PASS` | Cond. | — | Mot de passe de connexion SMTP |
| `SMTP_FROM` | Non | *(utilise `SMTP_USER`)* | Adresse de l'expéditeur affichée dans l'en-tête From |
| `SMTP_FROM_NAME` | Non | — | Nom d'affichage affiché dans l'en-tête From |
| `SMTP_REPLY_TO` | Non | — | Adresse Reply-To ; les réponses vont ici au lieu de `SMTP_FROM` |
| `SMTP_ALLOWED_DOMAINS` | Non | — | Liste d'autorisation de domaines séparés par des virgules (ex. `example.com,corp.io`) ; bloque les destinataires en dehors des domaines listés |
| `SMTP_ALLOWED_ADDRESSES` | Non | — | Liste d'autorisation d'adresses exactes séparées par des virgules ; combinée avec `SMTP_ALLOWED_DOMAINS` ; laissez les deux non définis pour autoriser n'importe quel destinataire (non recommandé pour les boîtes aux lettres partagées) |
***
## Connecteurs
| Variable | Requis | Par défaut | Description |
| ------------------------------ | ------ | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CONNECTOR_RESPONSE_MAX_CHARS` | Non | `50000` | Nombre maximum de caractères pour les réponses de connecteur JSON non-tableau / texte brut |
| `CONNECTOR_RESPONSE_MAX_ITEMS` | Non | `10` | Nombre maximum d'éléments de tableau à conserver lorsque la réponse du connecteur est un tableau JSON |
| `CREDENTIAL_ENCRYPTION_KEY` | Non | *(non défini)* | Clé de chiffrement Fernet pour les blobs d'identifiants de connecteur. Lorsqu'elle est définie, les jetons d'authentification stockés dans `connector_credentials` sont chiffrés au repos. Si elle n'est pas définie, les identifiants sont stockés en JSON en texte brut (rétrocompatible). La modification de cette clé invalide tous les identifiants chiffrés existants. |
| `CONNECTOR_TOOL_MODE` | Non | `progressive` | Comment les outils de connecteur sont exposés aux agents. `progressive` : un seul `ConnectorMetaTool` avec les sous-commandes `discover`/`execute` (\~30 jetons/connecteur). `classic` : un outil par action (hérité, \~250 jetons/action). |
| `DATABASE_TOOL_MODE` | Non | `progressive` | Comment les outils de connecteur de base de données sont exposés aux agents. `progressive` : un seul `DatabaseMetaTool` avec les sous-commandes `list_tables`/`discover`/`query`. `legacy` : un outil par action par connecteur de base de données (3 outils chacun). |
| `MCP_TOOL_MODE` | Non | `progressive` | Comment les outils du serveur MCP sont exposés aux agents. `progressive` : un seul `MCPServerMetaTool` avec les sous-commandes `discover`/`call`. `legacy` : un outil par action du serveur MCP (outils individuels originaux). |
***
## Plateforme
| Variable | Requis | Défaut | Description |
| -------------------------------- | ------ | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DATABASE_URL` | Non | `sqlite+aiosqlite:///./data/fim_one.db` | Chaîne de connexion à la base de données. **SQLite** (zéro configuration) : `sqlite+aiosqlite:///./data/fim_one.db`. **PostgreSQL** (production) : `postgresql+asyncpg://user:pass@localhost:5432/fim_one`. Docker Compose configure automatiquement PostgreSQL. |
| `JWT_SECRET_KEY` | Non | `CHANGE_ME` | Clé secrète pour la signature des jetons JWT. La valeur d'espace réservé `CHANGE_ME` (ou tout défaut hérité) déclenche la génération automatique d'une clé aléatoire sécurisée de 256 bits au premier démarrage, qui est écrite dans `.env`. Définissez explicitement en production pour maintenir la validité des jetons lors des redémarrages et des répliques. |
| `FIM_BCRYPT_COST` | Non | `12` | Facteur de travail bcrypt pour le hachage des mots de passe, limité à 4-31. Le défaut 12 coûte environ 200 ms par hachage sur les CPU modernes ; réduisez-le sur du matériel faible, augmentez-le pour les déploiements renforcés en sécurité. |
| `CORS_ORIGINS` | Non | — | Liste séparée par des virgules des origines CORS supplémentaires autorisées au-delà des entrées localhost par défaut. Requis lorsque le frontend s'exécute sur un domaine non-localhost (par ex. `https://app.example.com`). |
| `UPLOADS_DIR` | Non | `./uploads` | Répertoire pour les fichiers téléchargés |
| `EXPORT_FONT_DIR` | Non | *(détection automatique)* | Répertoire contenant `NotoSansSC-Regular.ttf` / `NotoSansSC-Bold.ttf` pour l'export PDF. Récupérez avec `python scripts/fetch_export_fonts.py` ; les images Docker l'incluent déjà. Sans une police TrueType CJK intégrable, l'export PDF revient à une police CID non intégrée avec un espacement dégradé et pas de gras. |
| `MAX_UPLOAD_SIZE_MB` | Non | `50` | Taille maximale de téléchargement de fichier en mégaoctets (application côté serveur) |
| `NEXT_PUBLIC_MAX_UPLOAD_SIZE_MB` | Non | `50` | Taille maximale de téléchargement de fichier affichée dans l'interface utilisateur du frontend. **Variable au moment de la compilation** — doit correspondre à `MAX_UPLOAD_SIZE_MB`. |
| `MCP_SERVERS` | Non | — | Tableau JSON des configurations de serveur MCP (nécessite `uv sync --extra mcp`) |
| `ALLOW_STDIO_MCP` | Non | `false` | Autoriser les serveurs MCP stdio. Définissez `true` uniquement pour les déploiements locaux de confiance |
| `ALLOWED_STDIO_COMMANDS` | Non | `npx,uvx,node,python,python3,deno,bun` | Liste séparée par des virgules des commandes de base autorisées pour les serveurs MCP stdio. Effectif uniquement lorsque `ALLOW_STDIO_MCP=true` |
| `LOG_LEVEL` | Non | `INFO` | Niveau de journalisation : `DEBUG` / `INFO` / `WARNING` / `ERROR` / `CRITICAL` |
| `REDIS_URL` | Non | — | URL de connexion Redis pour le relais d'interruption entre workers. **Requis lorsque `WORKERS>1`** — sans cela, les demandes d'interruption/injection en cours de flux peuvent atteindre un worker différent et échouer silencieusement. Configuré automatiquement par Docker Compose. |
| `WORKERS` | Non | `1` | Processus workers Uvicorn. `1` est sûr et ne nécessite aucun service externe. Pour la production multi-worker, utilisez PostgreSQL (SQLite est single-writer). SQLite fonctionne pour le développement local sous charge légère. L'authentification, OAuth et les opérations de fichiers sont entièrement multi-worker sûrs (basés sur JWT). Docker Compose configure automatiquement PostgreSQL et Redis. |
**Liste de contrôle multi-worker** (`WORKERS>1`) :
* **Arrêt (interruption du streaming)** — fonctionne toujours, aucune configuration supplémentaire nécessaire (le signal voyage sur la même connexion TCP).
* **Injection (suivi en cours de flux)** — **nécessite `REDIS_URL`**. Sans Redis, la demande d'injection peut atterrir sur un worker différent qui n'a aucune connaissance de l'exécution en cours, ce qui provoque un échec silencieux.
* **Production** : utilisez PostgreSQL (`DATABASE_URL`). Le verrou single-writer de SQLite peut causer une contention lors d'écritures concurrentes.
* **Développement local** : SQLite + multi-worker est correct pour une utilisation légère ; ajoutez simplement `REDIS_URL` si vous utilisez la fonctionnalité d'injection.
## Workflow Run Retention
Background cleanup task that automatically purges old workflow runs. Per-workflow overrides (configured in the workflow settings UI) take priority over these global defaults.
| Variable | Required | Default | Description |
| ------------------------------------- | -------- | ------- | --------------------------------------------------------------- |
| `WORKFLOW_RUN_MAX_AGE_DAYS` | No | `30` | Delete workflow runs older than this many days |
| `WORKFLOW_RUN_MAX_PER_WORKFLOW` | No | `100` | Keep at most this many runs per workflow (oldest deleted first) |
| `WORKFLOW_RUN_CLEANUP_INTERVAL_HOURS` | No | `24` | How often the background cleanup task runs, in hours |
### Expiration des demandes de confirmation de canal
Sweeper en arrière-plan qui marque les demandes d'approbation en attente obsolètes (produites par des hooks de canal comme `FeishuGateHook` ou le Playground d'approbation) comme expirées. Garantit qu'un clic quelques jours plus tard sur une carte oubliée ne bascule pas l'état de l'agent qui a déjà été démantelé.
| Variable | Requis | Par défaut | Description |
| --------------------------------------------- | ------ | ---------- | ----------------------------------------------------------------------------------------------------------- |
| `CHANNEL_CONFIRMATION_TTL_MINUTES` | Non | `1440` | Les confirmations en attente plus anciennes que ceci sont automatiquement expirées (par défaut : 24 heures) |
| `CHANNEL_CONFIRMATION_SWEEP_INTERVAL_SECONDS` | Non | `600` | Fréquence d'exécution du sweeper d'expiration (par défaut : toutes les 10 minutes) |
## OAuth (Optionnel)
Quand `CLIENT_ID` et `CLIENT_SECRET` sont tous les deux définis pour un fournisseur, la page de connexion affiche automatiquement le bouton OAuth correspondant.
| Variable | Requis | Par défaut | Description |
| ----------------------- | -------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GITHUB_CLIENT_ID` | Non | — | ID client de l'application GitHub OAuth. Créer sur [github.com/settings/developers](https://github.com/settings/developers) → OAuth Apps |
| `GITHUB_CLIENT_SECRET` | Non | — | Secret client de l'application GitHub OAuth |
| `GOOGLE_CLIENT_ID` | Non | — | ID client Google OAuth. Créer sur [console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) |
| `GOOGLE_CLIENT_SECRET` | Non | — | Secret client Google OAuth |
| `DISCORD_CLIENT_ID` | Non | — | ID client Discord OAuth2. Créer sur [discord.com/developers](https://discord.com/developers/applications) |
| `DISCORD_CLIENT_SECRET` | Non | — | Secret client Discord OAuth2 |
| `FEISHU_APP_ID` | Non | — | ID d'application Feishu (Lark). Créer sur [open.feishu.cn](https://open.feishu.cn/app). Nécessite la permission `contact:user.email:readonly` |
| `FEISHU_APP_SECRET` | Non | — | Secret d'application Feishu (Lark) |
| `FRONTEND_URL` | **Prod** | `http://localhost:3000` | Où le navigateur arrive après la fin d'OAuth. Doit être défini en production (ex. `https://yourdomain.com`) |
| `API_BASE_URL` | **Prod** | `http://localhost:8000` | URL du backend accessible de l'extérieur, utilisée pour construire les URLs de rappel OAuth. Doit être défini en production |
| `NEXT_PUBLIC_API_URL` | **Prod** | *(détecté automatiquement comme `:8000`)* | URL de base de l'API côté navigateur pour les redirections OAuth. **C'est une variable de temps de construction du frontend** — définissez-la dans `frontend/.env.local` pour le développement local, ou passez-la comme argument de construction Docker pour les déploiements de production personnalisés. La détection automatique fonctionne pour les configurations de proxy inverse standard (port 80/443). |
> **Prod** = optionnel localement (les valeurs par défaut fonctionnent), mais **requis pour tout déploiement accessible sur Internet**.
### URLs de rappel OAuth à enregistrer auprès de chaque fournisseur
Le backend construit les URLs de rappel comme : `{API_BASE_URL}/api/auth/oauth/{provider}/callback`
| Fournisseur | URL de rappel à enregistrer |
| ----------- | -------------------------------------------------------- |
| GitHub | `https://yourdomain.com/api/auth/oauth/github/callback` |
| Google | `https://yourdomain.com/api/auth/oauth/google/callback` |
| Discord | `https://yourdomain.com/api/auth/oauth/discord/callback` |
***
## Tunnel Cloudflare (Optionnel)
Acheminez tout le trafic via le réseau de Cloudflare au lieu d'exposer directement les ports. Élimine le besoin de Nginx, de certificats SSL et de règles de pare-feu ouvertes. Consultez la section [Déploiement en Production](/quickstart#cloudflare-tunnel) pour les instructions de configuration.
**Utilisateurs de la Chine continentale** : Les plans Cloudflare Free/Pro/Business n'ont pas de PoPs en Chine continentale. Le trafic est acheminé vers des edges à l'étranger, causant des erreurs 502 fréquentes. N'utilisez pas ceci si vos utilisateurs principaux sont en Chine continentale, sauf si vous disposez de Cloudflare Enterprise avec China Network.
| Variable | Requis | Par défaut | Description |
| ------------------------- | --------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CLOUDFLARE_TUNNEL_TOKEN` | **Oui** (si vous utilisez Tunnel) | — | Jeton de Cloudflare Zero Trust → Networks → Tunnels → votre tunnel → Configure. Commence par `eyJ...`. Requis par le sidecar `cloudflared` dans `docker-compose.tunnel.yml`. |
***
## Analyse (Optionnel)
Tous les fournisseurs d'analyse sont optionnels. Définissez n'importe quelle combinaison — tous les fournisseurs actifs se chargent simultanément. Laissez tous les champs vides pour désactiver complètement l'analyse (recommandé pour le développement local).
| Variable | Requis | Par défaut | Description |
| ---------------------------------- | ------ | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NEXT_PUBLIC_GA_MEASUREMENT_ID` | Non | — | ID de mesure Google Analytics 4 (par exemple `G-XXXXXXXXXX`). Obtenez le vôtre sur [analytics.google.com](https://analytics.google.com) |
| `NEXT_PUBLIC_UMAMI_SCRIPT_URL` | Non | — | URL du script d'analyse Umami (par exemple `https://your-umami.com/script.js`). Alternative auto-hébergée et respectueuse de la vie privée — [umami.is](https://umami.is) |
| `NEXT_PUBLIC_UMAMI_WEBSITE_ID` | Non | — | ID du site web Umami. Requis lorsque `NEXT_PUBLIC_UMAMI_SCRIPT_URL` est défini |
| `NEXT_PUBLIC_PLAUSIBLE_DOMAIN` | Non | — | Domaine d'analyse Plausible (par exemple `yourdomain.com`). Léger et respectueux de la vie privée — [plausible.io](https://plausible.io) |
| `NEXT_PUBLIC_PLAUSIBLE_SCRIPT_URL` | Non | `https://plausible.io/js/script.js` | URL de script Plausible personnalisée pour les instances auto-hébergées |
> Toutes les variables d'analyse `NEXT_PUBLIC_*` sont au **moment de la compilation** — les modifications nécessitent une reconstruction du frontend pour prendre effet.
## Stripe Billing (Optional)
Stripe powers Pro subscriptions. Leave all three variables blank to disable billing — the rest of FIM One works unchanged. **Both** `STRIPE_SECRET_KEY` **and** `STRIPE_WEBHOOK_SECRET` must be set together; partial config raises an error at first use.
| Variable | Required | Default | Description |
| --------------------------- | -------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `STRIPE_SECRET_KEY` | No | — | Stripe API secret key. Must start with `sk_test_` / `sk_live_` (full access) or `rk_test_` / `rk_live_` (restricted key). Get yours from the Stripe Dashboard → Developers → API keys. Never commit a `sk_live_*` key to source. |
| `STRIPE_WEBHOOK_SECRET` | No | — | Stripe webhook signing secret (`whsec_*`). Created when you register the webhook endpoint in Stripe Dashboard → Developers → Webhooks → Add endpoint. Required to verify inbound webhook payloads. |
| `STRIPE_BILLING_RETURN_URL` | No | `http://localhost:3000/settings?tab=billing` | URL Stripe redirects users to after Checkout / Customer Portal sessions. Set this to your production billing settings page (e.g. `https://your-domain.com/settings?tab=billing`). |