OpenClaw : guide complet de openclaw.json et bonnes pratiques

Mise à jour du 2026-06-08 : champs, dmPolicy, commandes d’audit de sécurité et conseils CVE-2026-25253 revérifiés dans la doc officielle du Gateway OpenClaw, et lectures complémentaires de la même série ajoutées. Les clés de configuration suivent la doc officielle.

Une fois OpenClaw en marche, ouvrez ~/.openclaw/openclaw.json : gateway, channel, skills, provider… et des options imbriquées partout. dmPolicy en pairing ou allowlist ? gateway.auth.token, c’est le mot de passe ? Faut-il activer toutes les compétences ?

Plus inquiétant : fin janvier 2026, correction d’une faille grave (CVE-2026-25253, CVSS 8,8) — vol de token via l’URL et exécution de commandes. Une mauvaise configuration peut transformer l’assistant en porte dérobée.

Voici le guide que j’aurais voulu à l’époque : chaque module de openclaw.json, le sens des paramètres, les réglages production, les pièges que j’ai rencontrés et une checklist sécurité.

Guide économique « élever un homard » : ArkClaw démocratise l’agent IA

OpenClaw (homard) est puissant mais la config rebute ? ArkClaw de ByteDance Volcano Engine abaisse la barrière : pas de serveur ni de token à bricoler, un assistant 24h/24 qui contrôle le navigateur, exécute des scripts et gère l’agenda.

Le prix compte : 9,9 ¥/mois, code d’invitation ZLKUK54M (inscription) → 8,9 ¥. Développeurs : Coding Plan Pro peut offrir l’accès.

Bases du fichier de configuration

Emplacement et structure

Par défaut : ~/.openclaw/openclaw.json. Créé par l’assistant d’installation ou à créer à la main. Noms de champs et valeurs par défaut : documentation Gateway. Les exemples ci-dessous illustrent la structure ; vérifiez après chaque mise à jour majeure.

Cinq modules :

• Gateway : port, authentification, logs
• Channel : WhatsApp, Telegram, etc.
• Skills : compétences et permissions
• Provider : Anthropic, modèles locaux, etc.
• Security : politiques et contrôle d’accès

Gateway = entrée, Channel = communication, Skills = capacités, Provider = cerveau, Security = protection.

Méthodes et priorité

Quatre approches :

1. Assistant interactif : à l’installation
2. Édition JSON directe : vim/nano
3. Variables d’environnement : conteneurs ou override temporaire
4. Scripts : déploiement en masse

Priorité : variables d’environnement > fichier > défaut.

Exemple : gateway.port: 18789 dans le fichier mais OPENCLAW_GATEWAY_PORT=9000 en env → port 9000. Pratique pour tester sans toucher au fichier.

Les versions 2026 ajoutent le support MCP et openclaw doctor pour diagnostiquer la configuration.

Configuration Gateway

Gateway = entrée Web et clients distants.

Port et authentification

{
  "gateway": {
    "port": 18789,
    "auth": {
      "token": "your-secret-token-here"
    },
    "remote": {
      "token": "your-remote-token-here"
    }
  }
}

• port : interface Web, défaut 18789 (http://localhost:18789). Si occupé, par ex. 19000.

• auth.token : jeton d’authentification (= mot de passe). Qui le possède contrôle l’instance. La CVE-2026-25253 venait de la fuite via URL.

• remote.token : clients distants (app mobile, bureau), séparé pour rotation indépendante.

Sécurité : depuis le 29/01/2026, plus d’"auth: none" — token ou mot de passe obligatoire.

Logs

{
  "gateway": {
    "logging": {
      "redactSensitive": true
    }
  }
}

Avec redactSensitive: true, clés API et tokens deviennent *** dans les logs.

Démarrage : openclaw gateway

[Gateway] Listening on http://localhost:18789
[Gateway] Authentication: Token-based

Configuration Channel

Channel définit les plateformes de conversation.

Railway - Plateforme de déploiement moderne, sans opérations complexes, en ligne en quelques minutes

Commencer →Pub

Types supportés

1. WhatsApp : appairage QR, le plus courant
2. Telegram : Bot API, groupes
3. Discord : communautés techniques
4. Mattermost : entreprise

WhatsApp = QR ; Telegram = Bot Token ; Discord = Application.

Politique DM (dmPolicy)

Quatre modes :

1. pairing (défaut)

{
  "channel": {
    "dmPolicy": "pairing"
  }
}

Code à 6 chiffres, validité 1 h, approbation manuelle :

openclaw pairing approve whatsapp ABC123

Équilibre sécurité / usage : première fois validée, ensuite fluide.

2. allowlist

{
  "channel": {
    "dmPolicy": "allowlist",
    "allowFrom": [
      "+1234567890",
      "telegram:@username"
    ]
  }
}

Liste blanche stricte.

3. open

{
  "channel": {
    "dmPolicy": "open",
    "allowFrom": ["*"]
  }
}

Tout le monde peut écrire — risqué, sauf démo courte.

4. disabled

DM fermés, groupes uniquement.

Isolation multi-utilisateurs

{
  "channel": {
    "session": {
      "dmScope": "per-channel-peer"
    }
  }
}

Historiques séparés, pas de mélange de contexte.

Groupes et mentionGating

{
  "channel": {
    "groupPolicy": "mention",
    "mentionGating": true
  }
}

Réponses seulement aux @mentions — évite le bot qui spamme le groupe.

Configuration Skills

Skills = ce que l’assistant peut faire.

Concepts

Extensions modulaires ; boutique ClawHub 700+ compétences :

• Calendrier (Google Calendar, Outlook)
• Navigateur (browser)
• Fichiers (file_manager)
• Shell (exec)
• Code (python, node)

Chemin : ~/.openclaw/skills/. Priorité : workspace > utilisateur > intégré.

Une compétence browser dans le projet remplace la version globale.

Gestion

Métadonnées dans SKILL.md :

---
name: google-calendar
description: Manage Google Calendar events
requirements:
  bins:
    - gcalcli
  env:
    - GOOGLE_CALENDAR_API_KEY
---

bins = binaires requis (gcalcli pour le calendrier).

Installation :

1. Interface Web « Add Skill »
2. openclaw skill install google-calendar
3. Copie manuelle dans ~/.openclaw/skills/

Dépannage

openclaw skill check google-calendar

openclaw gateway --verbose

Petits modèles

Fenêtre de contexte limitée → désactiver des compétences pour libérer des tokens.

Alibaba Cloud - Choix n°1 des développeurs, 15 % de réduction exclusive sur Lighthouse

Obtenir -15 % →Pub

Compétences à haut risque

• exec : shell arbitraire
• browser : pages web
• web_fetch : contenu externe
• web_search : recherche

À désactiver si non indispensables.

Configuration Provider

Provider = modèle IA utilisé.

Types

1. Anthropic (Claude) : recommandé, API stable, sécurité solide
2. OpenAI : bientôt (GPT-5, etc.)
3. Local : LM Studio, Ollama
4. OpenRouter : une clé, plusieurs modèles
5. MCP : Model Context Protocol (2026)

Anthropic

{
  "provider": {
    "type": "anthropic",
    "apiKey": "sk-ant-..."
  }
}

Préférez les variables d’environnement :

export ANTHROPIC_API_KEY="sk-ant-..."

Le fichier peut aller dans Git sans secrets.

Modèle local

{
  "provider": {
    "type": "openai-compatible",
    "baseURL": "http://localhost:1234/v1",
    "modelId": "kimi-k2.5-chat"
  }
}

• baseURL : serveur local (LM Studio port 1234)
• modelId : nom du modèle

MCP

{
  "provider": {
    "mcpServers": {
      "onesearch": {
        "command": "npx",
        "args": ["-y", "@onesearch/mcp-server"]
      }
    }
  }
}

OneSearch : Google, Bing, Brave via une interface.

Précautions modèles locaux

Avantages : confidentialité, coût, hors ligne. Inconvénients sécurité :

• Injection de prompt plus facile
• Petite fenêtre de contexte
• Quantification 4-bit : moins de respect des consignes

Si obligatoire : limiter les skills, sandbox, pas de données sensibles sur la machine.

Bonnes pratiques de sécurité

La sécurité passe avant tout. La CVE-2026-25253 l’a démontré.

Checklist

Base (obligatoire)

• ✅ Ne jamais partager le token gateway
• ✅ Pare-feu : n’exposer que le port nécessaire (18789)
• ✅ SSH par clé, pas par mot de passe
• ✅ Limiter l’accès Web (VPN / IP autorisées)
• ✅ DM : pairing ou allowlist
• ✅ Groupes : mention gating

Avancé (recommandé)

• ✅ Rotation des tokens (trimestrielle minimum)
• ✅ redactSensitive dans les logs
• ✅ Limiter exec, browser
• ✅ Serveur dédié, pas la machine de travail principale

Entrées externes et sandbox

Règle : traiter toute entrée externe comme hostile.

Liens, pièces jointes, texte collé — attaques possibles. Sandbox (opt-in) :

{
  "security": {
    "sandbox": {
      "enabled": true,
      "skills": ["exec", "browser"]
    }
  }
}

exec et browser isolés du système hôte.

Secrets

1. Simple : transférer .env par SCP, pas dans le chat
2. Avancé : Doppler, HashiCorp Vault

À ne jamais faire :

• ❌ Envoyer une clé API sur Telegram
• ❌ Commiter les secrets
• ❌ Publier des logs bruts (tokens dedans)

Audit

openclaw security audit
openclaw security audit --deep
openclaw security audit --fix

Vérifie : force du token, exposition du port, permissions (~/.openclaw 700, fichier 600), skills à risque, politique DM.

Permissions fichiers

chmod 700 ~/.openclaw
chmod 600 ~/.openclaw/openclaw.json

Interdits

• ❌ Port 18789 sur Internet public
• ❌ Accès shell sans comprendre le risque
• ❌ Skills de source non vérifiée
• ❌ dmPolicy: "open" en production
• ❌ Machine avec e-mail bancaire principal

Cas pratiques

Scénario 1 : personnel, WhatsApp, pairing

{
  "gateway": {
    "port": 18789,
    "auth": {
      "token": "generate-a-strong-random-token"
    },
    "logging": {
      "redactSensitive": true
    }
  },
  "channel": {
    "type": "whatsapp",
    "dmPolicy": "pairing",
    "session": {
      "dmScope": "per-channel-peer"
    }
  },
  "skills": {
    "enabled": [
      "calendar",
      "web_search",
      "file_manager"
    ],
    "disabled": [
      "exec",
      "browser"
    ]
  },
  "provider": {
    "type": "anthropic"
  },
  "security": {
    "sandbox": {
      "enabled": true
    }
  }
}

Sécurisé, fonctionnel, skills dangereux coupés.

Scénario 2 : équipe, multi-canal, allowlist

{
  "gateway": {
    "port": 18789,
    "auth": {
      "token": "team-gateway-token"
    },
    "remote": {
      "token": "team-remote-token"
    }
  },
  "channel": [
    {
      "type": "telegram",
      "dmPolicy": "allowlist",
      "allowFrom": [
        "telegram:@alice",
        "telegram:@bob",
        "telegram:@carol"
      ],
      "groupPolicy": "mention",
      "mentionGating": true
    },
    {
      "type": "discord",
      "dmPolicy": "allowlist",
      "allowFrom": [
        "discord:123456789"
      ]
    }
  ],
  "skills": {
    "enabled": [
      "calendar",
      "web_search",
      "github",
      "jira"
    ]
  },
  "provider": {
    "type": "anthropic"
  }
}

Tableau channel pour plusieurs plateformes ; mention gating en groupe.

Scénario 3 : local, hors ligne, skills réduits

{
  "gateway": {
    "port": 19000
  },
  "channel": {
    "type": "whatsapp",
    "dmPolicy": "allowlist",
    "allowFrom": ["+1234567890"]
  },
  "skills": {
    "enabled": [
      "calculator",
      "file_manager"
    ]
  },
  "provider": {
    "type": "openai-compatible",
    "baseURL": "http://localhost:1234/v1",
    "modelId": "llama-3.1-8b"
  }
}

Peu de skills pour tenir dans le contexte du petit modèle.

Erreurs courantes

Erreur 1 : token incorrect

Symptôme : « Authentication failed »

Vérifier gateway.auth.token (espaces, retours ligne).

KiloClaw - OpenClaw managé pour l’entreprise : orchestration d’agents IA et routage intelligent

Commencer →Pub

Erreur 2 : dépendances manquantes

Symptôme : Skill 'google-calendar' failed to load

openclaw skill check google-calendar

Erreur 3 : port occupé

Symptôme : Error: listen EADDRINUSE :::18789

Autre port ou libérer le processus.

Erreur 4 : JSON invalide

Symptôme : SyntaxError: Unexpected token }

Validateur JSON — virgules ou guillemets.

Commandes

openclaw status
openclaw doctor
openclaw gateway --verbose

À lire aussi

• Guide d’installation complet OpenClaw : de la préparation à la première exécution
• Architecture OpenClaw en détail : conception à trois niveaux
• OpenClaw vs ChatGPT : architecture, coût et confidentialité

Conclusion

Trois idées :

Le fichier de config est le cœur d’OpenClaw — comprendre chaque champ accélère le dépannage.

La sécurité d’abord — CVE-2026-25253, tokens secrets, ports limités, DM stricts, skills à risque sous contrôle.

La config évolue — revoyez-la, lancez openclaw security audit.

À faire maintenant :

1. openclaw security audit --deep
2. Optimiser selon cette checklist
3. Sauvegarder la config (sans les tokens)

La communauté (GitHub Discussions, Discord) aide ; partagez vos retours d’expérience.