본문으로 건너뛰기

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에서 에이전트를 실행하려면 다음 세 설정을 연결합니다.

설정역할
providerAI 게이트웨이 주소, API 키와 사용할 모델 코드로 모델 연결을 정의합니다.
에이전트등록한 provider를 참조해 모델을 호출합니다.
risk profile도구를 실행할 때 승인을 받을 기준을 정합니다.
  1. 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도 별도로 설정하지 않습니다.

  2. API 키 저장하기

    API 키를 config.toml에 평문으로 저장하지 마세요

    ZeroClaw는 아래 명령으로 저장한 키를 암호화합니다. 암호화에 쓰는 키는 설정 파일 옆의 .secret_key에 있으니 이 파일을 버전 관리에 넣지 마세요.

    다음 명령을 키 값 인수 없이 실행하면 ZeroClaw가 숨김 입력으로 키를 받아 암호화해 저장합니다.

    zeroclaw config set providers.models.custom.letsur.api_key
  3. 에이전트 연결하기

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

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

    custom.letsur의 letsur는 사용자가 지정하는 별칭입니다. [agents.<별칭>]의 model_provider가 이 이름을 그대로 참조합니다. 별칭에는 영문 소문자, 숫자와 밑줄만 사용하며 하이픈은 사용할 수 없습니다.

  4. 도구 승인 기준 연결하기

    아래 예시에서는 승인 방식을 supervised로 지정하고, 파일 읽기와 검색 도구를 자동 승인 목록에 등록합니다. supervised에서 ZeroClaw는 낮은 위험 작업만 바로 실행합니다. 중간 위험 작업은 승인을 요청하고, 높은 위험 작업은 차단합니다.

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

모델 선택

모델은 provider 등록하기 단계의 model에 에셋의 정확한 모델 코드로 지정합니다.

연결 확인

먼저 설정 파일을 불러와 검증합니다. 검증에 실패하면 오류가 표준 오류로 출력됩니다.

zeroclaw config list

ZeroClaw에는 기본 에이전트가 없으므로 -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일에 확인했습니다. 이 확인에는 렛서 게이트웨이와의 실제 연동 시험이 포함되지 않습니다.