CLI 설정 참조

이 페이지는 openclaw onboard의 전체 참조 문서입니다. 짧은 가이드는 온보딩(CLI)을 참조하세요.

# 마법사가 하는 일

로컬 모드(기본값)는 다음을 안내합니다.

• 모델 및 인증 설정(OpenAI Code 구독 OAuth, Anthropic Claude CLI 또는 API 키, 그리고 MiniMax, GLM, Ollama, Moonshot, StepFun, AI Gateway 옵션)
• 워크스페이스 위치 및 부트스트랩 파일
• Gateway 설정(포트, 바인드, 인증, Tailscale)
• 채널 및 제공자(Telegram, WhatsApp, Discord, Google Chat, Mattermost, Signal, BlueBubbles 및 기타 번들 채널 Plugin)
• 데몬 설치(LaunchAgent, systemd 사용자 유닛 또는 Startup 폴더 폴백이 있는 네이티브 Windows Scheduled Task)
• 상태 확인
• Skills 설정

원격 모드는 이 머신이 다른 위치의 Gateway에 연결하도록 구성합니다. 원격 호스트에는 아무것도 설치하거나 수정하지 않습니다.

# 로컬 흐름 세부 정보

# 원격 모드 세부 정보

원격 모드는 이 머신이 다른 위치의 Gateway에 연결하도록 구성합니다.

설정하는 항목:

• 원격 Gateway URL(ws://...)
• 원격 Gateway 인증이 필요한 경우 토큰(권장)

# 인증 및 모델 옵션

모델 동작:

• 감지된 옵션에서 기본 모델을 선택하거나 제공자와 모델을 수동으로 입력합니다.
• 사용자 지정 제공자 온보딩은 일반적인 모델 ID에 대해 이미지 지원을 추론하고 모델 이름을 알 수 없는 경우에만 묻습니다.
• 온보딩이 제공자 인증 선택에서 시작되면 모델 선택기는 해당 제공자를 자동으로 우선합니다. Volcengine 및 BytePlus의 경우 같은 선호도는 해당 coding-plan 변형(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)
• 대화형 참조 모드는 저장 전에 빠른 사전 검증을 실행합니다.
  • Env refs: 현재 온보딩 환경에서 변수 이름 + 비어 있지 않은 값을 검증합니다.
  • Provider refs: 제공자 구성을 검증하고 요청된 id를 확인합니다.
  • 사전 검증에 실패하면 온보딩이 오류를 표시하고 재시도할 수 있게 합니다.
• 비대화형 모드에서 --secret-input-mode ref는 env 기반만 지원합니다.
  • 온보딩 프로세스 환경에서 제공자 env var를 설정하세요.
  • 인라인 키 플래그(예: --openai-api-key)는 해당 env var가 설정되어 있어야 합니다. 그렇지 않으면 온보딩이 빠르게 실패합니다.
  • 사용자 지정 제공자의 경우 비대화형 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>.
• 기존 일반 텍스트 설정은 변경 없이 계속 작동합니다.

# 출력 및 내부 항목

~/.openclaw/openclaw.json의 일반적인 필드:

• agents.defaults.workspace
• --skip-bootstrap이 전달된 경우 agents.defaults.skipBootstrap
• agents.defaults.model / models.providers(Minimax를 선택한 경우)
• tools.profile(설정되지 않은 경우 로컬 온보딩은 기본값으로 "coding"을 사용하며, 기존의 명시적 값은 보존됨)
• gateway.*(mode, bind, auth, tailscale)
• session.dmScope(설정되지 않은 경우 로컬 온보딩은 기본값으로 per-channel-peer를 사용하며, 기존의 명시적 값은 보존됨)
• channels.telegram.botToken, channels.discord.token, channels.matrix.*, channels.signal.*, channels.imessage.*
• 프롬프트에서 선택한 경우 채널 허용 목록(Slack, Discord, Matrix, Microsoft Teams)(가능한 경우 이름은 ID로 해석됨)
• skills.install.nodeManager
  • setup --node-manager 플래그는 npm, pnpm 또는 bun을 허용합니다.
  • 수동 구성에서는 나중에 여전히 skills.install.nodeManager: "yarn"을 설정할 수 있습니다.
• wizard.lastRunAt
• wizard.lastRunVersion
• wizard.lastRunCommit
• wizard.lastRunCommand
• wizard.lastRunMode

openclaw agents add는 agents.list[] 및 선택적 bindings를 작성합니다.

WhatsApp 자격 증명은 ~/.openclaw/credentials/whatsapp/<accountId>/ 아래에 저장됩니다. 세션은 ~/.openclaw/agents/<agentId>/sessions/ 아래에 저장됩니다.

Gateway 마법사 RPC:

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

클라이언트(macOS 앱 및 Control UI)는 온보딩 로직을 다시 구현하지 않고도 단계를 렌더링할 수 있습니다.

Signal 설정 동작:

• 적절한 릴리스 자산 다운로드
• ~/.openclaw/tools/signal-cli/<version>/ 아래에 저장
• 구성에 channels.signal.cliPath 작성
• JVM 빌드에는 Java 21 필요
• 사용 가능한 경우 네이티브 빌드 사용
• Windows는 WSL2를 사용하며 WSL 내부에서 Linux signal-cli 흐름을 따름

# 관련 문서

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