TeeckIn/Docs

Dépannage

Problèmes courants et solutions pour l'intégration des agents IA.

Problèmes d'authentification

Erreur « invalid_client »

Causes possibles :

  • -Le Client ID ou le Client Secret a été mal copié
  • -Le Client Secret a été révoqué
  • -L'agent a été désactivé

Solutions :

  • +Vérifiez que TEECKIN_CLIENT_ID commence par « teeckin_agent_ »
  • +Vérifiez que TEECKIN_CLIENT_SECRET commence par « tcs_ »
  • +Vérifiez l'état du secret dans Paramètres > Agents > onglet Secrets
  • +Créez un nouveau secret si l'actuel a été révoqué

Erreur « Access token expired »

Causes possibles :

  • -Les jetons d'accès sont valables 1 heure
  • -Le jeton n'a pas été renouvelé avant son expiration

Solutions :

  • +Demandez un nouveau jeton d'accès avec vos identifiants client
  • +Le serveur MCP s'en charge automatiquement
  • +Pour l'utilisation de l'API, demandez un nouveau jeton sur /api/oauth/token

Erreur « Agent not found »

Causes possibles :

  • -Utilisation des identifiants d'un agent supprimé
  • -L'agent n'a jamais été correctement créé

Solutions :

  • +Créez un nouvel agent et enregistrez les identifiants
  • +Veillez à copier à la fois le Client ID et le Client Secret lorsqu'ils s'affichent

Problèmes de Timer

Le Timer ne démarre pas

Causes possibles :

  • -Un autre Timer est déjà en cours
  • -ID de Topic invalide
  • -Limite de débit dépassée

Solutions :

  • +Vérifiez l'état avec teeckin_get_status ou GET /api/timer/active
  • +Arrêtez le Timer existant avant d'en démarrer un nouveau
  • +Utilisez teeckin_list_topics pour obtenir des IDs de Topics valides

Le Timer s'est arrêté de façon inattendue

Causes possibles :

  • -Quelqu'un l'a arrêté manuellement dans l'interface
  • -Redémarrage du serveur (rare)
  • -L'agent a été désactivé en cours de session

Solutions :

  • +Vérifiez vos pointages pour voir s'il a été enregistré
  • +Démarrez un nouveau Timer si nécessaire

Le pointage n'apparaît pas

Causes possibles :

  • -Le Timer est toujours en cours (pas arrêté)
  • -Vous consultez une mauvaise plage de dates
  • -Vous consultez l'espace de travail personnel au lieu de l'organisation

Solutions :

  • +Arrêtez le Timer pour créer l'entrée
  • +Vérifiez le calendrier à la bonne date
  • +Basculez vers le bon contexte d'organisation

Problèmes de Topics

Erreur « Topic not found »

Causes possibles :

  • -Utilisation d'un ID de Topic qui n'existe pas
  • -Le Topic a été supprimé
  • -Le Topic se trouve dans une autre organisation

Solutions :

  • +Actualisez votre liste de Topics avec teeckin_list_topics
  • +Utilisez la liste de Topics mise à jour pour obtenir des IDs valides

La correspondance approximative choisit le mauvais Topic

Causes possibles :

  • -Plusieurs Topics ont des noms similaires
  • -La requête est trop ambiguë

Solutions :

  • +Utilisez des noms de Topics plus spécifiques
  • +Utilisez l'ID complet du Topic au lieu du nom
  • +Incluez le nom de la catégorie : « Backend API Development »

Problèmes de serveur MCP (Claude Code)

Le serveur MCP ne se connecte pas

Causes possibles :

  • -JSON invalide dans .mcp.json ou .claude/settings.json
  • -Variables d'environnement non définies (TEECKIN_CLIENT_ID, TEECKIN_CLIENT_SECRET)
  • -Problèmes de connectivité réseau
  • -Un pare-feu bloque les connexions HTTPS

Solutions :

  • +Validez la syntaxe de votre JSON avec un validateur JSON
  • +Vérifiez que les variables d'environnement sont exportées dans le profil de votre shell
  • +Testez la connectivité réseau : curl https://api.teeckin.com/mcp
  • +Vérifiez que votre réseau autorise les connexions HTTPS sortantes (port 443)

Tester la connexion

Vérifiez que vos identifiants fonctionnent avec curl :

bash
# First get an access token
curl -X POST https://api.teeckin.com/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=$TEECKIN_CLIENT_ID" \
  -d "client_secret=$TEECKIN_CLIENT_SECRET"

# Then test the MCP endpoint
curl -X POST https://api.teeckin.com/mcp \
  -H "Authorization: Bearer tat_..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Claude ne voit pas les outils TeeckIn

Causes possibles :

  • -L'URL du serveur MCP n'est pas configurée dans .mcp.json
  • -Claude Code doit redémarrer après les modifications de configuration
  • -Les identifiants OAuth ne sont pas configurés dans la section env

Solutions :

  • +Vérifiez que mcpServers.teeckin.url est défini sur https://api.teeckin.com/mcp
  • +Redémarrez Claude Code après avoir modifié les fichiers de configuration
  • +Vérifiez que la section env inclut TEECKIN_CLIENT_ID et TEECKIN_CLIENT_SECRET

Problèmes de serveur MCP (Codex)

Le serveur MCP ne se connecte pas

Causes possibles :

  • -TOML invalide dans ~/.codex/config.toml
  • -Section [mcp_servers.teeckin] manquante
  • -TEECKIN_CLIENT_ID ou TEECKIN_CLIENT_SECRET non exporté dans le shell

Solutions :

  • +Vérifiez la syntaxe TOML : les sections ont besoin de [crochets] et les chaînes de "guillemets"
  • +Exécutez npx @teeckin/agent init --codex pour régénérer la configuration
  • +Assurez-vous que TEECKIN_CLIENT_ID et TEECKIN_CLIENT_SECRET sont tous deux exportés dans le profil de votre shell

Codex ne voit pas les outils TeeckIn

Causes possibles :

  • -La configuration n'est pas dans ~/.codex/config.toml (niveau utilisateur)
  • -Codex doit redémarrer après les modifications de configuration
  • -Il manque les identifiants OAuth dans env_vars

Solutions :

  • +La configuration MCP doit se trouver dans ~/.codex/config.toml, pas au niveau du projet
  • +Redémarrez Codex après avoir modifié config.toml
  • +Vérifiez que [mcp_servers.teeckin] inclut env_vars = ["TEECKIN_CLIENT_ID", "TEECKIN_CLIENT_SECRET"]

Les hooks ne se déclenchent pas

Causes possibles :

  • -hooks.json n'est pas dans le répertoire .codex/
  • -La fonctionnalité de hooks n'est pas activée dans config.toml
  • -Syntaxe JSON invalide dans hooks.json

Solutions :

  • +Assurez-vous que .codex/hooks.json existe à la racine de votre projet
  • +Ajoutez [features] codex_hooks = true à config.toml si nécessaire
  • +Validez la syntaxe de hooks.json avec un validateur JSON

Limitation de débit

Erreur « Rate limit exceeded » (429)

Causes possibles :

  • -Trop d'appels à l'API en peu de temps
  • -Script ou boucle hors de contrôle
  • -Plusieurs intégrations partageant les mêmes identifiants

Solutions :

  • +Patientez 60 secondes et réessayez
  • +Implémentez un backoff exponentiel dans votre intégration
  • +Utilisez des agents ou des secrets distincts pour des intégrations distinctes
  • +Mettez la liste des Topics en cache au lieu de la récupérer à répétition

Limites de débit

  • Requêtes GET : 120 par minute
  • Requêtes POST/PATCH : 30 par minute
  • Opérations du Timer : 10 par minute

Problèmes de permissions

« Permission refusée » lors de l'accès aux paramètres des agents

Causes possibles :

  • -Vous n'êtes pas dans le contexte d'organisation
  • -Tentative d'accès aux agents d'un autre membre
  • -Le rôle dans l'organisation n'autorise pas l'accès

Solutions :

  • +Basculez vers la bonne organisation
  • +Vous ne pouvez gérer que vos propres agents (sauf si vous êtes administrateur)
  • +Demandez de l'aide à un administrateur pour les paramètres d'agents à l'échelle de l'organisation

L'agent ne peut pas accéder à la facturation/aux taux

Causes possibles :

  • -C'est le comportement attendu : les agents ont des permissions restreintes

Solutions :

  • +Les agents ne peuvent pas voir, intentionnellement, les taux horaires ni les données de facturation
  • +C'est une fonctionnalité de sécurité, pas un bug

Problèmes d'agents personnels

L'onglet « Agents » n'apparaît pas dans Paramètres

Causes possibles :

  • -Vous consultez actuellement un contexte d'organisation
  • -Les agents personnels nécessitent l'espace de travail personnel

Solutions :

  • +Basculez vers l'espace de travail personnel (cliquez sur votre nom dans la barre latérale et sélectionnez « Personnel »)
  • +Les agents personnels ne sont visibles que dans les Paramètres personnels, pas dans les organisations

Erreur « Pro subscription required »

Causes possibles :

  • -Le forfait gratuit n'inclut pas les agents personnels
  • -Les agents personnels nécessitent Pro ou supérieur

Solutions :

  • +Passez à l'abonnement Pro pour accéder aux agents personnels
  • +Si vous utilisez une organisation, celle-ci a besoin du forfait Team pour les agents d'organisation

L'agent personnel suit le temps sur les mauvais Topics

Causes possibles :

  • -L'agent accède à des Topics d'organisation alors que des Topics personnels étaient attendus
  • -L'agent a été créé dans le mauvais contexte

Solutions :

  • +Les agents personnels n'accèdent qu'aux Topics personnels
  • +Les agents d'organisation n'accèdent qu'aux Topics de cette organisation
  • +Créez un nouvel agent dans le bon contexte si nécessaire

Obtenir de l'aide

Si vous rencontrez toujours des problèmes :

  • 1.Vérifiez que vos identifiants sont valides et que l'agent est actif
  • 2.Testez l'API directement avec curl pour isoler le problème
  • 3.Examinez les journaux de Claude Code à la recherche d'erreurs propres à MCP
  • 4.Contactez le support avec votre message d'erreur et les étapes pour reproduire le problème