Agent runtimes 선택

기준일: 2026-07-26
난이도: 고급
공식 기준: Agent runtimes, Codex harness, Attach CLI, Cloud Workers

Agent runtime은 준비된 한 번의 model loop를 소유합니다. 프롬프트를 받고, 모델 출력을 돌리고, native tool call을 처리한 뒤 완료된 turn을 OpenClaw로 돌려줍니다. Provider·model 이름과 자주 섞이지만 레이어가 다릅니다.

핵심 개념

레이어	예	의미
Provider	anthropic, openai, github-copilot	인증·모델 카탈로그·model ref 이름
Model	anthropic/…, openai/gpt-5.6-sol	turn에 선택된 모델
Agent runtime	openclaw, codex, copilot, claude-cli	실제 loop/backend
Channel	Discord, Slack, Telegram	메시지 입·출 표면

공개 설정은 provider/model 항목의 agentRuntime.id를 씁니다. 에이전트 전체 runtime 키는 legacy이며 무시됩니다. openclaw doctor --fix이 오래된 whole-agent pin과 legacy model ref를 정리합니다.

네 가지 선택지 (이 가이드 범위)

선택	한 줄	언제
Built-in openclaw	OpenClaw embedded runner가 loop·transcript·tool 경로 소유	기본·플러그인 없는 안정 경로, OpenAI 모델에 명시 호환 경로
Codex harness (codex)	Codex app-server가 저수준 세션 소유, OpenClaw가 채널·미러·dynamic tools	ChatGPT/Codex 구독·openai/* 에이전트 경험
openclaw attach	Claude Code를 임시 Gateway MCP grant로 기동	외부 Claude Code 세션에 Gateway 도구만 짧게 붙일 때
Cloud workers	turn loop는 임시 클라우드 박스, transcript·placement는 Gateway	호스트 밖에서 에이전트 실행, 자격 증명은 Gateway에 유지

관련: CLI backend claude-cli는 embedded harness id가 아닙니다. 모델 ref는 anthropic/...로 두고 agentRuntime.id: "claude-cli"로 실행 백엔드를 지정합니다. Claude Code·Gemini CLI·Cursor 등 외부 harness 전체 제어는 보통 ACP 경로입니다.

선택 기준

1. 채널 메시징 + OpenClaw 도구·세션 저장소가 중심 → 기본 openclaw 또는 필요 시 모델 스코프 runtime 정책.
2. Codex/ChatGPT 구독으로 OpenAI 에이전트 turn → openai/<model>, @openclaw/codex 플러그인, /codex 제어 표면. fail-closed면 agentRuntime.id: "codex".
3. 이미 Claude Code를 쓰고 Gateway MCP 도구만 필요 → openclaw attach (세션 바인딩·TTL·--strict-mcp-config).
4. Gateway 호스트가 아닌 throwaway 머신에서 loop 실행 → cloudWorkers.profiles + managed worktree + sessions.dispatch. OpenClaw runtime만 지원; claude-cli 등 external CLI runtime 세션은 dispatch 불가.
5. PI vs Codex vs Copilot SDK 비교 → 공식 Agent runtimes / GitHub Copilot agent runtime. copilot은 auto로 선택되지 않음.

Runtime 소유권 (요약)

표면	OpenClaw embedded	Codex app-server
Model loop	OpenClaw	Codex app-server
Canonical thread	OpenClaw transcript	Codex thread + OpenClaw mirror
Dynamic tools	native	adapter bridge
Channel delivery	OpenClaw	OpenClaw

실습

Built-in OpenClaw (호환 명시)

{
  agents: {
    defaults: {
      model: "openai/gpt-5.6-sol",
      models: {
        "openai/gpt-5.6-sol": {
          agentRuntime: { id: "openclaw" },
        },
      },
    },
  },
}

선택 순서: (1) model-scoped agentRuntime (2) provider-scoped models.providers.<provider>.agentRuntime (3) auto 클레임 (4) 그 외 기본 경로.

OpenAI 예외 (중요): 에이전트 모델이 openai/* 이면, runtime을 명시하지 않거나 auto여도 기본 harness는 Codex 입니다. 내장 OpenClaw loop로 쓰려면 agentRuntime.id: "openclaw" 를 명시해야 합니다(위 JSON 예시). 반대로 Codex fail-closed면 agentRuntime.id: "codex" — 실패 시 OpenClaw로 조용히 떨어지지 않습니다. 자세한 클레임·discovery 규칙은 공식 Agent runtimes를 따릅니다.

Codex harness

openclaw plugins install @openclaw/codex
openclaw models auth login --provider openai

{
  plugins: {
    entries: {
      codex: { enabled: true },
    },
  },
  agents: {
    defaults: {
      model: "openai/gpt-5.6-sol",
    },
  },
}

plugins.allow를 쓰면 codex를 포함합니다. 게이트웨이 재시작 후 기존 채팅은 /new 또는 /reset으로 harness를 다시 resolve합니다. 채팅에서 /status에 Runtime: OpenAI Codex가 보이면 성공. /codex status, /codex models, /codex binding으로 app-server 상태를 봅니다.

Codex-only 배포:

{
  models: {
    providers: {
      openai: {
        agentRuntime: { id: "codex" },
      },
    },
  },
}

Attach (Claude Code + Gateway MCP)

openclaw attach
openclaw attach --session agent:main:telegram:123 --ttl 600000
openclaw attach --print-config

옵션	의미
--session <key>	Gateway 세션에 grant 바인딩 (기본: main)
--ttl <ms>	요청 TTL; Gateway 상한 적용
--bin <path>	Claude Code 바이너리 (기본 claude)
--print-config	임시 .mcp.json·실행 명령·env 출력, spawn/revoke 없음

bearer는 argv가 아니라 환경 변수로 전달됩니다. OpenClaw는 claude --strict-mcp-config --mcp-config <path>로 ambient MCP를 붙이지 않습니다. 일반 실행은 Claude 프로세스 종료 시 grant revoke.

Cloud workers

openclaw.json에 프로필(예: crabbox + AWS). 요약 필드: provider, install (bundle|npm), settings (backend class, ttl, idleTimeout, idempotent setup).

{
  "cloudWorkers": {
    "profiles": {
      "aws": {
        "provider": "crabbox",
        "install": "bundle",
        "settings": {
          "provider": "aws",
          "class": "standard",
          "ttl": "8h",
          "idleTimeout": "45m",
          "setup": "test -x /usr/bin/node || (curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt-get install -y nodejs)"
        }
      }
    }
  }
}

요구: worker provider 플러그인, 세션 managed worktree (worktree: true), 박스에 Node(setup), AWS면 Crabbox 0.38.1+ 및 instance profile 비부착 검증.

openclaw gateway call sessions.create \
  --params '{"key":"agent:main:big-refactor","worktree":true,"cwd":"/path/to/repo","worktreeName":"big-refactor"}'

openclaw gateway call sessions.dispatch \
  --timeout 1500000 \
  --params '{"key":"agent:main:big-refactor","profileId":"aws"}'

모델 inference·provider credential은 Gateway 프록시. 완료 후 workspace는 managed worktree로 reconcile. 중지: UI Stop cloud worker 또는 sessions.reclaim. 프로필 미설정 시 sessions.dispatch RPC 자체가 없을 수 있습니다.

체크리스트

• provider / model / runtime / channel 네 레이어를 섞어 쓰지 않았다.
• Codex면 플러그인 enable + openai/* + /status Runtime 확인.
• fail-closed가 필요하면 명시 agentRuntime.id (auto만 아닐 때).
• attach는 session key·TTL·strict MCP를 이해했다.
• cloud worker는 OpenClaw runtime + managed worktree + setup Node를 맞췄다.
• legacy pin은 openclaw doctor --fix로 정리했다.

다음 단계

• 플러그인과 ClawHub
• Gateway 운영
• CLI 명령어 — openclaw attach, sessions, doctor
• 서브 에이전트 — runtime과 별개인 spawn 표면