FloofClaw: 내구성 있는 AI 에이전트를 위한 작은 C 런타임

FloofClaw는 내구성 있는(durable) AI 에이전트를 위한 작은 C 런타임입니다. 이 런타임은 메시지, 타이머, API 호출 및 워커 결과를 검사 가능한 이벤트 기반 실행으로 변환하며, 재시작에도 살아남아 작업할 내용이 없을 때까지 계속됩니다.

~560 KiB의 모든 어댑터 최적화 코어 · C11 · 내구성 있는 파일 시스템 상태 · 기본 JSON/JSONL · macOS, Linux 및 Android ARM64 지원

오프라인 경로는 C11 컴파일러, make, 그리고 POSIX 사용자 영역(userland)이 필요합니다. 이는 커밋된 목업 기반의 hello floop을 사용하므로 계정, API 키, 게이트웨이 또는 네트워크 연결이 필요 없습니다.

git clone https://github.com/FloofLogic/Floofclaw.git
cd Floofclaw
make -j4
...

v0.30.0부터는 태그가 지정된 릴리스에 네이티브 macOS arm64 아카이브가 포함되며, Linux 빌드는 몇 초 만에 소스에서 가능합니다. 사전 구축된 바이너리(Prebuilt binaries)를 확인하세요.

항상 켜져 있는 로컬 런타임을 시작하고 다른 터미널에서 접속할 수 있습니다:

./bin/fclaw gateway start -h
./bin/fclaw -i -h

나중에 ./bin/fclaw gateway stop -h로 중지하세요.

.

실제 모델을 사용할 준비가 되었나요? 안내 경로(guided path)는 온보딩 마법사입니다:

./scripts/onboard.sh

이 스크립트는 정체성, 제공업체 키(provider key), floop, 채널, 번들된 액션 활성화 체크리스트(각 액션은 켜지기 전에 실시간으로 검증됨), 그리고 게이트웨이 상태 프로브를 안내합니다. bash와 bin/fclaw만 필요합니다. 재실행해도 안전하며, 기존 답변을 유지하고 복구합니다.

수동으로 진행하는 것을 선호하나요? 셸 히스토리에 저장하지 않고 키를 저장할 수 있습니다. 예를 들어, ./bin/fclaw auth set-stdin -h gemini_key를 사용한 후, 제공업체 가이드를 따라 제공업체 기반 floop과 프로필을 선택하세요.

선택적 구성 요소(Optional components)

libcurl은 실제 HTTP 제공업체를 활성화하며, OpenSSL 3은 TLS 채널을 활성화합니다. 일부 선택적 액션 및 로컬 검사 앱은 python3, jq 또는 curl을 사용하지만, 이들 중 어느 것도 C 런타타임 아래에 위치하지는 않습니다.

공개 소스 릴리스에는 고정된(pinned) pluck 소스가 일반 파일로 포함됩니다. web_read 액션을 원하는 개발 체크아웃은 공개 소스를 초기화하고 다음 명령어로 빌드할 수 있습니다:

git submodule update --init actions/common/web_read/_pluck
bash actions/common/web_read/build.sh

참고

FloofClaw는 또 다른 챗봇 프레임워크가 아닙니다. 이는 에이전트의 작업이 재시작 후에도 유지되고, 경제적이며, 시간이 지나도 책임질 수 있도록 작동하는 내부 엔진입니다.

이 엔진은 완전히 C 언어로 처음부터 작성되었습니다. Node, Python, JVM, 프레임워크 또는 언어 런타임이 그 아래에 존재하지 않습니다. 패키지 매니저와 연결된 make release-small 소스 빌드는 약 560 KiB이며, 다운로드 가능한 macOS 아카이브는 OpenSSL을 포함하기 때문에 약 4.34 MiB입니다. 둘 다 macOS 시스템 libcurl을 사용합니다. 목업 전용 빌드(make MOCK_ONLY=1)는 두 라이브러리를 생략할 수 있습니다.

PostgreSQL, SQLite, Redis 또는 벡터 데이터베이스가 없습니다. 파일시스템이 내구성 있는 기반(substrate)입니다: append-only 이벤트 로그가 진실이며, 상태 파일은 재구축 가능한 투영(projection)이고, 실행은 충돌 후에도 재생될 수 있습니다.

모든 공개 명령어는 기본적으로 구조화된 JSON 또는 JSONL을 사용합니다. 전체 런타임은 에이전트, 셸 스크립트 및 자동화에 의해 직접 조합(composable)됩니다. 사람이 읽기 쉬운 출력은 여전히 하나의 플래그만 거리에 있지만, 기계는 사후 고려 사항이 아니라 연산자(operator)로 취급됩니다.

fclaw view -a <run_id> # 에이전트를 위한 압축된 JSONL
fclaw view -h <run_id> # 사람을 위한 형식화된 출력

모든 요청, 응답, 토큰 기록, 캐시 경계, 액션 호출, 이벤트 및 stderr 아티팩트는 검사 가능합니다. 불투명한 “에이전트 턴”을 진실로 취급하지 않고도 실행을 확인하고, 재생하고, 비용을 계산하며, 추적할 수 있습니다.

2026-09-04 날짜의 arm64 macOS 환경에서 Apple clang 17을 사용한 측정 결과입니다. 바이너리는 scripts/build_binary_archive.sh에 의해 생성된 스트립(stripped)된 release-small 아티팩트이며, 정적 OpenSSL과 시스템 libcurl, 그리고 네 가지 어댑터(discord irc telegram ws)를 포함하고 있으며, 기본 -O2 개발 빌드는 아닙니다. 테이블을 재현하려면 아카이브 빌드 직후 ./scripts/metrics.sh를 실행하십시오. 이 출력은 빌드 프로필, 어댑터 세트 및 개정판(revision)을 명시합니다.

A floop은 순서가 지정되고 이벤트에 의해 제어되는 단계들의 선언적 프로필입니다. C 커널은 이 프로필을 따라 이동하며, 엔벨로프를 검증하고, 작업을 실행하고, 이벤트를 추가하며, 결과를 기다립니다. 제품의 동작 방식은 floops, 에이전트 패킷, 그리고 액션 계약에 남아 있으며, 커널 자체는 판단자가 아닌 이동자(walker)로 남습니다.

floops/ 배포 가능한 루프 + 에이전트 번들
actions/ 선언된 기능 및 효과 경계
runtime/ 작은 C 커널
...

모든 트리거링 이벤트는 실행 디렉터리를 생성합니다:

workspace/runs/<run_id>/ 
├── event_log.jsonl # 행동의 진실 (behavioral truth)
├── runstate.json # 내구성 있는 스케줄러 엔벨로프
...

명령줄은 동일한 증거를 직접 노출합니다:

./bin/fclaw view -a <run_id>
./bin/fclaw replay -a workspace/runs/<run_id>/event_log.jsonl
./bin/fclaw usage -a
...

실행(run)에는 재시도, 여러 LLM 기반 단계, 또는 압축이 포함될 수 있습니다. 정확한 모델 호출 사용량을 확인하려면 provider_calls/*_meta.json 또는 사용량 원장(usage ledger)을 세어보십시오—실행 디렉터리가 아닙니다. fclaw usage -a는 config/pricing.json에 있는 날짜별 가정(dated assumptions)으로부터 현재의 원장 세그먼트 가격을 책정하고, 제공자/모델 쌍이 목록에 없는 경우 불완전한 추정치를 표시합니다.

./bin/fclaw run -h --floop openclaw --text

action을 actions/ 디렉터리로 복사 → restart → fclaw actions -h
native adapter를 adapters/ 디렉터리로 복사 → make → restart → fclaw adapters -h
floop을 floops/ 디렉터리로 복사 → select and run → fclaw floops -h

C로 작성되어 동일한 실행 파일에 연결되기 때문에 native adapter만 재빌드가 필요합니다. 확장 가이드부터 시작하세요.

`mcpServers`를 붙여넣으세요.

Claude Desktop 또는 Claude Code용으로 이미 가지고 있는 `config/mcp.json`의 맵을 여기에 넣고 동기화를 실행하세요:

`./bin/fclaw mcp sync -h # tools/list → 하나의 도구당 하나의 액션 → restart`

FloofClaw는 MCP 클라이언트를 임베드하는 대신 서버 카탈로그에서 액션을 *생성*하므로, 각 도구는 일반적인 액션으로 도착합니다. 따라서 에이전트 허용 목록(agent allowlists), `force_disable`, 시간 초과(timeouts), 그리고 호출별 아티팩트(per-call artifacts)가 모두 적용되며, 바이너리에는 프로토콜 코드가 포함되어 있지 않습니다. MCP 서버에 대해 확인하세요.

Discord에서 이미지, PDF 또는 파일을 드롭하거나—또는 Telegram에서 선택적 캡션이 있는 사진이나 문서를 보내면—텍스트와 동일한 `user_message` 경로로 모델에 도달합니다. Discord는 최대 10개의 첨부 파일(각 25 MiB)과 메시지당 50 MiB를 허용하며, Telegram의 Bot API 다운로드 경로는 파일당 20 MiB로 제한됩니다. 바이트는 게이트웨이에서가 아니라 항상 인증된 채널 자체 파일 호스트 내부의 제한된 모델 자식(bounded model child) 내에서만 가져와지며 그 외의 곳에서는 가져와지지 않습니다. 서명되거나 토큰을 지닌 URL은 어떤 버스, 게이트웨이 로그 또는 실행 아티팩트도 반복하지 않는 비공개 콘텐츠 주소 지정형 매니페스트에 존재합니다. 모델이 이들을 가지고 무엇을 할 수 있는지는 제공업체의 호출에 달려 있습니다—Gemini 프로필은 이미지, PDF, 오디오 및 비디오를 처리하며; OpenAI 스타일의 프로필은 이미지를 처리합니다. Discord 미디어와 Telegram 미디어를 확인하세요.

FloofClaw는 macOS, Linux, 그리고 Android ARM64용으로 빌드됩니다. Android는 APK 라이브러리나 앱별 래퍼가 아닌 동일한 CLI 실행 파일을 생성합니다.

`ANDROID_NDK_ROOT="$ANDROID_HOME/ndk/27.0.12077973" \
FCLAW_ANDROID_DEPS_ROOT=/path/to/android-arm64-static-deps \
make android-arm64`

종속성 레이아웃, API 선택 및 장치 스모크 명령어는 Android ARM64 빌드 가이드를 참조하세요.

`make test`

루틴 오프라인 게이트는 약 1분 만에 49개의 단위 테스트(unit tests), 203개의 통합 테스트(integration tests), 피처 격리(fixture isolation), 로컬 클라이언트 생명 주기 프로브(local-client lifecycle probe), 그리고 목업 제공자 응답을 사용한 hermetic smoke을 실행합니다. `make test-full`

재빌드 및 기능 선택 계약(feature-selection contracts)을 추가하며, 릴리스 검사에서 이를 자동으로 실행합니다. 메이저 버전 릴리스 준비에는 `make robustness`를 통해 ASan, UBSan, small-stack, fuzz, chaos, disk-full/read-only, 그리고 thrash 캠페인이 추가됩니다.

이러한 주장들의 재현 가능한 히스토리(reproducible history)는 Testing investment에서 읽어보세요.

- FloofClaw란 무엇인가?
- 아키텍처
- CLI 출력 계약
- 제공자들(Providers)
- Discord
- Telegram
- MCP 서버들
- Floops
- 액션들(Actions)
- 철학(Philosophy)

FloofClaw는 Apache License 2.0 하에 오픈 소스로 공개되었습니다. 상업적 및 비상업적 사용, 수정 및 배포가 해당 약관에 따라 허용됩니다.