CometAPI와 함께 OpenClaw 사용하기

이 가이드를 사용하여 OpenClaw 를 CometAPI에 연결하세요. 첫 번째 구성에서는 하나의 API 형식과 모델 ID를 선택하세요.

OpenClaw v2026.8.1은 OpenClaw 2.0으로도 표기됩니다. 패키지는 2.x 버전 번호를 사용하지 않습니다. 다음을 참조하세요. OpenClaw 2.0 발표 및 v2026.8.1 릴리스 노트.

공식 OpenClaw 참조 자료:

사전 요구 사항

Node.js 22.22.3+, 24.15+ 또는 25.9+가 필요합니다. Node 26을 권장합니다. Node 23은 지원되지 않습니다.
활성 API 키가 있는 CometAPI 계정, 키 발급처: 대시보드.
모델 ID를 확인할 수 있는 페이지: CometAPI Models 페이지.

설치 및 업그레이드

첫 설치
설치 업그레이드

공식 설치 관리자를 사용하면 온보딩을 시작하지 않고 CLI를 설치할 수 있습니다. 이렇게 하면 모델 구성을 별도의 단계로 유지할 수 있습니다.

macOS / Linux / WSL2
Windows PowerShell

다음 명령어로 공식 설치 관리자를 실행합니다:

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

다음 명령어로 공식 PowerShell 설치 관리자를 실행합니다:

& ([scriptblock]::Create(
  (iwr -useb https://openclaw.ai/install.ps1)
)) -NoOnboard

Node.js와 npm을 직접 관리하는 경우, npm 11.16+ 및 npm 12는 다음 --allow-scripts 옵션을 지원합니다. 다음 명령어는 OpenClaw를 온보딩 없이 설치합니다:

npm install -g openclaw@latest --allow-scripts=openclaw

npm 11.15 이하에서는 --allow-scripts=openclaw 없이 설치하세요. 해당 npm 버전은 이 옵션을 인식하지 못합니다.설치된 CLI가 이 가이드의 최소 버전 요구 사항을 충족하는지 확인하세요:

openclaw --version

계속하려면 CometAPI 구성으로 진행하세요. 일반 온보딩을 먼저 실행하지 마세요. 안내 흐름에서는 모든 사용자 지정 API 어댑터를 표시하지 않기 때문입니다.

중요한 업데이트 전에 백업을 생성하고 검증하세요. 아카이브에는 API 키, 채널 상태 및 인증 데이터가 포함될 수 있으므로 OpenClaw 상태 디렉터리를 보호하는 것과 동일하게 보호하세요.다음 명령어로 백업을 생성하고 OpenClaw를 업데이트합니다:

mkdir -p ~/Backups/openclaw
openclaw backup create --output ~/Backups/openclaw --verify
openclaw update

업데이트 후 지원되는 마이그레이션을 복구하고 Gateway 상태를 확인하세요:

openclaw doctor --fix
openclaw gateway restart
openclaw health

업데이트하면 구성된 모델 경로가 유지됩니다. 온보딩을 반복하지 마세요 모델 제공업체 또는 해당 인증을 변경하려는 경우가 아니라면.

CometAPI 구성

클래식 온보딩 사용

클래식 온보딩은 채팅 완성, 응답 및 Anthropic 메시지를 처음 설치할 때 권장되는 경로입니다. 다음 명령은 클래식 온보딩을 열고 백그라운드 서비스를 설치합니다:

openclaw onboard --classic --install-daemon

에서 Model/Auth에서 Custom Provider을 선택합니다. 그런 다음 다음 호환성 옵션 중 하나에 대한 값을 입력합니다:

API 형식	Provider ID	호환성 옵션	Base URL
채팅 완성	`cometapi-openai`	OpenAI 호환	`https://api.cometapi.com/v1`
응답	`cometapi-openai-responses`	OpenAI Responses 호환	`https://api.cometapi.com/v1`
Anthropic 메시지	`cometapi-claude`	Anthropic 호환	`https://api.cometapi.com`

메시지가 표시되면 일치하는 provider ID, your-model-id 및 CometAPI API 키를 입력하세요. 터미널 마법사는 API 키 입력을 마스킹합니다. 클래식 Custom Provider 메뉴에는 Google Generative AI 어댑터가 포함되어 있지 않습니다. 해당 어댑터를 사용하려면 config 명령으로 provider 구성, 을 완료하고 기본 모델을 설정한 후 클래식 온보딩을 실행하세요. 해당 옵션이 표시되면 기존 모델 구성 을 선택하세요.

config 명령으로 provider 구성

Google 어댑터를 사용하거나 구성 변경을 제어하려면 이 경로를 사용하세요. OpenClaw는 JSON5를 지원하므로 openclaw.json을 엄격한 JSON 도구로 파싱하고 다시 작성하지 마세요.

OpenClaw의 기본 구성 작성기는 JSON5를 검증하지만 파일을 작성할 때 JSON으로 정규화합니다. 기존 주석, 후행 쉼표 및 서식은 제거될 수 있습니다. 이러한 세부 정보가 중요하다면 패치를 적용하기 전에 검증된 백업을 만드세요.

먼저 활성 구성 경로를 출력하고 내용을 검증합니다:

openclaw config file
openclaw config validate

OpenClaw는 provider API 키를 프로세스 환경 또는 전역 상태 .env 파일에서 읽습니다. provider API 키에 대해 워크스페이스 .env 파일은 신뢰하지 않습니다. 전역 파일은 ~/.openclaw/.env이며, $OPENCLAW_STATE_DIR/.env OPENCLAW_STATE_DIR이 설정된 경우에는 해당 위치를 사용합니다. 클래식 온보딩에서 API 키를 저장했다면 다음 단계를 건너뛰세요. 그렇지 않으면 운영 체제에 해당하는 탭을 사용하여 API 키를 표시하지 않고 저장 하세요.

macOS / Linux / WSL2
Windows PowerShell

다음 명령은 COMETAPI_KEY을 원자적으로 업데이트하고 빈 값을 거부합니다:

state_dir="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
install -d -m 700 "$state_dir"
read -rsp "CometAPI API key: " COMETAPI_KEY
printf '\n'
if [ -z "$COMETAPI_KEY" ]; then
  echo "The CometAPI API key cannot be empty." >&2
  unset COMETAPI_KEY
  exit 1
fi
umask 077
env_file="$state_dir/.env"
temp_file="$(mktemp "${env_file}.XXXXXX")"
if [ -f "$env_file" ]; then
  awk -F= '$1 != "COMETAPI_KEY"' "$env_file" > "$temp_file"
fi
printf 'COMETAPI_KEY=%s\n' "$COMETAPI_KEY" >> "$temp_file"
chmod 600 "$temp_file"
mv "$temp_file" "$env_file"
unset COMETAPI_KEY temp_file env_file state_dir

다음 명령은 COMETAPI_KEY을 표시하지 않고 업데이트합니다:

$stateDir = if ($env:OPENCLAW_STATE_DIR) {
  $env:OPENCLAW_STATE_DIR
} else {
  Join-Path $HOME ".openclaw"
}
New-Item -ItemType Directory -Force -Path $stateDir | Out-Null
$secureKey = Read-Host "CometAPI API key" -AsSecureString
$plainKey = [Net.NetworkCredential]::new("", $secureKey).Password
if ([string]::IsNullOrWhiteSpace($plainKey)) {
  throw "The CometAPI API key cannot be empty."
}
$envFile = Join-Path $stateDir ".env"
$lines = @()
if (Test-Path $envFile) {
  $lines = @(Get-Content $envFile | Where-Object {
    $_ -notmatch '^COMETAPI_KEY='
  })
}
$lines += "COMETAPI_KEY=$plainKey"
$tempFile = Join-Path $stateDir ".$([guid]::NewGuid()).tmp"
[IO.File]::WriteAllLines($tempFile, $lines)
Move-Item -Force $tempFile $envFile
$plainKey = $null
$secureKey = $null

provider를 추가하기 전에 대상 경로를 검사하세요. 다음 명령에서 provider ID를 선택한 탭의 ID로 바꾸세요:

openclaw config get models.providers.cometapi-openai --json

명령이 구성된 provider를 반환하면 예제를 적용하기 전에 중지하세요. config patch 객체는 병합하지만 배열은 대체합니다. 새 모델을 배열을 작성하기 전에 provider의 모델 배열에 병합하세요. 이렇게 하면 모델 메타데이터, 사용자 지정 헤더 및 기타 provider 설정이 유지됩니다. API 형식을 하나 선택하세요. 각 패치는 환경 기반 SecretRef를 사용하고, 변경 사항을 대상 구성 경로로만 제한하며, 다른 구성 섹션은 그대로 유지합니다.

모델 ID가 모든 API 어댑터와 자동으로 호환되는 것은 아닙니다. 정확한 CometAPI 모델과 경로가 지원하는 어댑터를 선택한 다음, 실제 요청으로 provider/모델/어댑터 조합을 검증하세요. 아래의 your-model-id 값은 범용 호환성 주장이 아니라 구성 자리 표시자입니다.

채팅 완성
응답
Anthropic 메시지
Google Generative AI

Provider ID: cometapi-openai
OpenClaw 어댑터: openai-completions
Base URL: https://api.cometapi.com/v1
기본 모델 참조: cometapi-openai/your-model-id

이 provider 패치를 사용하여 cometapi.patch.json5을 만드세요:

{
  models: {
    mode: "merge",
    providers: {
      "cometapi-openai": {
        baseUrl: "https://api.cometapi.com/v1",
        apiKey: {
          source: "env",
          provider: "default",
          id: "COMETAPI_KEY",
        },
        api: "openai-completions",
        models: [
          {
            id: "your-model-id",
            name: "CometAPI model",
            input: ["text"],
          },
        ],
      },
    },
  },
}

OpenClaw가 구성을 작성하기 전에 패치를 검증하세요:

openclaw config patch --file ./cometapi.patch.json5 --dry-run

검증에 성공하면 동일한 패치를 적용하세요:

openclaw config patch --file ./cometapi.patch.json5

기본 모델이 구성되지 않은 경우 이 모델을 기본값으로 설정하세요:

openclaw models set cometapi-openai/your-model-id

provider 구성을 검증하고 최소 모델 요청을 전송하세요:

openclaw models list --provider cometapi-openai
openclaw models status --probe \
  --probe-provider cometapi-openai
openclaw agent exec \
  "Reply exactly with: OPENCLAW_OK" \
  --model cometapi-openai/your-model-id \
  --thinking off \
  --json

활성 OpenClaw 채팅 세션을 전환하려면 다음 채팅 명령을 실행하세요:

/model cometapi-openai/your-model-id

Provider ID: cometapi-openai-responses
OpenClaw 어댑터: openai-responses
Base URL: https://api.cometapi.com/v1
기본 모델 참조: cometapi-openai-responses/your-model-id

이 provider 패치를 사용하여 cometapi.patch.json5을 만드세요:

{
  models: {
    mode: "merge",
    providers: {
      "cometapi-openai-responses": {
        baseUrl: "https://api.cometapi.com/v1",
        apiKey: {
          source: "env",
          provider: "default",
          id: "COMETAPI_KEY",
        },
        api: "openai-responses",
        models: [
          {
            id: "your-model-id",
            name: "CometAPI model",
            input: ["text"],
          },
        ],
      },
    },
  },
}

OpenClaw가 구성을 작성하기 전에 패치를 검증하세요:

openclaw config patch --file ./cometapi.patch.json5 --dry-run

검증에 성공하면 동일한 패치를 적용하세요:

openclaw config patch --file ./cometapi.patch.json5

기본 모델이 구성되지 않은 경우 이 모델을 기본값으로 설정하세요:

openclaw models set cometapi-openai-responses/your-model-id

provider 구성을 검증하고 최소 모델 요청을 전송하세요:

openclaw models list --provider cometapi-openai-responses
openclaw models status --probe \
  --probe-provider cometapi-openai-responses
openclaw agent exec \
  "Reply exactly with: OPENCLAW_OK" \
  --model cometapi-openai-responses/your-model-id \
  --thinking off \
  --json

활성 OpenClaw 채팅 세션을 전환하려면 다음 채팅 명령을 실행하세요:

/model cometapi-openai-responses/your-model-id

Provider ID: cometapi-claude
OpenClaw 어댑터: anthropic-messages
Base URL: https://api.cometapi.com
기본 모델 참조: cometapi-claude/your-model-id

이 provider 패치를 사용하여 cometapi.patch.json5을 만드세요:

{
  models: {
    mode: "merge",
    providers: {
      "cometapi-claude": {
        baseUrl: "https://api.cometapi.com",
        apiKey: {
          source: "env",
          provider: "default",
          id: "COMETAPI_KEY",
        },
        api: "anthropic-messages",
        models: [
          {
            id: "your-model-id",
            name: "CometAPI model",
            input: ["text"],
          },
        ],
      },
    },
  },
}

OpenClaw가 구성을 작성하기 전에 패치를 검증하세요:

openclaw config patch --file ./cometapi.patch.json5 --dry-run

검증에 성공하면 동일한 패치를 적용하세요:

openclaw config patch --file ./cometapi.patch.json5

기본 모델이 구성되지 않은 경우 이 모델을 기본값으로 설정하세요:

openclaw models set cometapi-claude/your-model-id

provider 구성을 검증하고 최소 모델 요청을 전송하세요:

openclaw models list --provider cometapi-claude
openclaw models status --probe \
  --probe-provider cometapi-claude
openclaw agent exec \
  "Reply exactly with: OPENCLAW_OK" \
  --model cometapi-claude/your-model-id \
  --thinking off \
  --json

활성 OpenClaw 채팅 세션을 전환하려면 다음 채팅 명령을 실행하세요:

/model cometapi-claude/your-model-id

Provider ID: cometapi-google
OpenClaw 어댑터: google-generative-ai
Base URL: https://api.cometapi.com/v1beta
기본 모델 참조: cometapi-google/your-model-id

이 provider 패치를 사용하여 cometapi.patch.json5을 만드세요:

{
  models: {
    mode: "merge",
    providers: {
      "cometapi-google": {
        baseUrl: "https://api.cometapi.com/v1beta",
        apiKey: {
          source: "env",
          provider: "default",
          id: "COMETAPI_KEY",
        },
        api: "google-generative-ai",
        models: [
          {
            id: "your-model-id",
            name: "CometAPI model",
            input: ["text"],
          },
        ],
      },
    },
  },
}

OpenClaw가 구성을 작성하기 전에 패치를 검증하세요:

openclaw config patch --file ./cometapi.patch.json5 --dry-run

검증에 성공하면 동일한 패치를 적용하세요:

openclaw config patch --file ./cometapi.patch.json5

기본 모델이 구성되지 않은 경우 이 모델을 기본값으로 설정하세요:

openclaw models set cometapi-google/your-model-id

provider 구성을 검증하고 최소 모델 요청을 전송하세요:

openclaw models list --provider cometapi-google
openclaw models status --probe \
  --probe-provider cometapi-google
openclaw agent exec \
  "Reply exactly with: OPENCLAW_OK" \
  --model cometapi-google/your-model-id \
  --thinking off \
  --json

활성 OpenClaw 채팅 세션을 전환하려면 다음 채팅 명령을 실행하세요:

/model cometapi-google/your-model-id

구성에서 이미 cometapi-gemini provider ID를 사용하고 있다면 해당 ID를 유지하고 모델 참조와 명령에서 사용하세요. 이 가이드에 맞추기 위해 이름을 바꾸거나 중복 provider를 만들지 마세요.

네 가지 CometAPI provider 형식을 사용하는 OpenClaw 2026.8.1 모델 목록

새 provider의 경우 openclaw config set은 동일한 스키마와 SecretRef 검사를 제공합니다. 작성 전에 --strict-json, --merge 및 --dry-run을 사용하세요. 다음 대안은 채팅 완성 provider를 미리 봅니다: 작성 전에 사용할 수 있는 대안은 다음과 같습니다:

openclaw config set models.providers.cometapi-openai \
  '{
    "baseUrl": "https://api.cometapi.com/v1",
    "apiKey": {
      "source": "env",
      "provider": "default",
      "id": "COMETAPI_KEY"
    },
    "api": "openai-completions",
    "models": [
      {
        "id": "your-model-id",
        "name": "CometAPI model",
        "input": ["text"]
      }
    ]
  }' \
  --strict-json --merge --dry-run

드라이 런에 성공하면 --dry-run 없이 명령을 다시 실행하여 저장하세요. 구성된 provider에는 이 예제를 적용하지 마세요. 작성하기 전에 models 배열에는 provider의 완전히 병합된 모델 목록이 포함되어야 합니다.

모델 메타데이터 이해

최소 패치는 텍스트 전용 모델을 선언합니다. 모델 사양을 검증한 경우에만 선택적 메타데이터를 추가하세요:

필드	효과
`input`	허용되는 입력 모달리티를 선언합니다. 모델이 네이티브 이미지 입력을 허용하는 경우에만 `["text", "image"]`을 사용하세요.
`contextWindow`	모델의 기본 컨텍스트 윈도우(Context Window) 용량을 기록합니다.
`contextTokens`	변경하지 않고 활성 입력 예산을 제한합니다. `contextWindow`.
`maxTokens`	OpenClaw가 모델에 요청하는 출력 토큰(Token)을 제한합니다.

잘못된 값은 지원되는 입력을 숨기거나, 사용 가능한 컨텍스트를 과장하거나, 지원되지 않는 출력 크기를 요청할 수 있습니다. 재사용 가능한 예제에서는 your-model-id을 유지하고, 다음 CometAPI Models 페이지 에서 모델 ID를 선택하세요.

전체 설정 확인

config 또는 전역 .env 파일을 변경한 후 Gateway를 재시작합니다:

openclaw gateway restart

그런 다음 config 및 Gateway 상태를 검증합니다:

openclaw config validate
openclaw doctor
openclaw health

선택한 API 형식 탭에서 제공업체별 명령을 실행합니다. 모델 목록 또는 상태 확인은 구성만 확인합니다. openclaw agent exec 명령은 실제 모델 요청을 전송합니다. OPENCLAW_OK이 반환되는지 확인하고 해결되지 않은 인증, 어댑터 또는 모델 오류가 없는지 확인합니다. OpenClaw가 요청을 재시도하는 경우 최종 마커를 단일 시도 성공으로 간주하지 말고 모든 시도를 기록하고 검사합니다. 최종 마커를 단일 시도 성공으로 간주하지 마세요.

문제 해결

API 키가 없습니다

프로세스 환경 또는 전역 상태 COMETAPI_KEY 파일에 .env이 있는지 확인합니다. 터미널 출력에 값을 표시하지 마세요.신뢰할 수 있는 키 소스를 수정한 후 Gateway를 재시작하고 확인합니다:

openclaw gateway restart
openclaw health

제공업체 ID의 설정이 다릅니다

baseUrl, api, 사용자 지정 헤더 또는 모델 메타데이터가 다른 제공업체를 덮어쓰지 마세요. 먼저 대상 제공업체를 검사합니다:

openclaw config get models.providers.cometapi-openai --json
openclaw config validate

두 구성이 모두 의도된 경우 다른 제공업체 ID를 사용합니다. 차이가 실수로 발생한 경우 대상 제공업체를 변경하기 전에 검증된 백업을 생성합니다. 대상 제공업체를 변경합니다.

업데이트가 완료되지 않았습니다

설치를 복구하기 전에 업데이트 상태를 검사합니다:

openclaw update status --json
openclaw update repair
openclaw doctor --fix
openclaw health

이 명령은 상태 디렉터리를 유지합니다.

코드 롤백이 필요합니다

상태 디렉터리를 유지하면서 알려진 패키지 버전을 다시 설치합니다. 먼저 작업을 미리 봅니다:

openclaw update --tag 2026.8.1 --dry-run

미리 보기가 올바르면 --dry-run 없이 동일한 작업을 실행합니다:

openclaw update --tag 2026.8.1
openclaw doctor --fix
openclaw health

설치된 코드가 상태를 읽을 수 없는 경우에만 상태 백업을 복원합니다. 상태 복원으로 인해 백업 이후에 생성된 세션 및 구성 변경 사항이 삭제될 수 있습니다.

개요

AI 코딩 에이전트

AI 에이전트

AI 채팅 클라이언트

번역 및 언어

자동화 플랫폼

관측성 및 평가

AI 프레임워크

CometAPI와 함께 OpenClaw 사용하기

사전 요구 사항

설치 및 업그레이드

CometAPI 구성

클래식 온보딩 사용

config 명령으로 provider 구성

모델 메타데이터 이해

전체 설정 확인

문제 해결

​사전 요구 사항

​설치 및 업그레이드

​CometAPI 구성

​클래식 온보딩 사용

​config 명령으로 provider 구성

​모델 메타데이터 이해

​전체 설정 확인

​문제 해결

사전 요구 사항

설치 및 업그레이드

CometAPI 구성

클래식 온보딩 사용

config 명령으로 provider 구성

모델 메타데이터 이해

전체 설정 확인

문제 해결