​

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 사용자 유닛 또는 기본 Windows Scheduled Task와 Startup 폴더 대체 경로)
• 상태 점검
• Skills 설정

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

​

로컬 흐름 세부사항

​

원격 모드 세부사항

원격 모드는 이 컴퓨터가 다른 위치의 gateway에 연결되도록 구성합니다. 설정하는 항목:

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

​

인증 및 모델 옵션

모델 동작:

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

자격 증명 및 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)는 해당 환경 변수가 설정되어 있어야 하며, 그렇지 않으면 온보딩이 즉시 실패합니다.
  • 사용자 지정 제공자의 경우 비대화형 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
• 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.*
• 프롬프트 중 옵트인한 경우의 채널 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 마법사 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