OpenClaw 설치 및 API 설정

OpenClaw는 TokenHub의 OpenAI compatible 호환 API 게이트웨이로 모델 요청을 라우팅할 수 있습니다. 공식 설치 방식은 그대로 두고 API key, Base URL, model ID만 바꿉니다.

이 가이드에서 사용하는 TokenHub endpoint는 https://us-api.tokenhub.com/v1/chat/completions입니다.

사용할 때

작은 저장소나 테스트 프로젝트에서 시작하세요. 먼저 파일 읽기, 코드 설명, 계획 생성을 확인한 뒤 편집과 자동화 작업을 켭니다.

설치 또는 열기

먼저 OpenClaw 공식 문서에 따라 설치하거나 엽니다. 메뉴가 다르면 현재 공식 문서를 우선하세요.

CLI 도구는 TokenHub 자격 증명을 추가하기 전에 실행 파일이 동작하는지 먼저 확인합니다:

openclaw --version

TokenHub 자격 증명 준비

TokenHub API key를 만들고 TokenHub 모델 목록에서 이 도구에 맞는 모델을 선택합니다.

export TOKENHUB_API_KEY="sk-..."

키는 로컬 shell, IDE 비밀 저장소, 또는 도구의 안전한 API key 필드에 저장하세요. 저장소에 커밋하지 마세요.

TokenHub 공급자 설정

Models, Providers, API Keys, OpenAI Compatible 설정 화면에서 아래 값을 입력합니다.

Provider 값

Use the official custom provider guide for the current models.providers schema and OpenAI-compatible adapter behavior.

설정 파일 위치

Store the key where the managed Gateway can read it:

TOKENHUB_API_KEY=your-local-tokenhub-key

Add the custom provider to ~/.openclaw/openclaw.json:

{
  models: {
    mode: 'merge',
    providers: {
      tokenhub: {
        baseUrl: '__API_BASE_URL__/v1',
        apiKey: '${TOKENHUB_API_KEY}',
        api: 'openai-completions',
        models: [
          {
            id: 'gpt-4.1',
            name: 'TokenHub / gpt-4.1',
            reasoning: false,
            input: ['text'],
            contextWindow: 128000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: {
        primary: 'tokenhub/gpt-4.1',
      },
    },
  },
}

Replace the example model metadata with the actual limits and capabilities of the TokenHub model you selected. Keep the catalog id bare, then add the provider prefix only when selecting it as tokenhub/gpt-4.1.

Restart the Gateway and verify the custom provider:

openclaw gateway restart
openclaw models list --provider tokenhub
openclaw models set "tokenhub/gpt-4.1"

The API key remains in ~/.openclaw/.env so launchd, systemd, Docker, and other managed Gateway processes can read it.

도구가 chat, edit, apply, fast models를 나누어 두었다면 첫 테스트에서는 같은 TokenHub 모델을 사용하세요. 동작 확인 후 비용, 지연 시간, 추론 성능에 따라 분리합니다.

임시 환경 변수는 디버깅용

임시 변수는 key, 네트워크, 모델 이름 확인에만 사용하세요. 검증 후 같은 값을 위의 영구 설정으로 옮기세요.

export TOKENHUB_API_KEY="sk-..."

연결 확인

먼저 읽기 전용 프롬프트로 모델이 컨텍스트를 읽고 파일을 바꾸지 않는지 확인합니다. 그 다음 편집이나 agent 작업을 테스트합니다.

프로젝트 README를 읽고 세 문장으로 요약해 주세요. 파일은 수정하지 마세요.

프롬프트가 성공하면 TokenHub 요청 로그에서 모델 이름, endpoint, token 사용량, billing group을 확인합니다.

문제 해결