Onboarding Wizard (CLI)

Onboarding wizardは、macOS、Linux、またはWindows（WSL2経由、強く推奨）でOpenClawをセットアップするための推奨方法です。 ローカルGatewayまたはリモートGateway接続に加えて、channels、skills、workspaceのデフォルト設定を1つのガイド付きフローで構成します。

主要なエントリーポイント：

openclaw onboard

最速の初回チャット：Control UIを開く（channelセットアップ不要）。openclaw dashboardを実行してブラウザでチャットします。ドキュメント：Dashboard

再設定のフォローアップ：

openclaw configure

推奨：Brave Search API keyを設定することで、エージェントがweb_searchを使用できるようになります（web_fetchはkeyなしで動作します）。最も簡単な方法：openclaw configure --section webを実行するとtools.web.search.apiKeyに保存されます。ドキュメント：Web tools

QuickStart vs Advanced

ウィザードはQuickStart（デフォルト）またはAdvanced（完全制御）から始まります。

QuickStartはデフォルトを維持します：

• ローカルgateway（loopback）
• Workspaceデフォルト（または既存のworkspace）
• Gatewayポート18789
• Gateway認証Token（自動生成、loopbackでも）
• Tailscale公開オフ
• Telegram + WhatsApp DMsはデフォルトでallowlist（電話番号の入力を求められます）

Advancedは全てのステップを公開します（mode、workspace、gateway、channels、daemon、skills）。

ウィザードの機能

**ローカルモード（デフォルト）**では以下を実行します：

• Model/Auth（OpenAI Code (Codex) subscription OAuth、Anthropic API key（推奨）またはsetup-token（貼り付け）、さらにMiniMax/GLM/Moonshot/AI Gatewayオプション）
• Workspace locationとbootstrapファイル
• Gateway設定（port/bind/auth/tailscale）
• Providers（Telegram、WhatsApp、Discord、Google Chat、Mattermost（plugin）、Signal）
• Daemonインストール（LaunchAgent / systemd user unit）
• ヘルスチェック
• Skills（推奨）

リモートモードは、ローカルクライアントが他の場所のGatewayに接続するように設定するだけです。 リモートホストに対してインストールや変更は行いません。

より分離されたエージェント（個別のworkspace + sessions + auth）を追加するには：

openclaw agents add <name>

ヒント：--jsonは非インタラクティブモードを意味しません。スクリプトには--non-interactive（および--workspace）を使用してください。

フロー詳細（ローカル）

1. 既存設定の検出

   • ~/.openclaw/openclaw.jsonが存在する場合、Keep / Modify / Resetを選択します。
   • ウィザードを再実行しても、明示的にResetを選択しない限り（または--resetを渡さない限り）何も消去されません。
   • 設定が無効であるか、レガシーキーが含まれている場合、ウィザードは停止し、続行する前にopenclaw doctorを実行するよう求めます。
   • Resetはtrashを使用し（決してrmは使用しません）、スコープを提供します：
     • Configのみ
     • Config + credentials + sessions
     • フルリセット（workspaceも削除）

2. Model/Auth

   • Anthropic API key（推奨）：ANTHROPIC_API_KEYが存在する場合は使用し、存在しない場合はkeyの入力を求め、daemonが使用できるように保存します。
   • Anthropic OAuth (Claude Code CLI)：macOSではウィザードはKeychain item "Claude Code-credentials"をチェックします（launchdの起動がブロックされないように"Always Allow"を選択）。Linux/Windowsでは~/.claude/.credentials.jsonが存在する場合は再利用します。
   • Anthropic token（setup-tokenを貼り付け）：任意のマシンでclaude setup-tokenを実行し、tokenを貼り付けます（名前を付けることができます。空白=default）。
   • OpenAI Code (Codex) subscription (Codex CLI)：~/.codex/auth.jsonが存在する場合、ウィザードはそれを再利用できます。
   • OpenAI Code (Codex) subscription (OAuth)：ブラウザフロー。code#stateを貼り付けます。
     • modelが未設定またはopenai/*の場合、agents.defaults.modelをopenai-codex/gpt-5.2に設定します。
   • OpenAI API key：OPENAI_API_KEYが存在する場合は使用し、存在しない場合はkeyの入力を求め、launchdが読み取れるように~/.openclaw/.envに保存します。
   • OpenCode Zen (multi-model proxy)：OPENCODE_API_KEY（またはOPENCODE_ZEN_API_KEY）の入力を求めます（https://opencode.ai/authで取得）。
   • API key：keyを保存します。
   • Vercel AI Gateway (multi-model proxy)：AI_GATEWAY_API_KEYの入力を求めます。
   • 詳細：Vercel AI Gateway
   • MiniMax M2.1：設定は自動的に書き込まれます。
   • 詳細：MiniMax
   • Synthetic (Anthropic-compatible)：SYNTHETIC_API_KEYの入力を求めます。
   • 詳細：Synthetic
   • Moonshot (Kimi K2)：設定は自動的に書き込まれます。
   • Kimi Code：設定は自動的に書き込まれます。
   • 詳細：Moonshot AI (Kimi + Kimi Code)
   • Skip：まだ認証が設定されていません。
   • 検出されたオプションからデフォルトのmodelを選択します（または手動でprovider/modelを入力）。
   • ウィザードはmodelチェックを実行し、設定されたmodelが不明または認証が欠落している場合に警告します。

• OAuth credentialsは~/.openclaw/credentials/oauth.jsonに、auth profilesは~/.openclaw/agents/<agentId>/agent/auth-profiles.json（API keys + OAuth）に保存されます。
• 詳細：/concepts/oauth

3. Workspace

   • デフォルト~/.openclaw/workspace（設定可能）。
   • エージェントのbootstrap ritualに必要なworkspaceファイルをシードします。
   • 完全なworkspaceレイアウト + バックアップガイド：Agent workspace

4. Gateway

   • Port、bind、authモード、tailscale公開。
   • Auth推奨：ローカルWSクライアントが認証を必要とするように、loopbackでもTokenを維持します。
   • 全てのローカルプロセスを完全に信頼している場合のみ、認証を無効にします。
   • 非loopback bindsは依然として認証が必要です。

5. Channels

• WhatsApp：オプションのQRログイン。
• Telegram：bot token。
• Discord：bot token。
• Google Chat：service account JSONとwebhook audience。
• Mattermost (plugin)：bot tokenとbase URL。
• Signal：オプションのsignal-cliインストールとアカウント設定。
• iMessage：ローカルimsg CLIパスとDBアクセス。
• DMセキュリティ：デフォルトはペアリングです。最初のDMはコードを送信します。openclaw pairing approve <channel> <code>で承認するか、allowlistsを使用します。

6. Daemonインストール

   • macOS：LaunchAgent
     • ログイン済みのユーザーセッションが必要です。ヘッドレスの場合は、カスタムLaunchDaemon（未提供）を使用します。
   • Linux（およびWSL2経由のWindows）：systemd user unit
     • ウィザードはloginctl enable-linger <user>を介してlingeringを有効にしようとするため、ログアウト後もGatewayは稼働し続けます。
     • sudoを求められる場合があります（/var/lib/systemd/lingerに書き込みます）。まずsudoなしで試行します。
   • Runtimeの選択： Node（推奨。WhatsApp/Telegramには必須）。Bunは推奨されません。

7. ヘルスチェック

   • Gatewayを起動し（必要な場合）、openclaw healthを実行します。
   • ヒント：openclaw status --deepはstatusの出力にgatewayヘルスプローブを追加します（到達可能なgatewayが必要）。

8. Skills（推奨）

   • 利用可能なskillsを読み取り、要件をチェックします。
   • nodeマネージャーを選択できます：npm / pnpm（bunは推奨されません）。
   • オプションの依存関係をインストールします（一部はmacOSでHomebrewを使用）。

9. 完了

   • 概要と次のステップ（追加機能のためのiOS/Android/macOSアプリを含む）。

• GUIが検出されない場合、ウィザードはブラウザを開く代わりに、Control UI用のSSHポートフォワード指示を出力します。
• Control UIアセットが欠落している場合、ウィザードはそれらをビルドしようとします。フォールバックはpnpm ui:build（UI depsを自動インストール）です。

リモートモード

リモートモードは、ローカルクライアントが他の場所のGatewayに接続するように設定します。

設定する内容：

• リモートGateway URL（ws://...）
• リモートGatewayが認証を必要とする場合のToken（推奨）

注意事項：

• リモートインストールやdaemon変更は実行されません。
• Gatewayがloopbackのみの場合は、SSHトンネリングまたはtailnetを使用します。
• ディスカバリーヒント：
  • macOS：Bonjour（dns-sd）
  • Linux：Avahi（avahi-browse）

別のエージェントを追加

openclaw agents add <name>を使用して、独自のworkspace、sessions、auth profilesを持つ別のエージェントを作成します。--workspaceなしで実行すると、ウィザードが起動します。

設定内容：

• agents.list[].name
• agents.list[].workspace
• agents.list[].agentDir

注意事項：

• デフォルトのworkspacesは~/.openclaw/workspace-<agentId>に従います。
• 受信メッセージをルーティングするためにbindingsを追加します（ウィザードがこれを実行できます）。
• 非インタラクティブフラグ：--model、--agent-dir、--bind、--non-interactive。

非インタラクティブモード

--non-interactiveを使用して、オンボーディングを自動化またはスクリプト化します：

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice apiKey \
  --anthropic-api-key "$ANTHROPIC_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback \
  --install-daemon \
  --daemon-runtime node \
  --skip-skills

機械可読の概要には--jsonを追加します。

Geminiの例：

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice gemini-api-key \
  --gemini-api-key "$GEMINI_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Z.AIの例：

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice zai-api-key \
  --zai-api-key "$ZAI_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Vercel AI Gatewayの例：

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice ai-gateway-api-key \
  --ai-gateway-api-key "$AI_GATEWAY_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Moonshotの例：

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice moonshot-api-key \
  --moonshot-api-key "$MOONSHOT_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Syntheticの例：

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice synthetic-api-key \
  --synthetic-api-key "$SYNTHETIC_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

OpenCode Zenの例：

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice opencode-zen \
  --opencode-zen-api-key "$OPENCODE_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

エージェント追加（非インタラクティブ）の例：

openclaw agents add work \
  --workspace ~/.openclaw/workspace-work \
  --model openai/gpt-5.2 \
  --bind whatsapp:biz \
  --non-interactive \
  --json

Gateway wizard RPC

GatewayはRPC（wizard.start、wizard.next、wizard.cancel、wizard.status）を介してウィザードフローを公開します。 クライアント（macOSアプリ、Control UI）は、オンボーディングロジックを再実装することなくステップをレンダリングできます。

Signal設定（signal-cli）

ウィザードはGitHub releasesからsignal-cliをインストールできます：

• 適切なreleaseアセットをダウンロードします。
• ~/.openclaw/tools/signal-cli/<version>/に保存します。
• 設定にchannels.signal.cliPathを書き込みます。

注意事項：

• JVMビルドにはJava 21が必要です。
• 利用可能な場合はネイティブビルドが使用されます。
• WindowsではWSL2を使用します。signal-cliのインストールはWSL内部のLinuxフローに従います。

ウィザードが書き込む内容

~/.openclaw/openclaw.jsonの典型的なフィールド：

• agents.defaults.workspace
• agents.defaults.model / models.providers（Minimaxを選択した場合）
• gateway.*（mode、bind、auth、tailscale）
• channels.telegram.botToken、channels.discord.token、channels.signal.*、channels.imessage.*
• Channelのallowlists（Slack/Discord/Matrix/Microsoft Teams）プロンプト中にオプトインした場合（可能な場合は名前がIDに解決されます）。
• skills.install.nodeManager
• wizard.lastRunAt
• wizard.lastRunVersion
• wizard.lastRunCommit
• wizard.lastRunCommand
• wizard.lastRunMode

openclaw agents addはagents.list[]とオプションのbindingsを書き込みます。

WhatsApp credentialsは~/.openclaw/credentials/whatsapp/<accountId>/に保存されます。 Sessionsは~/.openclaw/agents/<agentId>/sessions/に保存されます。

一部のchannelsはpluginsとして提供されます。オンボーディング中に選択すると、ウィザードは設定前にインストール（npmまたはローカルパス）を求めます。

関連ドキュメント

• macOSアプリのオンボーディング：Onboarding
• 設定リファレンス：Gateway configuration
• Providers：WhatsApp、Telegram、Discord、Google Chat、Signal、iMessage
• Skills：Skills、Skills config