OpenClaw

OpenClaw는 개인 장치에서 실행되는 오픈 소스 AI 어시스턴트입니다. Gateway로 모델, 세션, 도구 및 메시징 채널을 통합 관리하며 터미널 TUI와 브라우저 Control UI를 제공합니다. AGTCloud를 Custom Provider로 추가하면 OpenAI Chat Completions 호환 진입점을 통해 현재 API Key로 사용할 수 있는 모델을 호출할 수 있습니다.

이 튜토리얼은 로컬 설치, 모델 연동, Gateway 시작 및 기본 검증만 다룹니다. 메시징 채널, 원격 Gateway, ClawHub 플러그인, Skills, MCP, 예약 작업 및 다중 에이전트 기능은 이 페이지에서 설명하지 않습니다.

준비 사항

시작하기 전에 다음 사항을 확인합니다.

• OpenClaw가 지원하는 macOS, Linux, WSL2 또는 Windows 장치를 준비합니다.
• API Keys 페이지에서 AGTCloud API Key를 생성합니다.
• 모델 목록에서 현재 Key에 표시되며 Chat Completions를 지원하는 모델 ID를 복사합니다.
• 운영 자격 증명과 민감한 소스 코드가 없는 테스트 디렉터리를 준비합니다.

MODEL_ID는 교체해야 하는 자리표시자입니다. 도구 호출을 테스트하려면 현재 API Key에 표시되며 도구 호출 지원이 명확한 모델을 선택합니다.

OpenClaw 설치

OpenClaw 공식 설치 프로그램은 필요한 경우 지원되는 Node.js 실행 환경을 준비할 수 있습니다. Node.js를 직접 관리하는 고객은 npm으로 설치할 수도 있습니다.

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

설치 후 버전과 실행 환경을 확인합니다.

openclaw --version
openclaw doctor

설치 프로그램이 초기 설정 마법사를 자동으로 열면 모델 설정 단계를 먼저 종료하고 아래의 AGTCloud Provider 설정을 완료한 뒤 openclaw onboard --install-daemon을 실행할 수 있습니다. 이렇게 하면 초기 설정 프로그램이 검증된 기본 모델 설정을 유지할 수 있습니다.

API Key 안전하게 저장

OpenClaw는 ~/.openclaw/.env를 전역 환경 변수의 폴백 파일로 읽습니다. 파일을 먼저 생성하고 AGTCloud API Key를 기록합니다.

~/.openclaw/.env

파일 내용입니다.

AGTCLOUD_API_KEY=your-api-key

이 파일에는 실제 자격 증명이 포함되므로 코드 저장소에 커밋하거나 클라우드 드라이브에 업로드하거나 문제 해결 첨부 파일로 보내지 않습니다.

AGTCloud Custom Provider 추가

OpenClaw는 Custom Provider를 models.providers에 저장합니다. 이 튜토리얼은 증분 설정 명령으로 agtcloud Provider를 병합하며 기존 openclaw.json을 덮어쓰지 않습니다.

openclaw config set models.providers.agtcloud \
  '{"baseUrl":"https://api.agtcloud.cn/v1","apiKey":"${AGTCLOUD_API_KEY}","api":"openai-completions","auth":"api-key","authHeader":true,"models":[{"id":"MODEL_ID","name":"MODEL_ID","input":["text"]}]}' \
  --strict-json \
  --merge

설정의 주요 필드는 다음과 같습니다.

이 튜토리얼은 모델을 텍스트 입력으로만 선언하고 확인되지 않은 컨텍스트 길이, 최대 출력, 가격, 추론 또는 이미지 기능은 입력하지 않습니다. 대상 모델의 실제 기능을 파악한 뒤 OpenClaw 공식 모델 필드 설명에 따라 메타데이터를 보완할 수 있습니다.

모델 설정 및 설정 검사

방금 등록한 모델을 기본 모델로 설정합니다.

openclaw models set agtcloud/MODEL_ID

설정 파일, Provider 모델 및 현재 기본 모델을 순서대로 확인합니다.

openclaw config validate
openclaw models list --provider agtcloud
openclaw models status

config validate가 유효하지 않은 필드를 보고하면 설정부터 수정하고 Gateway 시작을 계속하지 않습니다. 모델 목록에 agtcloud/MODEL_ID가 없으면 모델이 models.providers.agtcloud.models에 추가되었는지 확인합니다.

실제 연결 탐색을 수행해야 할 때는 다음을 실행할 수 있습니다.

openclaw models status --probe

로컬 초기 설정 완료 및 Gateway 시작

Provider 설정을 통과한 뒤 로컬 초기 설정을 실행하고 Gateway 데몬을 설치합니다.

openclaw onboard --install-daemon

마법사에서 모델 설정을 물으면 기존 모델 설정 유지를 선택합니다. 메시징 채널, Web Search, Skills 및 기타 확장은 일단 건너뛸 수 있습니다. 첫 설정에서는 Gateway가 로컬에서만 수신하도록 유지하고 접근 인증을 보존하는 것이 좋습니다.

완료 후 Gateway를 다시 시작하고 확인합니다.

openclaw gateway restart
openclaw gateway status

Gateway가 시작되지 않으면 먼저 openclaw config validate와 openclaw doctor를 실행합니다. 공개 인터넷 수신을 허용하거나 인증을 비활성화하여 임시로 우회하지 않습니다.

실행 및 연결 검증

Control UI 또는 터미널 TUI 열기

브라우저 Control UI를 사용합니다.

openclaw dashboard

또는 터미널에서 로컬 Gateway에 연결합니다.

openclaw tui

기본 텍스트 응답 검증

처음에는 다음 내용을 입력합니다.

AGTCloud 연결 성공이라고만 응답해 주세요. 어떤 도구도 호출하지 마세요.

지정한 텍스트가 반환되면 Gateway, AGTCloud Provider, API Key 및 모델 ID의 기본 연결이 설정된 것입니다.

선택 사항: 읽기 전용 도구 기능 검증

일반 대화가 안정적인지 확인한 뒤 안전한 테스트 프로젝트에 다음을 입력합니다.

README.md를 읽고 프로젝트의 용도를 세 가지로 요약해 주세요. 어떤 파일도 수정하거나 다른 명령을 실행하지 마세요.

OpenClaw가 제안하는 각 작업을 검사하고 대상 파일을 읽는 데 필요한 권한만 승인합니다. 일반 대화는 성공하지만 이 단계가 실패하면 보통 대상 모델 또는 현재 호환 진입점이 필요한 도구 호출 구조를 아직 완전히 지원하지 않는다는 뜻입니다.

모델 추가 또는 전환

OpenClaw의 모델 참조 형식은 provider/model이므로 AGTCloud 모델은 다음과 같이 표시합니다.

agtcloud/MODEL_ID

Custom Provider가 AGTCloud /v1/models의 모든 결과를 자동으로 읽는다고 보장하지 않습니다. 모델을 추가하려면 새 모델 객체를 models.providers.agtcloud.models에 병합하고 다음 명령으로 전환합니다.

openclaw models set agtcloud/MODEL_ID
openclaw gateway restart

모델 이름을 변경한 뒤에는 현재 API Key에 모델이 표시되며 해당 프로토콜을 지원하는지 확인합니다. 그렇지 않으면 모델이 없거나 사용이 허용되지 않는다는 오류가 발생할 수 있습니다.

자주 묻는 질문

원인을 찾기 어려우면 OpenClaw 버전, 요청 시각, API Base URL, Provider, 모델 ID, HTTP 상태 및 민감 정보를 제거한 오류 내용을 기록하고 오류 및 문제 해결을 확인합니다. .env, 전체 설정 백업 또는 API Key를 제출하지 않습니다.

보안 권장 사항

• OpenClaw는 신뢰할 수 있는 단일 운영자를 위한 설계이므로 보호되지 않은 Gateway를 공개 인터넷에 노출하지 않습니다.
• 첫 테스트는 격리 디렉터리에서 수행하고 파일, 명령, 네트워크 및 도구 권한을 개별적으로 검토합니다.
• API Key를 저장소, 스크린샷, 세션 내보내기, 로그 또는 공유 설정에 저장하지 않습니다.
• 메시징 채널, 다른 사용자 또는 자동화 작업을 연동하기 전에 OpenClaw 공식 보안 및 샌드박스 문서를 읽습니다.

다음 단계

• API Key 및 인증
• Chat Completions API Reference
• 오류 및 문제 해결
• OpenClaw 공식 문서