AgenticROS

    _                     _   _       ____   ___  ____
   / \   __ _  ___ _ __ | |_(_) ___ |  _ \ / _ \/ ___|
  / _ \ / _` |/ _ \ '_ \| __| |/ __|| |_) | | | \___ \
...

ROS 로봇을 위한 물리적 AI 에이전트

▶ YouTube에서 AgenticROS 소개 영상 시청하기

AgenticROS는 ROS 2 로봇을 에이전트 네이티브(agent-native) 머신으로 변환합니다. 말하거나, 타이핑하거나, 메시지를 보내면 로봇은 지각하고(perceives), 추론하며(reasons), 행동합니다(acts). 이는 최첨단 추론 모델의 세계와 카메라, 깊이 센서(depth sensors), 모터, 그리고 cmd_vel의 세계를 연결하는 개방적이고 AI 에이전트 독립적인 인터페이스 계층입니다. 따라서 로봇은 원격 조종 도구에서 벗어나 팀원처럼 협업하기 시작합니다.

AgenticROS를 사용하면 로봇이 자신이 보는 것을 설명하고, 의도(

• OpenClaw — ROS 2 도구, 명령어, 설정 UI, 원격 조종 웹 앱 및 스킬 로더를 갖춘 네이티브 게이트웨이 플러그인입니다. 대표적인 통합 솔루션입니다.
• NVIDIA NemoClaw — NemoClaw의 OpenShell 샌드박스 내에서 정책 기반 이탈(policy-enforced egress) 및 관리형 NVIDIA 추론을 통해 AgenticROS를 실행합니다. ROS 2, RealSense, rosbridge는 호스트에 유지되는 동안 플러그인은 샌드박스 내에서 실행됩니다.
• Anthropic Claude — 단일 MCP 서버가 Claude Code(터미널), Claude Desktop(macOS / Windows), 및 Claude Dispatch(iOS, Mac과 페어링)에 전력을 공급합니다. Claude에게 로봇이 무엇을 보는지 물으면, 실시간 카메라 스냅샷과 깊이 측정값으로 답변합니다.
• OpenAI Codex CLI — Claude Code와 동일한 MCP 서버를 사용합니다. 하나의 명령어로 Codex를 등록할 수 있습니다: agenticros codex setup (MCP 바이너리에 대한 절대 경로가 포함된 ~/.codex/config.toml을 작성). 전체 도구 표면(tool surface)을 활용할 수 있습니다: 미션, 따라가기(follow-me), 객체 찾기(find-object), 메모리. 설정 가이드: docs/codex-setup.md.
• Hermes Agent — MCP 클라이언트 지원을 갖춘 모델 비종속 에이전트 게이트웨이입니다 (OpenRouter, Ollama, 200개 이상의 제공업체). Codex와 동일한 MCP 서버를 사용합니다: agenticros hermes setup은 ~/.hermes/config.yaml을 작성합니다. 설정 가이드: docs/hermes-setup.md.
• Google Antigravity CLI (agy) — 동일한 MCP 서버를 사용하며, Antigravity 구독을 활용합니다 (GEMINI_API_KEY 필요 없음). agenticros agy setup은 ~/.gemini/config/mcp_config.json을 작성하고 AgenticROS 스킬을 설치합니다. 프롬프트를 실행하려면 agenticros agy run을 사용합니다. 설정 가이드: docs/agy-setup.md.
• Google Gemini — 동일한 ROS 2 도구에 대해 Gemini 함수 호출을 사용하는 독립형 CLI입니다 (MCP 필요 없음). 스크립팅 및 헤드리스 에이전트에 이상적입니다. 이 경로는 GEMINI_API_KEY가 필요합니다. Antigravity CLI는 위에서 언급된 구독 경로입니다.

AgenticROS는 새로운 어댑터(LangGraph, OpenAI, 로컬 모델, 음성 스택 등)를 ROS 2 계층을 건드리지 않고 추가할 수 있도록 구축되었습니다. 핵심 전송 및 도구 계약은 플랫폼에 구애받지 않으며, 어댑터는 이러한 도구를 각 에이전트 런타임으로 노출하는 얇은 심(thin shims) 역할을 합니다.

로컬 VLM (Ollama) — 클라우드 API 불필요

OpenAI 또는 기타 클라우드 API 대신 **로컬 비전-언어 모델(local vision-language model)**을 사용하여 로봇을 제어할 수 있습니다. AgenticROS 로봇 도구는 동일하게 작동하며, 사용자의 기기에서 Ollama를 향해 OpenClaw나 Hermes를 지정하기만 하면 됩니다.

ollama pull qwen3-vl:8b-instruct   # 권장: 채팅 + 도구 + 카메라 비전
# 또는: ollama pull qwen3-vl:2b     # 더 작은 하드웨어용

...

그런 다음 OpenClaw 웹 UI나 Hermes에서 "ROS 토픽 목록을 나열해 줘", "천천히 앞으로 이동해 줘", *"무엇이 보여?"*와 같이 채팅할 수 있습니다.

아키텍처 (Architecture)

• Core (packages/core): 플랫폼에 구애받지 않는 ROS2 전송(Zenoh, rosbridge, 로컬 DDS, WebRTC), 기능/임무 런타임, 공유 메모리, 구성 스키마 및 타입. 특정 AI 플랫폼에 의존하지 않습니다.
• 어댑터 (Adapters): OpenClaw 플러그인 (packages/agenticros, NemoClaw 포함); Claude Code / Desktop / Dispatch, Codex CLI, Hermes Agent, 및 Antigravity CLI (agy)를 위한 MCP 서버 (packages/agenticros-claude-code), 함수 호출을 통한 Gemini API CLI (packages/agenticros-gemini). packages/agenticros-claude-code/README.md, docs/codex-setup.md, docs/hermes-setup.md, 및 docs/agy-setup.md를 참조하십시오.
• 지각 (Perception): 모든 어댑터가 공유하는 @agenticros/ros-camera (이미지 / CompressedImage 스냅샷)와 @agenticros/object-detection (YOLOv8n find-object).

User (메시징 앱) → OpenClaw Gateway → AgenticROS OpenClaw 플러그인 → Core → ROS2 로봇
Claude (코드 / 데스크톱 / 디스패치) → agenticros MCP 서버 → Core → ROS2 로봇 (Zenoh/rosbridge)
Codex CLI → agenticros MCP 서버 → Core → ROS2 로봇 (Zenoh/rosbridge)
...

로봇을 위한 공통 임무 언어

모든 어댑터(Claude Code, Codex, Hermes, Antigravity CLI, Gemini, OpenClaw)에서 동일한 도구 인터페이스를 제공합니다. 따라서 두 개의 다른 에이전트가 서로 다른 스택에 있더라도 같은 로봇을 제어할 때 동일한 방언을 구사할 수 있습니다. 이는 다섯 가지 기능(capability)을 중심으로 구축되었습니다.

기능 명세서 (Capability manifests) — 로봇은 동사를 광고합니다

AgenticROS가 활성화된 모든 로봇은 ros2_list_capabilities를 통해 타입이 지정된 이름의 동사 목록(typed list of named verbs)을 노출합니다: drive_base, take_snapshot, measure_depth, find_object, follow_person, 그리고 스킬 패키지가 기여하는 모든 것들입니다. 에이전트는 원시 ROS 2 토픽(raw ROS 2 topics) 대신 동사(verbs)를 기반으로 계획을 세우며, 이 명세서는 ACP/A2A 에이전트 카드 역할도 겸하도록 설계되었습니다.

임무 체인 연결 (Mission chaining) — run_mission

하나의 MCP 도구인 run_mission은 선언적 단계 그래프(declarative step graph)를 실행합니다. 각 단계는 { id, capability, inputs, on_fail }로 구성됩니다. 어떤 단계에서 나온 출력물은 {{stepId.outputs.field}} 템플릿 참조를 통해 후속 단계로 흐르므로, 감지된 결과가 다음 동작 명령으로 아무런 연결 코드(glue code) 없이 바로 이어집니다:

{
  "steps": [
    { "id": "find",     "capability": "find_object", "inputs": { "target": "chair" } },
...

자연어 목표 (Natural-language goals)

run_mission은 또한 goal 필드를 받아들입니다. 이는 일반 영어(plain English)로 작성됩니다. @agenticros/core의 규칙 기반 결정론적 플래너(rule-based, deterministic planner)는 이를 로봇의 기능 레지스트리(capability registry)를 대상으로 실행 가능한 임무로 컴파일합니다:

• `

LLM 의존성이 없고(플래너는 수백 줄의 패턴 매칭으로 구성되므로 런타임에 Ollama가 필요하지 않음) 꾸며낸 호출도 없습니다(등록소에 실제로 존재하는 기능만 방출함). 컴파일 불가능한 목표를 입력하면 인식된 동사 목록과 함께 깨끗한 오류를 반환하여 에이전트가 스스로 수정할 수 있습니다.

다중 로봇 군집 (Multi-robot fleets)

ros2_list_robots, ros2_discover_robots, 그리고 ros2_find_robots_for({ capability, kind?, online? })를 사용하면 에이전트가 "follow_person 기능을 수행할 수 있고 현재 온라인 상태인 AMR을 찾아줘"와 같이 요청하고 순위가 매겨진 목록을 받을 수 있습니다. 이 CLI는 JSON을 수동으로 편집하지 않고도 군집 메타데이터를 동기화합니다:

agenticros robots add my-amr \
  --kind=amr --sensors=has_realsense,!has_arm \
  --capabilities=drive_base,take_snapshot,follow_person

ROS 측면에서는 모든 로봇이 <ns>/agenticros/robot_info에 대해 1 Hz의 하트비트를 게시하여 온라인 필터가 실제로 도달 가능한 상태를 반영하도록 합니다. 단일 임무는 서로 다른 로봇에게 서로 다른 단계를 라우팅할 수 있습니다. 즉, "AMR이 상자를 찾고, 팔(arm)이 그것을 집어 올리는" 과정이 하나의 임무로 실행됩니다.

취소 및 공유 트랜스크립트 (Cancel + shared transcripts)

mission_cancel({ mission_id })는 진행 중인 취소 토큰을 플립합니다. 러너(runner)는 다음 단계 경계에서 멈추고 남아있는 단계를 cancelled로 표시합니다. 공유 메모리 백엔드가 활성화된 경우, 모든 단계는 장기 메모리의 mission:<id>에 기록되며, 여기에 step:<status>와 capability:<id> 태그가 붙습니다. 다른 에이전트(다른 프로세스, 다른 공급업체)는 나중에 memory_recall을 수행하여 정확히 무슨 일이 일어났는지 재구성할 수 있으므로, 두 에이전트가 임무를 협업하거나 인계할 수 있습니다.

사용 방법: 단계별 군집 설정, 선언적 계획(declarative plans), 자연어 목표(NL goals), 취소 및 인계 — docs/missions.md. 실행 가능한 워크스루: examples/find-and-approach/README.md.

전체 아키텍처 및 설계 트레이드오프(design trade-offs): docs/strategy-ai-agents-plus-ros.md.

저장소 레이아웃 (Repository layout)

packages/core — Transport, types, config (Zod). 모든 어댑터에서 사용됩니다.
packages/agenticros — OpenClaw 플러그인: 도구(tools), 명령어(commands), 설정 페이지(config page), 원격 조종 경로(teleop routes).
packages/agenticros-claude-code — Claude Code용 MCP 서버, Claude desktop / Dispatch, Codex, Hermes, 그리고 Antigravity CLI용 (도구 전용; 설정 UI 없음).
packages/agenticros-gemini — Gemini API CLI (함수 호출(function calling); GEMINI_API_KEY 필요). Antigravity CLI와 분리되어 있습니다.
packages/robot-eyes — 로봇 본체 얼굴 디스플레이 (agenticros eyes): 애니메이션 눈이 cmd_vel 회전 방향을 따라가며; 유휴 상태일 때는 YOLO가 이미 설치된 경우 RealSense 카메라로 사람을 추적합니다. 선택 사항으로 WASD를 사용할 수 있습니다. docs/eyes.md 참조.
ros2_ws/ — ROS2 작업 공간: agenticros_msgs, agenticros_bringup (Gazebo + RViz + rosbridge 실행), agenticros_discovery, agenticros_agent, agenticros_follow_me.
docs/ — 아키텍처, 하드웨어 시작하기, 스킬(skills), 로봇 설정, Zenoh (npx zenoh-fleet을 Mode D 플릿에 사용), 원격 조종(teleop), 눈(eyes), 로컬 VLM / Ollama.
scripts/ — 작업 공간 설정, 게이트웨이 플러그인 설정, 데모 실행.
docker/ — ROS2 + 플러그인 이미지를 위한 Docker Compose 및 Dockerfile.
examples/ — 예제 프로젝트들.

설치

단 하나의 명령어만 필요합니다. agenticros CLI가 나머지 모든 것을 처리합니다 —
ROS 2 작업 공간 설치, MCP 서버 빌드, OpenClaw 플러그인 등록, 로봇 설정을 연결하는 것까지 모두 합니다.

npx agenticros

끝입니다. Node ≥ 20이 설치된 모든 기기에서 실행할 수 있으며, git clone은 필요 없습니다.
만약 아직 모터와 카메라를 배선하는 중이라면, 먼저 이것부터 하세요: docs/hardware.md.
첫 실행 시 대화형 메뉴가 시작됩니다:

╔──────────────────────────────────────────────────╗
║  AgenticROS - ROS 기반 로봇을 위한 에이전트 AI  ║
╚──────────────────────────────────────────────────╝
...

Pick **최초 설정(First-time setup)**을 한 번만 수행하세요 (작업 공간 + OpenClaw 플러그인 + 선택적 Codex MCP + 선택적 API 키, 모두 idempotent). **OpenAI 대신 로컬 Ollama를 사용하나요?** API 키 단계는 건너뛰세요 — **[로컬 VLM (Ollama)](#local-vlm-ollama--no-cloud-api-required)**을 참조하세요. 그런 다음 원하는 실행 방식을 선택하세요:

| ... | 선택 | 
|---|---|
| **실제 로봇**을 구동하고 싶다면 (RealSense + 모터 + MCP) | **실제 로봇으로 시작(Launch with real robot)** |
| ... | 
Once a stack is up, point any of the supported agents — OpenClaw, Claude Code, OpenAI Codex, Hermes Agent, Antigravity CLI, Claude Desktop / Dispatch, 또는 Gemini CLI — at the same robot and start talking to it. The CLI tracks what it spawned (pidfiles + logs under `/tmp/agenticros-*`), so **Stop everything** cleanly tears the demo down.

스크립트화된 호출을 선호하나요? 모든 메뉴 항목은 직접적인 명령에 매핑됩니다: