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

1. OpenClaw란 무엇인가

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

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. 일반적인 문제 해결

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

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