OpenClaw 중계 API 연동 튜토리얼: 자율 에이전트 프레임워크 설정

1. OpenClaw란 무엇인가

OpenClaw는 오픈 소스 AI 에이전트(Agent) 프레임워크입니다. 모델(로컬 또는 클라우드 게이트웨이)을 지정하면 컴퓨터에서 인터페이스 조작, 명령어 실행, 파일 관리 등의 작업을 자동으로 수행할 수 있습니다. 핵심은 '모델 엔드포인트 구성'이므로 본 사이트의 게이트웨이를 연결하여 사용하기에 매우 적합합니다.

2. OpenClaw 설치

원클릭 설치 스크립트 권장:

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard

Docker 또는 소스 코드를 통해 설치할 수도 있습니다:

git clone https://github.com/openclaw/openclaw.git
cd openclaw
# Docker：./scripts/docker/setup.sh
# 소스 코드(pnpm)：corepack enable && pnpm install && pnpm openclaw setup

3. 본 사이트 게이트웨이 연결 (두 가지 방법)

방법 1: 대화형 가이드(onboard)

openclaw onboard를 실행하고, Provider 선택 시 사용자 지정 주소를 지원하는 옵션을 선택한 후 다음을 입력합니다:

Base URL : https://www.relay-api.com
API Key  : sk-본인의 키
Model ID : claude-sonnet-5

(openai / gemini 엔드포인트는 각각 https://www.relay-api.com/v1 및 https://www.relay-api.com/v1beta에 대응합니다)

방법 2: 설정 파일 직접 수정

OpenClaw는 ~/.openclaw/openclaw.json(Linux/macOS) 또는 %USERPROFILE%\.openclaw\openclaw.json(Windows)을 읽습니다. models.providers에 새로운 Provider를 추가하세요:

{
  "gateway": {
    "mode": "local"
  },
  "agents": {
    "defaults": {
      "model": {"primary": "jizhi/claude-sonnet-5"}
    }
  },
  "models": {
    "providers": {
      "jizhi": {
        "baseUrl": "https://www.relay-api.com",
        "apiKey": "sk-본인의 키",
        "api": "openai-completions"
      }
    }
  }
}

primary를 사용하는 모델 슬러그로 변경하면 OpenClaw의 모든 에이전트 작업이 본 사이트 게이트웨이를 통해 이루어집니다.

4. 실행 및 자주 사용하는 명령어

openclaw gateway --port 18789

시작 후 http://localhost:18789에 접속하여 제어판으로 들어갑니다. 자주 사용하는 명령어:

openclaw doctor              # 문제 진단
openclaw security audit      # 보안 점검
openclaw config set key x    # 설정 수정
openclaw channels add --channel telegram  # 메시지 채널 추가

5. 자주 묻는 질문(FAQ)

현상	조치
401 / 403	키가 유효하지 않거나 활성화되지 않음, 또는 잔액 부족. sk- 키가 정확한지 확인하고 충전하세요.
404 / 모델 이용 불가	모델 슬러그가 플랫폼과 일치하지 않거나 해당 모델이 활성화되지 않음. 모델 ID를 확인하세요.
모델 연결 실패	baseUrl이 본 사이트의 입구 주소인지 확인하세요.

보안 권장사항: sk- 키를 공개 리포지토리에 올리지 마십시오. 에이전트 작업은 토큰 소모가 많으므로 잔액을 주의 깊게 확인하세요.

Base URL 안내: 본 사이트는 /v1beta/models/...와 /v1beta/v1beta/models/...(및 /v1/...와 /v1/v1/...)을 모두 허용하므로, 클라이언트가 /v1이나 /v1beta를 자동으로 추가하는지 여부와 상관없이 호출이 가능합니다. Base URL은 도메인 루트를 입력하거나 /v1beta가 포함된 주소를 입력해도 모두 작동합니다. 모델 ID는 제어판 내 「토큰(Token)」 페이지 오른쪽 상단의 「모델 ID」에서 복사하여 확인하십시오.