ZeroClaw

시작 전 준비

ZeroClaw의 모델 연결 설정인 provider에 AI 게이트웨이 주소, API 키와 사용할 모델 코드를 등록합니다. 에이전트는 이 provider를 참조해 모델을 호출하고, risk profile은 도구를 실행할 때 승인을 받을 기준을 정합니다. 에이전트를 실행하려면 세 설정을 모두 연결해야 합니다.

• AI 게이트웨이 API 키

  현재 사용할 수 있는 AI 게이트웨이 API 키를 준비합니다.

• 모델 코드

  에셋에 표시된 정확한 코드를 확인합니다.

• ZeroClaw

  로컬 환경에 ZeroClaw를 설치합니다.

brew install zeroclaw

공통 기본 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에 평문으로 쓰지 않고 키 입력란에서 입력 내용을 숨기는 방식으로 저장합니다. 값 인수를 생략하면 터미널에 키가 노출되지 않으며 ZeroClaw의 암호화된 인증 정보 저장소에 보관됩니다.

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

이 custom provider 연결에는 native_tools를 별도로 설정하지 않습니다.

에이전트 연결

model_provider에는 앞에서 등록한 모델 연결을, risk_profile에는 다음 단계에서 정의할 도구 승인 설정을 지정합니다.

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

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

risk profile 연결

아래 예시는 승인 방식으로 supervised를 선택하고, 파일 읽기와 검색 도구를 자동 승인 목록에 등록합니다. 작업별 승인 여부는 이 설정에 따라 ZeroClaw가 판단합니다.

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

연결 확인

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

zeroclaw agent -a letsur -m "ping"

모델 응답이 출력되면 지정한 에이전트가 게이트웨이를 통해 모델을 호출한 것입니다. 이 확인은 텍스트 응답 기준이며, 도구 실행과 승인 동작은 실제로 사용할 도구로 별도 확인합니다.

지원 범위와 제약

작업 폴더

에이전트별로 분리됩니다. ~/.zeroclaw/agents/<별칭>/workspace 안의 파일만 도구가 읽고 씁니다.

비용 표시

provider에 pricing을 설정하지 않으면 ZeroClaw는 토큰 사용량만 기록하고 비용은 unknown으로 처리합니다. AI 게이트웨이의 누적 사용량과 호출 수는 분석, 호출별 비용과 월별 비용의 확인 경로는 요금 및 사용량 안내에서 확인합니다.

승인

supervised에서는 낮은 위험 작업만 바로 실행하고 중간 위험 작업은 승인을 요청하며 높은 위험 작업은 차단합니다. 승인을 받을 수 없는 비대화형 실행에서는 승인 요청이 거부될 수 있으므로 필요한 도구만 auto_approve에 둡니다.

문제 해결

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