ZeroClaw 연동

ZeroClaw 에이전트의 모델 요청을 Letsur 게이트웨이로 보내세요.

custom provider, 에이전트, 승인 정책, secret 저장과 연결 복구를 다룹니다.

시작 전 준비

ZeroClaw는 OpenAI 호환 endpoint를 custom provider 슬롯으로 등록합니다. provider 항목만으로는 동작하지 않고, 그 provider를 참조하는 에이전트와 risk profile을 함께 정의해야 합니다.

AI 게이트웨이 API 키
현재 사용할 수 있는 AI 게이트웨이 API 키를 준비합니다.
모델 코드
에셋에 표시된 정확한 코드를 확인합니다.
ZeroClaw
로컬 환경에 ZeroClaw를 설치합니다.


brew install zeroclaw

공통 base URL과 키 형식은 외부 도구 연동에서 비교합니다.

연결 설정

provider 등록

~/.zeroclaw/config.toml에 작성합니다.


schema_version = 3
 
[providers.models.custom.letsur]
uri = "https://gw.letsur.ai/v1"     # custom 슬롯은 uri 가 필수입니다
model = "<MODEL_CODE>"              # 에셋의 정확한 모델 코드

키는 config.toml에 평문으로 쓰지 않고 secret field의 masked 입력으로 저장합니다. 값 인수를 생략하면 터미널에 키가 노출되지 않으며 ZeroClaw의 암호화된 secret store에 보관됩니다.


zeroclaw config set providers.models.custom.letsur.api_key

native_tools는 provider 기본 동작을 강제로 덮어쓰는 고급 옵션입니다. 현재 ZeroClaw 공식 문서는 이 값이 Groq factory에서만 사용된다고 명시하므로, custom provider 연결에는 별도로 설정하지 않습니다.

에이전트 연결


[agents.letsur]
model_provider = "custom.letsur"    # <슬롯>.<별칭>
risk_profile = "default"

custom.letsur의 letsur는 직접 정하는 별칭입니다. [agents.<별칭>]의 model_provider가 이 이름을 그대로 참조합니다.

risk profile 연결


[risk_profiles.default]
level = "supervised"
auto_approve = ["file_read", "glob_search", "content_search"]

연결 확인

에이전트 별칭은 생략할 수 없습니다. 기본 에이전트가 없어 -a가 항상 필요합니다.


zeroclaw agent -a letsur -m "ping"

모델 응답이 출력되면 provider, 에이전트와 risk profile이 연결된 것입니다.

지원 범위와 제약

항목	내용
작업 폴더	에이전트별로 분리됩니다. `~/.zeroclaw/agents/<별칭>/workspace` 안의 파일만 도구가 읽고 씁니다
비용 표시	provider에 `pricing`을 설정하지 않으면 ZeroClaw는 토큰 사용량만 기록하고 비용은 `unknown`으로 처리합니다. 실제 누적 사용량과 비용은 분석에서 확인합니다
승인	`supervised`에서는 낮은 위험 작업만 바로 실행하고 중간 위험 작업은 승인을 요청하며 높은 위험 작업은 차단합니다. 승인 backchannel이 없는 비대화형 실행에서는 승인 요청이 거부될 수 있으므로 필요한 도구만 `auto_approve`에 둡니다

문제 해결

증상	먼저 확인할 것
에이전트를 찾지 못합니다	`-a letsur` 값이 `[agents.letsur]`의 별칭과 같은지 확인합니다
provider 요청이 실패합니다	`uri`가 `https://gw.letsur.ai/v1`인지 확인하고, `zeroclaw config list --secrets --filter providers.models.custom.letsur`로 credential이 저장됐는지 확인합니다
도구 실행이 승인 단계에서 멈춥니다	`risk_profile`의 `level`, `auto_approve`, `always_ask`를 확인합니다
모델을 찾지 못합니다	`model`에 에셋의 정확한 모델 코드를 사용했는지 확인합니다

설정 기준: ZeroClaw custom providers , provider credentials , CLI reference , Security model 에서 provider schema, secret 저장, 필수 agent 별칭, workspace, 승인 정책을 2026년 8월 7일에 확인했습니다.