OpenClaw에 laozhang.ai 연결하기: API 설정과 도구 호출 확인

OpenClaw에 laozhang.ai를 연결하려면 models.providers에 기본 URL https://api.laozhang.ai/v1, API 키 참조, openai-completions 프로토콜과 정확한 모델 ID를 등록합니다. 이어서 에이전트가 사용할 모델을 laozhang/모델ID 형식으로 선택하고, 허용 목록이 있는 경우 같은 모델을 허용해야 합니다. 아래 예제는 gpt-5.4-mini 하나로 시작하는 Chat Completions 설정입니다.

안내: laozhang.ai는 이 블로그 운영팀의 자사 서비스입니다. 그 가격은 독립적인 비교가 아니라 자사 제시 가격입니다.

먼저 이용 자격부터 확인하세요. 2026년 10월 7일 기준 LaoZhang API는 신규 이용자에게 기업 화이트리스트 승인을 요구합니다. 공개 안내에는 Gmail 등록과 선불 종량제 방식이 설명되어 있습니다. 이전의 ‘가입 즉시 200개 이상 모델 사용’, ‘3분 완료’, ‘무료 크레딧 제공’ 안내를 현재 이용 조건으로 받아들이면 안 됩니다. 승인과 토큰의 모델 권한은 현재 서비스 안내에서 확인해야 합니다.

이 글은 이미 OpenClaw를 사용하는 독자를 대상으로 합니다. 설정 예제는 현재 공개 문서에 근거하며, 이 글을 위해 실제 OpenClaw 연결이나 유료 모델 호출을 실행하지는 않았습니다. 설정을 저장한 뒤 대화 응답과 필요한 도구 실행을 직접 확인하는 절차까지 따라가야 연결 여부를 판단할 수 있습니다.

연결 전에 모델 ID와 토큰 그룹을 맞추세요

API 주소를 맞췄어도 토큰에 해당 모델을 사용할 권한이 없으면 요청은 실패합니다. 준비할 것은 승인된 서비스 이용 권한, LaoZhang API 키, 그리고 그 키의 토큰 그룹에서 사용할 수 있는 정확한 모델 ID입니다. 계정의 AccessToken과 모델 호출용 API 키는 서로 다릅니다. 인증 방식과 지원 API는 LaoZhang API 매뉴얼에 설명되어 있습니다.

안내: laozhang.ai는 이 블로그 운영팀의 자사 서비스입니다. 그 가격은 독립적인 비교가 아니라 자사 제시 가격입니다.

처음에는 모델을 여러 개 등록하기보다 필요한 모델 하나를 확인하세요. 2026년 10월 7일 공개 모델 목록에는 gpt-5.4-mini가 기본 그룹 모델로 표시되어 있습니다. 도구 연동 안내에서도 이 모델을 Chat Completions 도구 호출 대상으로 다루며, 공급업체는 10월 5일 스트리밍 도구 테스트 결과를 보고했습니다. 따라서 도구를 쓰는 OpenClaw 설정의 출발점으로 삼을 근거는 있지만, 그 결과가 사용자의 OpenClaw 환경에서도 그대로 재현된다는 뜻은 아닙니다.

현재 공개 목록의 온라인 모델 222개에는 이미지·음성·영상·임베딩 등이 포함됩니다. 이를 OpenClaw 대화에 바로 쓸 수 있는 모델 222개로 해석하지 마세요. 같은 목록에는 Claude 모델이 리소스 부족으로 일시 중단된 것으로 표시되어 있습니다. 예전 글의 Sonnet·Opus 예제를 그대로 기본 모델이나 대체 모델에 넣기보다, 현재 공급 상태와 토큰 권한을 먼저 확인해야 합니다.

프로토콜도 모델 이름만 보고 선택하지 않습니다. LaoZhang은 Chat Completions, Responses, Messages 등을 각각 문서화하고 있습니다. 여기서는 /v1/chat/completions에 대응하는 openai-completions를 사용합니다. Responses로 바꾸려면 실제 /v1/responses 지원과 해당 어댑터의 요청 형식을 함께 맞춰야 하며, URL만 유지한 채 어댑터를 바꾸는 것으로 호환성이 보장되지는 않습니다. GPT 계열이라도 reasoning effort, max_tokens 등의 지원이 모델과 경로에 따라 다르므로, 첫 연결에 다른 모델의 옵션을 한꺼번에 복사하지 않는 편이 좋습니다. 프로토콜 안내와 도구 연동별 제약을 기준으로 필요한 옵션을 추가하세요.

openclaw.json에 공급업체와 기본 모델 등록하기

기본 설정 파일은 ~/.openclaw/openclaw.json이며 JSON5 형식을 사용합니다. OPENCLAW_CONFIG_PATH를 지정한 환경은 다른 파일을 사용할 수 있습니다. 먼저 실제 실행 환경이 읽는 파일을 확인하고 기존 파일을 백업하세요. 아래는 기존 설정에 병합할 모델 관련 예제입니다. 채널, 작업 공간, 도구 권한 등의 설정은 생략했으므로 기존 파일 전체를 이 내용으로 교체하지 않습니다. OpenClaw는 알 수 없는 필드나 잘못된 자료형을 거부합니다. 설정 파일 안내

{
  "models": {
    "mode": "merge",
    "providers": {
      "laozhang": {
        "baseUrl": "https://api.laozhang.ai/v1",
        "apiKey": "${LAOZHANG_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "gpt-5.4-mini",
            "name": "LaoZhang GPT-5.4 Mini"
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "laozhang/gpt-5.4-mini"
      },
      "modelPolicy": {
        "allow": ["laozhang/gpt-5.4-mini"]
      }
    }
  }
}

modelPolicy.allow는 OpenClaw v2026.8.1 이후 문서의 모델 참조 문자열 배열입니다. 기존 허용 목록을 유지하면서 laozhang/gpt-5.4-mini를 추가하세요. 위 배열 하나로 기존 목록을 덮어쓰면 다른 모델의 사용 권한을 잃을 수 있습니다. 에이전트별 agents.entries.*.modelPolicy.allow가 있으면 기본 정책보다 우선하므로, 실제 사용할 에이전트의 정책도 확인해야 합니다. 업그레이드 전 설정은 아래의 허용 목록 오류 설명을 함께 읽으세요. 모델 정책과 선택 규칙

이 예제에서 laozhang는 OpenClaw 안에서 정한 공급업체 이름입니다. API에 보내는 실제 모델 ID는 gpt-5.4-mini이고, OpenClaw가 공급업체까지 구분할 때는 laozhang/gpt-5.4-mini를 사용합니다. 표시 이름인 name을 모델 ID 자리에 넣지 마세요.

mode: "merge"는 기본 공급업체 목록과 합치는 의도를 명시합니다. 현재 OpenClaw에서는 merge가 기본값이므로 이 필드를 생략했다고 기존 공급업체가 사라지는 것은 아닙니다. replace는 목록을 의도적으로 대체할 때 사용합니다. 또한 에이전트별 models.json에 같은 공급업체의 비어 있지 않은 baseUrl이 있으면 그 값이 우선할 수 있습니다. 설정 파일을 고쳤는데 계속 다른 주소로 접속한다면 공급업체를 중복 등록했는지 살펴보세요. SecretRef 인증 정보에는 별도의 병합 우선순위가 적용됩니다. 커스텀 공급업체 설정

API 키는 실제 Gateway 프로세스에 전달해야 합니다

예제의 ${LAOZHANG_API_KEY}는 실제 키를 대신하는 환경 변수 참조입니다. 변수 이름만 적는 것으로 인증 정보가 생기지는 않습니다. OpenClaw Gateway를 시작하는 프로세스에서 이 변수를 사용할 수 있게 하거나, 현재 환경에 맞는 비밀 정보 관리 방식을 사용해야 합니다.

OpenClaw는 부모 프로세스의 환경 변수, 현재 작업 디렉터리의 .env, ~/.openclaw/.env 등을 읽습니다. .env 파일은 이미 설정된 환경 변수 값을 덮어쓰지 않습니다. 별도 터미널에서 export한 값이 launchd·systemd 서비스나 컨테이너의 Gateway에 자동으로 전달되는 것도 아닙니다. ${VAR}는 대문자 변수 참조를 지원하며, 값이 없거나 비어 있으면 경고와 함께 미해결 상태로 남습니다. 환경 변수 처리 규칙

키 값을 터미널에 출력해서 확인하거나 채팅에 붙여 넣지 마세요. 인증 오류를 조사할 때는 키 내용 대신 Gateway가 읽는 변수 이름, 값의 존재 여부, 실행 방식과 적용 시점을 확인하면 됩니다. 키를 Git에 포함하지 않는 것도 필요합니다.

등록된 모델과 현재 대화의 모델을 구분해 확인하기

설정 확인은 문법, 모델 선택, 실제 요청 순서로 진행합니다. 아래 명령은 독자가 자신의 환경에서 확인할 때 사용하는 예이며, 이 글의 작성 과정에서 실행한 결과는 아닙니다.

openclaw config validate
openclaw models list --provider laozhang
openclaw models set laozhang/gpt-5.4-mini

첫 명령은 설정 스키마를 확인합니다. 두 번째는 공급업체의 모델이 OpenClaw 목록에 들어왔는지 확인합니다. 세 번째는 기본 모델을 변경합니다. 목록에 모델이 보이거나 기본 모델 변경이 끝났다고 API 키와 모델 호출까지 성공한 것은 아닙니다. models status와 --check의 종료 코드 0도 실제 모델 응답의 증거가 아니며, 상태 확인 과정에서 비밀 정보가 해석될 수 있습니다. 모델 CLI 안내

기존 대화에서 다른 모델을 직접 선택했다면 기본 모델 변경만으로 그 대화가 바뀌지 않을 수 있습니다. 현재 대화에서 기본 선택을 다시 따르려면 /model default로 고정을 해제하고, LaoZhang 모델을 명시적으로 선택하려면 /model laozhang/gpt-5.4-mini를 사용합니다. 이 두 선택은 의미가 다릅니다. 명시적으로 고정한 대화 모델에는 엄격한 선택 규칙이 적용되므로, 오류가 날 때 기본 fallback이 대신 답할 것이라고 가정하지 마세요. 대화별 모델 선택

모델·공급업체·기본값·fallback 변경은 현재 문서상 동적으로 적용될 수 있습니다. 기본 hybrid 모드에서는 변경마다 무조건 수동 재시작할 필요가 없고, 재적용을 꺼 둔 환경에서는 직접 재시작해야 합니다. 잘못된 외부 변경이 들어오면 마지막 정상 설정으로 실행을 계속할 수 있으므로, 파일에 새 값이 저장되었다는 사실만으로 실행 중인 설정도 바뀌었다고 판단하지 않습니다. 설정 재적용 동작

응답 확인 뒤에는 허용된 도구가 실제로 실행되는지 확인하세요

연결 확인은 비용이 작고 결과가 분명한 작업부터 진행하세요. 먼저 LaoZhang 모델을 선택한 대화에 짧은 질문을 보내고, 선택된 모델 참조와 정상 응답을 확인합니다. 그다음 기존에 허용된 읽기 도구가 있는 작업 공간에서 테스트용 문서 하나를 읽고 특정 문장을 알려 달라고 요청할 수 있습니다. 별도의 도구 권한을 넓히거나 파일 수정·외부 전송 작업으로 시작할 필요는 없습니다.

‘파일을 읽었습니다’라는 답변만으로 도구 실행을 판단하지 마세요. 실제 도구 호출과 결과가 있어야 합니다. Chat Completions 응답에는 tool_calls가 있고 텍스트가 비어 있을 수도 있습니다. 이때 빈 텍스트만 보고 접속 실패로 판단하면 정상적인 도구 호출 단계를 놓칩니다. 반대로 일반 답변이 나왔다고 필요한 도구까지 작동한다고 볼 수도 없습니다. Chat Completions 응답 형식

안내: laozhang.ai는 이 블로그 운영팀의 자사 서비스입니다. 그 가격은 독립적인 비교가 아니라 자사 제시 가격입니다.

CLI의 --probe는 실제 모델 요청을 보내므로 과금과 상태 관리가 필요합니다. 현재 문서는 직접 probe를 할 때 상태를 독점하고 Gateway를 중지한 뒤 정리까지 마치는 조건을 설명합니다. 대화가 정상 작동하는지 확인하려고 실행 중인 Gateway와 동시에 probe를 덧붙이지 마세요. openclaw models scan은 LaoZhang 모델 확인용 명령이 아닙니다. OpenRouter의 무료 모델 목록을 대상으로 하며 기본 동작에는 실제 검사와 설정 쓰기가 포함됩니다. probe와 scan의 범위

오류 메시지에 따라 설정·권한·호출을 나눠 고치세요

같은 오류를 반복 호출하기 전에 응답 본문의 원인을 읽으세요. HTTP 상태 코드만으로 잔액 부족, 모델 공급 중단, 설정 오류를 모두 구분할 수는 없습니다. 다음 표는 LaoZhang 오류 안내와 OpenClaw 모델 정책에 따른 확인 순서입니다.

안내: laozhang.ai는 이 블로그 운영팀의 자사 서비스입니다. 그 가격은 독립적인 비교가 아니라 자사 제시 가격입니다.

허용 목록 오류가 계속되면 버전과 에이전트별 정책을 확인하세요

현재 문서의 agents.defaults.models는 모델별 별칭과 설정을 담는 맵입니다. v2026.8.1 이후의 명시적 허용 정책은 agents.defaults.modelPolicy.allow이며, 값은 "laozhang/gpt-5.4-mini" 같은 참조의 배열입니다. 그런데 이전 설정에서 마이그레이션되지 않은 모델 맵은 기존 제한을 계속 유지할 수 있습니다. 최신 정책만 추가했는데 오류가 남는다면 버전, 기존 제한의 마이그레이션 상태, 에이전트별 정책을 함께 확인하세요.

이 오류를 없애려고 제한 전체를 삭제하는 것을 기본 해결책으로 삼지 않습니다. 필요한 모델만 허용하는 방식으로 고치세요. doctor --fix는 수리 작업이며 무조건 읽기 전용 검사가 아닙니다. 현재 문서에 따르면 해결되지 않은 기존 제한을 보존할 수 있어, 실행했다고 정책 충돌이 모두 사라지는 것도 아닙니다. 모델 정책과 기존 설정의 이전

기본 모델을 바꿨는데 이전 모델이 계속 답한다면

현재 대화가 모델을 고정했는지 먼저 살펴보세요. 고정을 풀어 기본값을 따르게 하려면 /model default를 사용합니다. 에이전트가 자체 모델을 지정했거나 해당 에이전트의 models.json이 다른 공급업체 주소를 유지하는 경우도 확인해야 합니다. 마지막으로 변경된 설정이 실행 환경에 적용되었는지 확인하세요. 이 순서로 보면 같은 API 키를 계속 재발급하지 않고도 선택·주소·적용 문제를 구분할 수 있습니다.

비용은 실제 토큰 사용량과 그룹 요율로 계산합니다

LaoZhang API는 선불 잔액에서 실제 사용량에 따라 차감합니다. OpenClaw에 적은 모델의 cost 값이 공급업체 청구액을 바꾸지는 않습니다. 특히 cost를 0으로 표시한다고 호출이 무료가 되지 않습니다. 토큰 그룹과 과금 방식이 접근 권한 및 차감액에 영향을 주며, 실제 청구 내역은 서비스 사용량 화면을 기준으로 확인해야 합니다. 과금 방식

안내: laozhang.ai는 이 블로그 운영팀의 자사 서비스입니다. 그 가격은 독립적인 비교가 아니라 자사 제시 가격입니다.

2026년 10월 7일 공개 모델 목록의 gpt-5.4-mini 가격은 100만 토큰당 입력 0.75달러, 출력 4.50달러, 캐시 읽기 0.075달러입니다. 캐시를 쓰지 않고 그룹 배수가 1이라고 가정하면 입력 20,000토큰과 출력 2,000토큰의 계산은 다음과 같습니다. 통화는 미국 달러입니다.

입력: 20,000 ÷ 1,000,000 × 0.75 = 0.015달러
출력:  2,000 ÷ 1,000,000 × 4.50 = 0.009달러
합계: 0.024달러

이는 가상의 사용량 계산이며 실제 호출 결과나 월 요금 예측이 아닙니다. 에이전트는 한 작업에서도 대화 기록, 도구 결과, 후속 응답을 여러 번 보낼 수 있습니다. 짧은 질문 한 번의 비용을 작업 하나 전체의 비용으로 보지 마세요. 처음에는 출력 길이를 작게 유지하고, 일반 응답과 필요한 도구를 확인한 뒤 실제 사용량을 보며 예산을 정하는 편이 낫습니다. 공개적으로 확인되지 않은 기업 할인율이나 고정 월비용을 전제로 선택하지 않습니다.

fallback이 필요하면 현재 사용 가능한 모델을 추가로 등록하고 그 모델도 허용 정책에 포함하세요. OpenClaw는 적격 오류에서 같은 모델의 복구·인증 순환을 거친 뒤 정해 둔 순서의 fallback을 사용합니다. 답변 품질이 부족할 때 자동으로 비싼 모델을 고르는 기능은 아닙니다. 컨텍스트 초과나 최종 거부가 모두 전환 대상인 것도 아니며, 대화에서 직접 고른 모델에는 엄격한 선택 규칙이 적용됩니다. 같은 LaoZhang 게이트웨이의 두 모델은 잔액 부족이나 게이트웨이 장애를 함께 겪을 수 있다는 점도 고려하세요. 모델 장애 전환 규칙

클라우드 API와 로컬 모델 중 무엇을 사용할지, 에이전트와 대화마다 모델을 어떻게 나눌지까지 결정해야 한다면 OpenClaw 모델 설정: 클라우드 API와 Ollama·LM Studio 연동하기를 이어서 읽을 수 있습니다.

자주 묻는 질문

laozhang.ai에 가입하면 바로 OpenClaw에 연결할 수 있나요?

2026년 10월 7일 공개 안내에서는 신규 이용자에게 기업 화이트리스트 승인을 요구합니다. 승인된 이용 권한, 호출용 API 키, 사용할 모델에 대한 토큰 그룹 권한이 있어야 설정을 진행할 수 있습니다. 무료 크레딧이 자동 제공된다고 전제하지 마세요. 현재 서비스 이용 안내

Claude를 기본 모델이나 fallback으로 넣어도 되나요?

현재 예제로 권하지 않습니다. 2026년 10월 7일 LaoZhang 모델 목록은 Claude 모델의 일시 중단을 안내합니다. 공급이 재개되면 정확한 ID와 토큰 권한, 사용할 프로토콜을 다시 확인한 뒤 등록해야 합니다. 예전 Sonnet·Opus ID가 설정에 남아 있다는 사실은 사용 가능하다는 증거가 아닙니다.

ChatGPT 구독이나 OpenClaw의 Codex 연결과 같은 방식인가요?

이 글은 LaoZhang API 키로 커스텀 공급업체를 연결하는 방식입니다. 공급업체 이름이나 모델 참조를 등록했다고 ChatGPT 구독 권한이나 네이티브 Codex 인증을 얻는 것은 아닙니다. 실제 인증 방식과 사용 가능한 모델은 해당 공급업체 설정 및 계정 권한에 따라 확인해야 합니다. OpenClaw 모델 선택 안내

모델 목록이 나오는데 도구 호출은 왜 실패하나요?

목록은 등록 상태를 보여 줍니다. 필요한 도구를 지원하는 모델과 프로토콜인지, OpenClaw에서 해당 도구가 허용되어 있는지, 실제 호출 뒤 실행 결과가 반환되는지를 별도로 확인해야 합니다. LaoZhang의 스트리밍 도구 테스트 보고는 공급업체의 결과이며, 사용자의 OpenClaw 도구 실행을 대신 검증하지 않습니다. 도구 연동 안내

설정을 바꿀 때마다 Gateway를 재시작해야 하나요?

모델 관련 변경은 현재 문서상 동적으로 적용할 수 있습니다. 기본 hybrid 모드와 재적용을 꺼 둔 환경은 동작이 다르므로 자신의 설정을 확인하세요. 잘못된 변경으로 마지막 정상 설정이 유지되는 경우도 있어, 저장 여부와 실제 적용 여부를 구분해야 합니다. 설정 재적용 안내