​

CLI 설정 참조

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

​

마법사가 수행하는 작업

local 모드(기본값)는 다음 항목을 안내합니다:

• 모델 및 인증 설정(OpenAI Code 구독 OAuth, Anthropic Claude CLI 또는 API 키, 그리고 MiniMax, GLM, Ollama, Moonshot, StepFun, AI Gateway 옵션)
• Workspace 위치 및 bootstrap 파일
• Gateway 설정(포트, bind, auth, tailscale)
• 채널 및 provider(Telegram, WhatsApp, Discord, Google Chat, Mattermost, Signal, BlueBubbles 및 기타 번들 채널 plugin)
• daemon 설치(LaunchAgent, systemd user unit 또는 네이티브 Windows Scheduled Task와 Startup-folder 대체 방식)
• 상태 검사
• Skills 설정

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

​

local 흐름 세부 정보

​

remote 모드 세부 정보

remote 모드는 이 머신이 다른 곳의 gateway에 연결하도록 구성합니다. 설정하는 항목:

• 원격 gateway URL (ws://...)
• 원격 gateway auth가 필요한 경우 토큰(권장)

​

인증 및 모델 옵션

모델 동작:

• 감지된 옵션에서 기본 모델을 선택하거나, provider와 모델을 수동으로 입력합니다.
• 온보딩이 provider auth 선택에서 시작되면 모델 선택기는 자동으로 해당 provider를 우선시합니다. Volcengine 및 BytePlus의 경우 같은 우선순위가 해당 coding-plan 변형(volcengine-plan/*, byteplus-plan/*)에도 적용됩니다.
• 이 선호 provider 필터가 비게 되면 선택기는 모델이 전혀 보이지 않도록 하지 않고 전체 카탈로그로 대체합니다.
• 마법사는 모델 검사를 실행하며, 구성된 모델을 알 수 없거나 auth가 없으면 경고합니다.

자격 증명 및 profile 경로:

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

자격 증명 저장 모드:

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

​

출력 및 내부 동작

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

• agents.defaults.workspace
• agents.defaults.model / models.providers (MiniMax를 선택한 경우)
• tools.profile (local 온보딩은 설정되지 않은 경우 기본값으로 "coding"을 사용하며, 기존의 명시적 값은 유지됨)
• gateway.* (mode, bind, auth, tailscale)
• session.dmScope (local 온보딩은 설정되지 않은 경우 이를 기본값 per-channel-peer로 설정하며, 기존의 명시적 값은 유지됨)
• channels.telegram.botToken, channels.discord.token, channels.matrix.*, channels.signal.*, channels.imessage.*
• 프롬프트 중 선택하면 채널 allowlist(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 wizard 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