여러분이 지금까지 봐온 모든 "하드웨어 기반 AI" 데모의 이면에는 LLM (Large Language Model)이 있습니다. 사용자가 터미널이나 Telegram을 통해 보드와 대화하면, 보드는 API를 호출하여 클라우드 모델이 작업을 수행하도록 합니다. QClaw는 이 구성을 뒤집습니다. Arduino Uno Q가 언어 모델을 호스팅하고, 에이전트 루프 (agent loop)를 실행하며, 컴파일 툴체인 (compile toolchain)을 구동하고, 자신의 마이크로컨트롤러 (microcontroller)에 플래싱 (flashing)까지 수행합니다. QClaw에게 LED 매트릭스에 "QClaw"라는 글자를 스크롤해 달라고 요청하면, 그것을 수행합니다. 엔드 투 엔드 (End to end)로. 보드 위에서. 오프라인으로 말이죠. QClaw는 8개의 도구를 가진 에이전트 인터페이스 (agentic surface), 15개의 기술을 가진 프리 라우터 (pre-router), 그리고 자율적인 업로드를 실제로 실행할 수 있게 만드는 직접적인 OpenOCD 플래시 경로를 갖추고 있습니다. 듀얼 패스 런타임 (dual-path runtime)을 통해 동일한 모델에서 속도 또는 완전한 하드웨어 제어 중 하나를 선택할 수 있습니다.

왜 Uno Q가 이를 위한 적합한 보드인가
Arduino Uno Q는 분리된 실리콘 (split-silicon) 장치입니다. 겉보기에는 클래식한 Arduino처럼 보이지만, 트렌치코트를 입은 두 개의 보드와 같습니다. 즉, MPU (Microprocessor Unit)와 MCU (Microcontroller Unit)가 동일한 PCB를 공유합니다. MPU는 MCU를 리셋 상태로 유지할 수 있으며, linuxgpiod 드라이버를 통해 SWD로 연결된 GPIO 핀을 사용하여 MCU의 플래시를 직접 재프로그래밍할 수 있습니다. 둘 사이의 USB 케이블도 필요 없습니다. 프로브 (probe)도 필요 없습니다. 두 번째 컴퓨터도 필요 없습니다. 이것이 QClaw의 천재성입니다. 에이전트 루프는 MPU가 루프를 구동하고 MCU가 결과물인 펌웨어를 실행하는 Arduino Uno Q의 듀얼 실리콘 토폴로지 (dual-silicon topology) 전반에 걸쳐 전체 스케치 라이프사이클 (sketch lifecycle)을 조율합니다. 이것이 QClaw가 생성, 컴파일, 플래싱 및 관찰을 수행하는 방식입니다. QClaw Arduino 툴은 정확한 주소에서 OpenOCD를 직접 호출합니다. 이 툴은 arduino-cli compile --fqbn arduino:zephyr:unoq --export-binaries 명령으로 컴파일하고, 결과물인 .elf-zsk.bin 파일을 가져와 GPIO SWD 브릿지를 통해 OpenOCD로 파이프라인 연결합니다. SSH도, 네트워크 자격 증명도, 원격 OCD 터널도 필요 없습니다. 그저 동일한 보드 위의 MPU에서 MCU로 전달될 뿐입니다. 바이너리가 디스크에 저장되면 1초 미만 만에 플래싱이 완료됩니다. 4GB의 RAM은 8K 컨텍스트 윈도우 (context window)를 가진 Qwen3.5 0.8B Q4_0 모델을 mlock 처리하고 q8_0 KV 캐시 (KV cache)와 함께 호스팅하기에 충분하고도 남습니다. QClaw는 Uno Q에서 약 1.3GB를 점유하며 작동합니다. 디코딩 (Decode)은 초당 약 8토큰 속도로 실행됩니다.

데스크톱 GPU에 비하면 느리지만, 커피를 다 마시기 전에 스케치 (Sketch)를 컴파일하고 플래싱 (Flashing)할 수 있을 만큼은 충분히 빠릅니다.

• QClaw 사용 방법 *

QClaw는 동일한 llama-server 백엔드, 동일한 SOUL.md, 그리고 동일한 23가지 규칙의 프리라우터 (Pre-router)를 기반으로 두 가지 런타임 (Runtime)을 제공합니다. 이 둘의 차이점은 LLM 호출을 감싸는 방식에 있습니다.

에이전트 방식 (Agentic path) ( make qclaw-agentic ): qclaw Go 게이트웨이가 모델 앞에 위치합니다. 이 게이트웨이는 채널 어댑터 (Channel adapters: 터미널, SSH, Telegram), 다중 반복 에이전트 루프 (Multi-iteration agent loop), 프리라우터, 그리고 8가지 도구 디스패처 (Tool dispatcher)를 실행합니다. 이것이 프로덕션 (Production) 기본 설정입니다. 실제로 스케치를 컴파일하고 플래싱할 수 있는 유일한 경로입니다.

직접 방식 (Direct path) ( make qclaw-direct ): 얇은 Python REPL이 Python에서 동일한 프리라우터 규칙을 실행한 후 llama-server로 직접 POST 요청을 보냅니다. 루프도 없고, 도구도 없으며, Telegram도 없습니다. 프롬프트 (Prompt)에 도구 스키마 (Tool schema)가 포함되지 않고 두 번째 반복이 없기 때문에, 동일한 정확도 기준 순수 사실 기반 프롬프트에서 지연 시간 (Latency)이 약 33% 더 낮습니다. 스케치를 플래싱하거나 프레임을 캡처하고 싶을 때는 에이전트 방식을 사용하세요. Uno Q의 어떤 핀이 PWM을 지원하는지 단순히 묻고 싶을 때는 직접 방식을 사용하세요.

두 개의 명령어를 입력하면 세션이 시작됩니다:

git clone https://github.com/laurenvil/Uno-QClaw.git ~/ArduinoApps/QClaw
cd ~/ArduinoApps/QClaw
git submodule update --init --recursive # 추론 엔진 (Inference engine) 다운로드
cd yzma && make download-llama.cpp && cd ..

모델 다운로드 (~Q4_0 기준 약 490 MB)

mkdir -p ~/models && wget -O ~/models/Qwen_Qwen3.5-0.8B-Q4_0.gguf 'https://huggingface.co/Qwen/Qwen3.5-0.8B-GGUF/resolve/main/Qwen3.5-0.8B-Q4_0.gguf'

빌드, 설치, arduino-cli 설정 (1회 수행)

make qclaw-install

세션 시작 — 경로 선택

make qclaw-agentic # 전체 에이전트 루프 + 8가지 도구 (compile/upload/camera/sysfs_led/network/i2cdetect)
make qclaw-direct # 프리-라우터 (Pre-router) + 직접 API (빠른 질의응답, 도구 미사용)

make qclaw-install은 Go 바이너리를 빌드하고, 시스템 프롬프트와 15가지 기술 트리 (skill tree)를 ~/.qclaw/workspace/로 복사하며, arduino-cli와 arduino:zephyr 코어를 설치합니다. 또한 선택 사항인 Telegram 게이트웨이를 설정하는 대화형 마법사를 실행합니다. 일단 실행되면, 에이전트는 다음과 같이 범위가 좁게 정의된 8가지 도구를 사용할 수 있습니다:

• read_file, write_file, list_dir: 워크스페이스 탐색용
• arduino: OpenOCD를 통한 컴파일 및 플래싱 (flash)
• camera: GStreamer를 통한 단일 프레임 V4L2 캡처
• sysfs_led: /sys/class/leds/*에 위치한 MPU 측 RGB LED 제어
• network: 호스트 이름, 인터페이스, 기본 게이트웨이 확인 (모두 읽기 전용)
• stdlib Go: Go 표준 라이브러리
• i2cdetect: -y -r 옵션만을 사용하여 Linux I²C 버스를 나열 및 스캔

일반적인 exec나 일반적인 쉘 (shell)은 허용되지 않습니다. 모든 도구는 허용 목록 (allow-list)을 기준으로 인자를 검증합니다. 전체 도구 스키마 (tool schema)는 약 3.4K 자이며, 이는 8K 컨텍스트 윈도우 (context window) 내에서 시스템 프롬프트를 위한 충분한 공간을 남겨둡니다.

프리-라우터 (Pre-Router): RAG가 아닌 기술 (Skills)

프리-라우터는 0.8B 모델에서 힘든 작업을 수행하는 QClaw의 핵심 부분입니다. 이것은 RAG (검색 증강 생성)가 아닙니다. 15가지 기술에 걸쳐 23개의 키워드 정규 표현식 (regex) 규칙으로 구성된 평면 테이블 (flat table)입니다. 메시지를 보내면 프리-라우터가 이를 스캔하여 일치하는 규칙을 찾고, LLM 호출 전에 관련 SKILL.md와 참조된 파일들을 시스템 프롬프트에 직접 인라인 (inline)으로 삽입합니다. 모델은 표준 기술 콘텐츠를 위해 read_file을 호출할 필요가 없습니다. 콘텐츠가 이미 그곳에 있기 때문입니다. 0.8B 규모에서 read_file 호출은 전체 LLM 반복 (iteration) 비용을 발생시키며, 이는 대략 10~20분의 콜드 프리필 (cold prefill) 및 디코딩 (decode) 시간을 소모합니다. 프리-라우터는 이 비용을 0으로 분할 상환 (amortize)합니다.

• 기술 범위: * 스케치 (Sketch) 기초: blink, breathe, button, potentiometer, servo, 컴파일 및 업로드 (compile and upload), CAN bus, DAC, OPAMP
• 표준 Arduino_LED_Matrix 템플릿을 사용하는 13x8 LED 매트릭스
• Uno Q 하드웨어: 핀 테이블 (pin tables), 전압 규칙 (voltage rules), 커넥터 (connectors), 전원 (power)
• 듀얼 칩 워크플로우 (Dual-chip workflow): Bridge RPC, App Lab, Bricks
• Linux 측 기능: Wi-Fi, Bluetooth, 카메라 (camera), OpenCV, 마이크 (microphone), sysfs LEDs
• 플러그 앤 플레이 (Plug-and-play) Modulino 센서
  각 기술은 workspace/skills/<name>/ 아래의 디렉토리이며, SKILL.md와 선택적인 참조 파일들로 구성됩니다. 새로운 기술을 추가하는 것은 마크다운 (markdown)을 작성하고 정규 표현식 (regex) 규칙을 추가하는 것만으로 충분합니다.
• 직접 시도해보기
• 저장소 (Repo): https://github.com/laurenvil/Uno-QClaw
  이슈 (Issues), 포크 (forks), 풀 리퀘스트 (pull requests)는 https://github.com/laurenvil/Uno-QClaw 에서 환영합니다. 만약 당신의 책상 위에 Arduino Uno Q가 있다면, 이더넷 케이블을 뽑은 상태에서도 오늘 밤 바로 스스로 플래싱 (self-flashing)하는 AI 어시스턴트를 올려둘 수 있습니다.