ZeroClaw
게이트웨이 모델로 에이전트 실행하기
Chat Completions를 사용하는 provider, 인증 정보와 에이전트 및 승인 설정을 연결하고, 응답과 도구 동작을 확인하는 방법을 안내합니다.
페이지 목차
시작 전 준비
설정을 마치면 ZeroClaw 에이전트가 AI 게이트웨이를 거쳐 모델을 호출하고, 도구를 실행할 때는 설정한 승인 기준을 따릅니다. 예제의 custom provider는 Chat Completions를 사용합니다.
- AI 게이트웨이 API 키
현재 사용할 수 있는 AI 게이트웨이 API 키를 준비합니다.
- 모델 코드
에셋에서 Chat Completions를 지원하는 모델의 정확한 코드를 확인합니다. 아래 custom provider 예제는 이 API 형식을 사용합니다.
- ZeroClaw
로컬 환경에 ZeroClaw를 설치합니다.
Homebrew를 사용하는 환경에서는 다음 명령으로 설치합니다. 다른 환경의 설치 방법은 ZeroClaw 공식 문서 를 확인하세요.
brew install zeroclaw아래 설정은 CLI의 기본 설정 위치인 ~/.zeroclaw/ 기준입니다. Homebrew로 설치한 ZeroClaw를 brew services로 실행하면 서비스는 $HOMEBREW_PREFIX/var/zeroclaw/의 설정을 읽으므로, 이 경우 설정 파일 위치를 서비스와 맞춥니다.
ZeroClaw에 넣을 값은 아래 단계에 모두 있습니다. API 형식별 기본 URL과 인증 헤더 전체는 인증과 기본 URL에 정리돼 있습니다.
연결 설정
ZeroClaw에서 에이전트를 실행하려면 다음 세 설정을 연결합니다.
| 설정 | 역할 |
|---|---|
| provider | AI 게이트웨이 주소, API 키와 사용할 모델 코드로 모델 연결을 정의합니다. |
| 에이전트 | 등록한 provider를 참조해 모델을 호출합니다. |
| risk profile | 도구를 실행할 때 승인을 받을 기준을 정합니다. |
provider 등록하기
~/.zeroclaw/config.toml에 다음 내용을 작성합니다. 파일을 직접 작성할 때는 첫 줄에schema_version = 4를 지정합니다.schema_version = 4 [providers.models.custom.letsur] uri = "https://gw.letsur.ai/v1" # custom 슬롯에는 uri 필수 model = "<MODEL_CODE>" # 에셋의 정확한 모델 코드uri에는/v1까지 포함한 게이트웨이 기본 URL을 넣습니다.custom슬롯은 기본으로 Chat Completions 형식을 사용하므로wire_api를 지정하지 않습니다. 이 custom provider 연결에는native_tools도 별도로 설정하지 않습니다.API 키 저장하기
API 키를config.toml에 평문으로 저장하지 마세요ZeroClaw는 아래 명령으로 저장한 키를 암호화합니다. 암호화에 쓰는 키는 설정 파일 옆의
.secret_key에 있으니 이 파일을 버전 관리에 넣지 마세요.다음 명령을 키 값 인수 없이 실행하면 ZeroClaw가 숨김 입력으로 키를 받아 암호화해 저장합니다.
zeroclaw config set providers.models.custom.letsur.api_key에이전트 연결하기
model_provider에는 앞에서 등록한 모델 연결을,risk_profile에는 다음 단계에서 정의할 도구 승인 설정을 지정합니다.[agents.letsur] model_provider = "custom.letsur" # <슬롯>.<별칭> risk_profile = "default"custom.letsur의letsur는 사용자가 지정하는 별칭입니다.[agents.<별칭>]의model_provider가 이 이름을 그대로 참조합니다. 별칭에는 영문 소문자, 숫자와 밑줄만 사용하며 하이픈은 사용할 수 없습니다.도구 승인 기준 연결하기
아래 예시에서는 승인 방식을
supervised로 지정하고, 파일 읽기와 검색 도구를 자동 승인 목록에 등록합니다.supervised에서 ZeroClaw는 낮은 위험 작업만 바로 실행합니다. 중간 위험 작업은 승인을 요청하고, 높은 위험 작업은 차단합니다.[risk_profiles.default] level = "supervised" auto_approve = ["file_read", "glob_search", "content_search"]
모델 선택
모델은 provider 등록하기 단계의 model에 에셋의 정확한 모델 코드로 지정합니다.
연결 확인
먼저 설정 파일을 불러와 검증합니다. 검증에 실패하면 오류가 표준 오류로 출력됩니다.
zeroclaw config listZeroClaw에는 기본 에이전트가 없으므로 -a로 에이전트 별칭을 항상 지정합니다.
zeroclaw agent -a letsur -m "ping"모델 응답이 출력되면 에이전트가 게이트웨이를 거쳐 모델을 호출한 것입니다. 실제 작업에 사용할 도구 호출과 승인 동작은 별도로 확인합니다.
지원 범위와 제약
- 작업 폴더
- 에이전트별로 분리됩니다. 기본 설정에서 도구는
~/.zeroclaw/agents/<별칭>/workspace안의 파일만 읽고 씁니다. - 비용 표시
- provider에
pricing을 설정하지 않으면 ZeroClaw는 토큰 사용량만 기록하고 비용은unknown으로 처리합니다. AI 게이트웨이의 누적 사용량과 호출 수는 분석에서 확인합니다. 호출별 비용과 월별 비용을 어디서 확인하는지는 요금 및 사용량 안내에 정리돼 있습니다. - 승인
- 승인을 받을 수 없는 비대화형 실행에서는 승인 요청이 거부될 수 있으므로 필요한 도구만
auto_approve에 등록합니다. 승인 방식별 동작은 도구 승인 기준 연결하기 단계에서 확인합니다.
문제 해결
| 증상 | 다음 행동 |
|---|---|
| ZeroClaw가 에이전트를 찾지 못합니다 | -a letsur 값이 [agents.letsur]의 별칭과 같은지 확인합니다 |
| provider 요청이 실패합니다 | uri가 https://gw.letsur.ai/v1인지 확인하고, zeroclaw config list --secrets --filter providers.models.custom.letsur로 인증 정보가 저장됐는지 확인합니다 |
401 응답이 반환됩니다 | 키 값과 키 상태(비활성 또는 만료)를 확인합니다 |
| 도구 실행이 승인 단계에서 멈춥니다 | risk_profile의 level, auto_approve, always_ask를 확인합니다 |
| ZeroClaw가 모델을 찾지 못합니다 | model의 값이 에셋의 정확한 모델 코드와 일치하는지 확인합니다 |
그 밖의 오류는 오류 type별 대응에서 확인합니다.
설정 기준: Custom Providers , Provider Configuration , CLI Reference , Config Reference , Security model , Autonomy Levels , Filesystem components , macOS , Operations & Deployment , Environment variables 의 custom provider 키와 기본 wire 형식, schema_version, API 키 저장 방식, 에이전트와 risk profile 키, -a와 -m 옵션, config list 옵션, 설정 파일과 작업 폴더 위치, 별칭 규칙, 승인 수준별 동작, pricing 기본 동작, Homebrew 설치를 2026년 11월 13일에 확인했습니다. 이 확인에는 렛서 게이트웨이와의 실제 연동 시험이 포함되지 않습니다.