CLI 설정 참조 문서

​

마법사가 수행하는 작업

• 모델 및 인증 설정(Anthropic, OpenAI Code 구독 OAuth, xAI, OpenCode, 사용자 지정 엔드포인트 및 기타 공급자 소유 인증 흐름)
• 워크스페이스 위치 및 부트스트랩 파일
• Gateway 설정(포트, 바인드, 인증, Tailscale)
• 채널 및 공급자(Discord, Feishu, Google Chat, iMessage, Mattermost, Microsoft Teams, QQ Bot, Signal, Slack, Telegram, WhatsApp 및 기타 번들 또는 Plugin 채널)
• 웹 검색 공급자(선택 사항)
• 데몬 설치(LaunchAgent, systemd 사용자 유닛 또는 시작 프로그램 폴더 대체 경로를 사용하는 네이티브 Windows 예약 작업)
• 상태 검사
• Skills 설정

​

로컬 흐름 세부 정보

​

원격 모드 세부 정보

• 원격 Gateway URL(ws://... 또는 wss://...)
• 원격 Gateway 구성과 일치하는 토큰, 비밀번호 또는 인증 없음

​

인증 및 모델 옵션

• 감지된 옵션에서 기본 모델을 선택하거나 제공자와 모델을 직접 입력합니다.
• 제공자 인증 선택에서 온보딩을 시작하면 모델 선택기가 해당 제공자를 자동으로 우선합니다. Volcengine과 BytePlus의 경우 동일한 우선 설정이 해당 코딩 플랜 변형(volcengine-plan/*, byteplus-plan/*)에도 적용됩니다.
• 해당 우선 제공자 필터의 결과가 비어 있으면 모델을 표시하지 않는 대신 전체 카탈로그로 대체합니다.
• 마법사가 모델 검사를 실행하고 구성된 모델을 알 수 없거나 인증이 누락된 경우 경고합니다.

• 인증 프로필(API 키 + OAuth): ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
• 레거시 OAuth 가져오기: ~/.openclaw/credentials/oauth.json

• 기본 온보딩 동작은 API 키를 인증 프로필에 일반 텍스트 값으로 영구 저장합니다.
• --secret-input-mode ref은 일반 텍스트 키 저장 대신 참조 모드를 활성화합니다. 대화형 설정에서는 다음 중 하나를 선택할 수 있습니다.
  • 환경 변수 참조(예: keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" })
  • 제공자 별칭 + ID를 사용하는 구성된 제공자 참조(file 또는 exec)
• 대화형 참조 모드는 저장하기 전에 빠른 사전 검증을 실행합니다.
  • 환경 변수 참조: 현재 온보딩 환경에서 변수 이름과 비어 있지 않은 값을 검증합니다.
  • 제공자 참조: 제공자 구성을 검증하고 요청된 ID를 확인합니다.
  • 사전 검증에 실패하면 온보딩에서 오류를 표시하고 다시 시도할 수 있게 합니다.
• 비대화형 모드에서 --secret-input-mode ref은 환경 변수 기반으로만 작동합니다.
  • 온보딩 프로세스 환경에 제공자 환경 변수를 설정하십시오.
  • 인라인 키 플래그(예: --openai-api-key)를 사용하려면 해당 환경 변수가 설정되어 있어야 하며, 그렇지 않으면 온보딩이 즉시 실패합니다.
  • 사용자 지정 제공자의 경우 비대화형 ref 모드는 models.providers.<id>.apiKey을 { source: "env", provider: "default", id: "CUSTOM_API_KEY" }으로 저장합니다.
  • 이 사용자 지정 제공자 사례에서는 --custom-api-key을 사용하려면 CUSTOM_API_KEY이 설정되어 있어야 하며, 그렇지 않으면 온보딩이 즉시 실패합니다.
• Gateway 인증 자격 증명은 대화형 설정에서 일반 텍스트와 SecretRef 옵션을 지원합니다.
  • 토큰 모드: 일반 텍스트 토큰 생성/저장(기본값) 또는 SecretRef 사용.
  • 비밀번호 모드: 일반 텍스트 또는 SecretRef.
• 비대화형 토큰 SecretRef 경로: --gateway-token-ref-env <ENV_VAR>.
• 기존 일반 텍스트 설정은 변경 없이 계속 작동합니다.

​

출력 및 내부 구조

• agents.defaults.workspace
• --skip-bootstrap이 전달된 경우 agents.defaults.skipBootstrap
• agents.defaults.model / models.providers(Minimax를 선택한 경우)
• tools.profile(설정되지 않은 경우 로컬 온보딩의 기본값은 "coding"이며, 기존에 명시적으로 설정된 값은 유지됩니다)
• gateway.*(모드, 바인드, 인증, Tailscale)
• session.dmScope(설정되지 않은 경우 로컬 온보딩에서 기본값을 per-channel-peer으로 설정하며, 기존에 명시적으로 설정된 값은 유지됩니다)
• channels.telegram.botToken, channels.discord.token, channels.matrix.*, channels.signal.*, channels.imessage.*
• 프롬프트에서 사용에 동의한 경우 채널 허용 목록(Discord, iMessage, Signal, Slack, Telegram, WhatsApp)을 구성하며, Discord와 Slack은 입력한 이름을 ID로 확인하기도 합니다
• skills.install.nodeManager
  • setup --node-manager 플래그는 npm, pnpm 또는 bun을 허용합니다.
  • 나중에 수동 구성으로 skills.install.nodeManager: "yarn"을 설정할 수도 있습니다.
• wizard.lastRunAt
• wizard.lastRunVersion
• wizard.lastRunCommit
• wizard.lastRunCommand
• wizard.lastRunMode
• wizard.securityAcknowledgedAt

​

비대화형 설정

openclaw onboard --non-interactive --accept-risk \
  --auth-choice apiKey \
  --anthropic-api-key "$ANTHROPIC_API_KEY"

​

Gateway 마법사 RPC

• wizard.start
• wizard.next
• wizard.cancel
• wizard.status

​

Signal 설정 동작

• 공식 signal-cli GitHub 릴리스에서 적절한 릴리스 아티팩트를 다운로드합니다(네이티브 빌드, Linux x86-64만 해당)
• 다른 플랫폼(macOS, x64가 아닌 Linux)에서는 대신 Homebrew를 통해 설치합니다
• 릴리스 아티팩트 설치를 ~/.openclaw/tools/signal-cli/<version>/ 아래에 저장합니다
• 구성에 channels.signal.cliPath을 작성합니다
• 네이티브 Windows는 아직 지원되지 않습니다. Linux 설치 경로를 사용하려면 WSL2 내부에서 온보딩을 실행하십시오

​

관련 문서

• 온보딩 허브: 온보딩(CLI)
• 자동화 및 스크립트: CLI 자동화
• 명령어 참조: openclaw onboard