OpenHands : du kit d'outils à la plateforme Agent sur Cloud Mac

Ces deux dernières semaines, la série Stack a posé couche par couche le L1 Runner (Fact), L2 Ollama (Inference) et L4 MCP (Context). Une phrase revient dans presque tous les retours : « Tous les outils sont là — mais j'enchaîne encore le flux à la main. » Claude Code livre le Diff, MCP récupère le contexte GitHub, le Runner passe au vert après le push — et malgré tout, quelqu'un reste quarante minutes au terminal pour « corriger l'issue #142 et ouvrir la PR ».

C'est précisément ce que couvre L5 · OpenHands : pas un CLI de plus, mais le passage d'un kit d'outils à une plateforme qui exécute des tâches d'ingénierie multi-étapes de façon autonome sur Cloud Mac. Ce texte est L5-Q01 · R1 · Hub de série : du « outil de code » à la « plateforme Agent » — position du Workflow dans le Stack, pourquoi OpenHands vs Claude Code n'est pas une question de remplacement, tâches typiques et OpenHands self-hosted sur macOS. Pas d'installation Docker ici (c'est L5-Q02).

Le piège du kit d'outils : chaque outil est bon, la chaîne reste manuelle

Un déroulé de semaine typique (que nous avons vu plusieurs fois dans des repos clients) :

1. Lundi : Claude Code modifie la couche API, MCP tire la liste des issues — tout roule en session.
2. Mardi : un collègue pousse depuis une autre machine, Runner rouge — personne n'a aligné les changements Agent avec les scripts CI (sans L1 execution engine, ça se répète).
3. Mercredi : tests à la main, config ajustée, nouvelle session Claude Code pour les fichiers manquants.
4. Jeudi : enfin vert — mais doc, scripts de migration, tests d'exemple manquent, parce qu'on a confondu « modifier le code » et « livrer la demande ».

Signe d'un kit d'outils : chaque étape a le meilleur outil, mais aucune couche ne porte toute la demande. Une plateforme Agent ajoute une couche Workflow qui décompose, exécute et reprend après les erreurs — OpenHands en est l'option open source dans le Stack (écosystème successeur d'OpenDevin).

Langage Stack : Workflow vs Context / Diff / Fact

Dans toute la série : ne pas dessiner le Workflow comme simple aval du Fact. Le Workflow (L5) est une orchestration qui, dans le cycle de tâche, consomme le Context, produit le Diff, vérifie avec le Fact, jusqu'à « demande satisfaite » :

Cloud Mac AI Stack · relations de livrables (≠ ordre d'appel)

  Workflow（L5 · OpenHands）
  ├── Context（L4 · MCP）          ← lire repo / issue / API
  ├── Diff（L3 · Claude Code）   ← modifier code / fichiers
  └── Fact（L1 · Runner / tests）← signal test / build / CI

Boucle Agent（dans Workflow · itérable）
       Diff  ↔  Fact
         ↑       ↓
      Observe → Plan → Execute …

Quatre types de livrables en parallèle : Context · Diff · Fact · Workflow (MCP · codage · Runner · OpenHands). L'Inference (L2 · Ollama) reste optionnelle, volontairement hors schéma pour éviter la confusion avec la boucle Agent.

Le Workflow n'est pas « un job CI de plus », mais une machine à états de tâche multi-étapes, interruptible : dans la boucle, Diff et Fact plusieurs fois, jusqu'à PR livrable. Claude Code excelle sur un Diff en une passe ; OpenHands sur le déroulement non supervisé de toute la boucle — à condition que Context et Fact soient en place.

OpenHands en une minute (pas un lexique)

OpenHands est une plateforme open source d'agent d'ingénierie logicielle autonome : dans un sandbox (typiquement Docker), elle reçoit un objectif en langage naturel et enchaîne Plan → code/commandes → lecture de sortie → débogage, avec liaison GitHub (issues, PR, statut CI). Dans le Cloud Mac AI Stack, elle ne remplace ni le pair programming de Claude Code ni la preuve objective de build du Runner, mais orchestre la livraison multi-étapes par-dessus.

OpenHands vs Claude Code : pas de concurrence, des niveaux différents

Ceux qui cherchent OpenHands vs Claude Code ou alternative Claude Code demandent souvent : l'un peut-il remplacer l'autre ? Dans le Stack : non, et ce ne devrait pas être l'objectif — niveau et livrable différents :

• Claude Code (L3) → Diff : pair programming, vous êtes là.
• OpenHands (L5) → Workflow : agent autonome, vous fixez l'objectif.

Utiliser OpenHands comme « second Claude Code » échoue vite : faible sur l'intuition produit vague ; Claude Code faible sur huit étapes d'issue non supervisées. La bonne approche : superposer les couches — Claude Code le jour pour les points durs, OpenHands la nuit sur la file d'issues.

Règle empirique : intention PR en une phrase → Claude Code ; « traiter l'issue » → OpenHands. Avec l'index CodeGraph sur gros repo, le pair programming reste souvent Claude Code ; OpenHands convient aux tâches backend templatisées. Les deux partagent le Context MCP, pas le rôle.

Quelles tâches pour OpenHands ? (première intention de recherche)

Ceux qui tapent OpenHands agent ou OpenHands github veulent savoir : qu'est-ce qui est déléguable de façon fiable ? Sous tests + CI, nous recommandons — aussi pool pour L5-Q02 :

Pas comme première tâche OpenHands : gros refactor sans tests, refonte UX, migration schema critique avec validation métier, secrets prod. Reste en sessions Claude Code avec gate humain, puis Runner pour le Fact.

Comment OpenHands travaille (boucle Agent)

Les recherches How OpenHands works ou OpenHands agent loop visent à comprendre : comment une phrase devient une PR mergeable ? Le cœur est la boucle en quatre temps Plan → Execute → Observe → Debug :

Boucle Agent OpenHands (concept · pas pipeline unique)

        ┌──────────┐
        │   Plan   │  ← Context
        └────┬─────┘
             ▼
        ┌──────────┐
        │ Execute  │  → Diff
        └────┬─────┘
             ▼
        ┌──────────┐
        │ Observe  │  ← Fact (test / build / CI)
        └────┬─────┘
             │
      fail   │  pass
             ▼
        ┌──────────┐        ┌─────────────┐
        │  Debug   │ ──────▶│ Workflow OK │ → PR
        └────┬─────┘        └─────────────┘
             │
             └──── retour Plan ou Execute

Ce n'est pas un « chat plus fort » : l'architecture OpenHands est une machine à tâches avec état — chaque Observe alimente la trajectoire du Plan suivant. Fix bug et nettoyage lint, même boucle, entrée Plan différente. Replay de tâche ci-dessous ; Docker/UI dans L5-Q02.

D'abord L0–L4, puis L5 — sinon sandbox sans preuve organisationnelle

Nous déconseillons « OpenHands jour un ». Ordre comme déploiement L1, plus L5 après MCP :

1. L0 — Cloud Mac comme nœud macOS permanent.
2. L1 — Runner : push → vert/rouge reproductible.
3. L2–L3 — Ollama + Claude Code optionnels sur le Fact.
4. L4 — Hub MCP + modèle de permissions : lecture/écriture auditable.
5. L5 — OpenHands : Workflow multi-étapes.

Sans L1, OpenHands peut techniquement ouvrir des PR — l'équipe n'évalue pas le risque de merge. Même erreur organisationnelle que « SSH vert, Actions rouge ». Sans L4, la surface de tokens de l'agent autonome grossit.

Déroulement réel : Plan → Execute → Observe → Debug

Replay sur un fork sandbox (chiffres illustratifs), aligné avec la boucle Agent :

Objectif : issue #218 « export CSV sans BOM UTF-8 »

  ① Lire issue + src/export/*.ts     ~2 min · Context
  ② Plan en 6 étapes                 ~1 min · Plan
  ③ 4 fichiers + 1 test              ~8 min · Execute
  ④ pnpm test → snapshot fail        ~3 min · Observe · Fact
  ⑤ Log → corriger 2 fichiers        ~5 min · Debug → Execute
  ⑥ Tests verts                      ~3 min
  ⑦ PR + lien issue                  ~1 min · livraison Workflow

~23 min wall time · Humain : valider l'objectif + revue merge

Étape ④ (Observe) : les échecs de test sont l'entrée de la boucle, pas une catastrophe. En pair programming vous corrigez tout de suite ; OpenHands a besoin d'Observe → Debug → Fact dans la prochaine passe Execute. Sans commande de test fixe (L1 non ancré), la boucle tourne à vide — encore une fois : Runner avant OpenHands.

Concept de déclenchement (pas tutoriel d'install) :

# Concept : label issue démarre tâche autonome
on:
  issues:
    types: [labeled]
if: github.event.label.name == 'agent:openhands'
run: |
  openhands run \
    --repo "${{ github.repository }}" \
    --issue "${{ github.event.issue.number }}" \
    --max-iterations 40 \
    --sandbox docker

Runner · OpenClaw · OpenHands : trois noms, trois rôles

OpenClaw ne tranche pas l'architecture — « quand exécuter, comment notifier ». OpenHands ne signe pas les archives iOS — livrables : PR reviewables et logs d'étapes. Les trois sur un même Cloud Mac, mais ne pas mélanger dans un seul runbook.

Architecture typique : OpenHands self-hosted · Docker · macOS

Les recherches OpenHands Mac ou OpenHands self-hosted demandent la topologie, pas les étapes d'install. Forme minimale de prod sur Cloud Mac Apple Silicon :

OpenHands self-hosted on macOS (Cloud Mac · L0)

  GitHub（issues / webhooks / PR）
           │
           ▼
  ┌─────────────────────────────────────┐
  │  Cloud Mac · macOS · Apple Silicon   │
  │  ┌─────────────┐  ┌───────────────┐  │
  │  │ OpenHands   │  │ Claude Code   │  │  L5 + L3 (même nœud optionnel)
  │  │ (Docker)    │  │ (SSH/Terminal)│  │
  │  └──────┬──────┘  └───────────────┘  │
  │         │ sandbox workspace           │
  │         ▼                             │
  │  ┌─────────────┐  ┌───────────────┐  │
  │  │ MCP Servers │  │ Ollama (opt.) │  │  L4 · L2
  │  └─────────────┘  └───────────────┘  │
  │         │ git push                    │
  │         ▼                             │
  │  ┌─────────────────────────────────┐  │
  │  │ GitHub Runner (self-hosted)     │  │  L1 Fact
  │  └─────────────────────────────────┘  │
  └─────────────────────────────────────┘

Pourquoi le Workflow sur Cloud Mac, pas sur le laptop ?

• Durée — tâches souvent 30–90 min ; capot fermé = interruption.
• Docker — daemon stable ; Cloud Mac 24/7.
• Avec Runner dans le Stack — même nœud valide après push Agent, moins de SSH vert / Actions rouge.
• ABI — cibles iOS/macOS sur Apple Silicon, pas les surprises d'un VPS Linux.

Démarrage Docker minimal (concept ; compose complet dans L5-Q02) :

# Cloud Mac · OpenHands self-hosted (esquisse)
docker pull docker.all-hands.dev/all-hands-ai/openhands:0.9
docker run -d --name openhands \
  -e SANDBOX_USER_ID=$(id -u) \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v $HOME/.openhands:/.openhands \
  -p 3000:3000 \
  docker.all-hands.dev/all-hands-ai/openhands:0.9

Stack Agent L5 : quel Cloud Mac ?

Après l'architecture, la spécification — repères tirés de combinaisons Stack réelles :

La chaîne Workflow → Cloud Mac → spécification : d'abord clarifier le besoin L5, puis dimensionner le nœud pour Docker + Ollama optionnel + Runner — pas l'inverse, louer du hardware puis empiler les outils.

Poser les limites vaut mieux que le hype Agent

Scripts et services : oui ; écriture prod réglementée : non. OpenHands est un accélérateur d'ingénierie, pas un « Auto-DevOps » qui décharge la responsabilité.

Décision : passer Cloud Mac en plateforme Agent ?

Auto-évaluation — ≥3 cases à gauche avant investissement L5 :

En bref : OpenHands n'est pas un « chat plus malin », mais le passage d'un kit d'outils à une responsabilité de demande à l'échelle plateforme — quand Fact (Runner) et Context/politique (MCP) sont en place. Sinon vous automatisez seulement l'enchaînement manuel, le merge reste risqué.

Série L5 : de la décision à la première tâche autonome

Avant L6, boucler au moins ② — sans tutoriel OpenHands reproductible, le Hub manque d'atterrissage. Carte globale dans L6-Q01 ; la série passe de « stack d'outils IA » à « plateforme d'ingénierie IA ».

FAQ

Boucle Agent ?
Plan → Execute → Observe → Debug ; voir comment OpenHands travaille.

OpenHands vs Claude Code ?
Pas l'un ou l'autre ; voir comparaison.

Installation ?
Hub sans pas-à-pas ; L5-Q02 (prévu 14.06.).

Self-hosted sur Mac ?
Oui — Cloud Mac + Docker ; architecture.

Sans Runner ?
Ça tourne, déconseillé — d'abord L1.

OpenClaw ?
Triangle et note OpenClaw.

Spécification ?
tableau L5 ; OpenHands seul dès M4 16 Go.