CLIオンボーディングリファレンス

このページは openclaw onboard の完全なリファレンスです。 簡易ガイドについては、オンボーディングウィザード（CLI）をご覧ください。

ウィザードの処理内容

ローカルモード（デフォルト）では以下の手順を案内します。

• モデルと認証のセットアップ（OpenAI Code サブスクリプション OAuth、Anthropic API キーまたはセットアップトークン、加えて MiniMax、GLM、Ollama、Moonshot、AI Gateway のオプション）
• ワークスペースの場所とブートストラップファイル
• Gateway 設定（ポート、バインド、認証、Tailscale）
• チャンネルとプロバイダー（Telegram、WhatsApp、Discord、Google Chat、Mattermost プラグイン、Signal）
• デーモンのインストール（LaunchAgent または systemd ユーザーユニット）
• ヘルスチェック
• スキルのセットアップ

リモートモードでは、このマシンを別の場所にある Gateway に接続するよう設定します。 リモートホスト上のインストールや変更は一切行いません。

ローカルフローの詳細

ステップ1：既存設定の検出

- `~/.openclaw/openclaw.json` が存在する場合、保持、変更、リセットのいずれかを選択。
- ウィザードを再実行しても、明示的にリセットを選択（または `--reset` を指定）しない限り何も消去されません。
- CLI の `--reset` はデフォルトで `config+creds+sessions` が対象。ワークスペースも含めるには `--reset-scope full` を使用。
- 設定が無効だったりレガシーキーが含まれている場合、ウィザードは続行前に `openclaw doctor` の実行を求めます。
- リセットは `trash` を使用し、以下のスコープを提供：
  - 設定のみ
  - 設定 + 認証情報 + セッション
  - フルリセット（ワークスペースも削除）

ステップ2：モデルと認証

- オプションの全一覧は[認証とモデルのオプション](#認証とモデルのオプション)を参照。

ステップ3：ワークスペース

- デフォルト `~/.openclaw/workspace`（変更可能）。
- 初回ブートストラップに必要なワークスペースファイルを生成。
- ワークスペースの構成：[エージェントワークスペース](/docs/concepts/agent-workspace)。

ステップ4：Gateway

- ポート、バインド、認証モード、Tailscale 公開の設定。
- 推奨：ループバックでもトークン認証を有効にし、ローカルの WS クライアントにも認証を要求。
- トークンモードでは、対話的なオンボーディングで以下を選択可能：
  - **平文トークンの生成・保存**（デフォルト）
  - **SecretRef を使用**（オプトイン）
- パスワードモードでも、平文または SecretRef の保存が可能。
- 非対話のトークン SecretRef パス：`--gateway-token-ref-env <ENV_VAR>`。
  - オンボーディングプロセスの環境に空でない環境変数が必要。
  - `--gateway-token` とは併用不可。
- 認証の無効化は、すべてのローカルプロセスを完全に信頼できる場合のみ。
- 非ループバックバインドでは認証が必須。

ステップ5：チャンネル

- [WhatsApp](/docs/channels/whatsapp)：オプションの QR ログイン
- [Telegram](/docs/channels/telegram)：ボットトークン
- [Discord](/docs/channels/discord)：ボットトークン
- [Google Chat](/docs/channels/googlechat)：サービスアカウント JSON + Webhook オーディエンス
- [Mattermost](/docs/channels/mattermost) プラグイン：ボットトークン + ベース URL
- [Signal](/docs/channels/signal)：オプションの `signal-cli` インストール + アカウント設定
- [BlueBubbles](/docs/channels/bluebubbles)：iMessage 用の推奨オプション。サーバー URL + パスワード + Webhook
- [iMessage](/docs/channels/imessage)：レガシーの `imsg` CLI パス + DB アクセス
- DM セキュリティ：デフォルトはペアリング。最初の DM でコードが送信され、
  `openclaw pairing approve <channel> <code>` で承認するか、許可リストを使用。

ステップ6：デーモンのインストール

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

ステップ7：ヘルスチェック

- Gateway を起動（必要に応じて）し、`openclaw health` を実行。
- `openclaw status --deep` でステータス出力に Gateway ヘルスプローブを追加。

ステップ8：スキル

- 利用可能なスキルを読み込み、要件を確認。
- ノードマネージャーの選択：npm または pnpm（bun は非推奨）。
- オプションの依存関係をインストール（macOS では Homebrew を使う場合あり）。

ステップ9：完了

- サマリーと次のステップ（iOS、Android、macOS アプリのオプションを含む）。

注意： GUI が検出されない場合、ウィザードはブラウザを開く代わりにコントロール UI 用の SSH ポートフォワード手順を表示します。 コントロール UI のアセットがない場合、ウィザードはビルドを試みます。フォールバックは pnpm ui:build（UI の依存関係を自動インストール）。

リモートモードの詳細

リモートモードでは、このマシンを別の場所にある Gateway に接続するよう設定します。

情報： リモートモードはリモートホスト上のインストールや変更を一切行いません。

設定する項目：

• リモート Gateway の URL（ws://...）
• リモート Gateway の認証が必要な場合はトークン（推奨）

注意：

• Gateway がループバック専用の場合、SSH トンネリングまたは Tailnet を使用してください。
• ディスカバリーのヒント：
  • macOS：Bonjour（dns-sd）
  • Linux：Avahi（avahi-browse）

認証とモデルのオプション

`ANTHROPIC_API_KEY` が設定されていればそれを使用し、なければキーの入力を求め、デーモン用に保存します。

- macOS：Keychain の "Claude Code-credentials" を確認
- Linux および Windows：`~/.claude/.credentials.json` が存在すれば再利用

macOS では、launchd の起動がブロックされないように「常に許可」を選択してください。

任意のマシンで `claude setup-token` を実行し、トークンを貼り付けてください。
名前を付けられます。空欄にするとデフォルト名が使用されます。

`~/.codex/auth.json` が存在する場合、ウィザードはそれを再利用できます。

ブラウザフロー。`code#state` を貼り付けてください。

モデルが未設定または `openai/*` の場合、`agents.defaults.model` を `openai-codex/gpt-5.4` に設定します。

`OPENAI_API_KEY` が設定されていればそれを使用し、なければキーの入力を求め、認証プロファイルに保存します。

モデルが未設定、`openai/*`、または `openai-codex/*` の場合、`agents.defaults.model` を `openai/gpt-5.1-codex` に設定します。

`XAI_API_KEY` の入力を求め、xAI をモデルプロバイダーとして設定します。

`OPENCODE_API_KEY`（または `OPENCODE_ZEN_API_KEY`）の入力を求め、Zen または Go カタログを選択できます。
セットアップ URL：[opencode.ai/auth](https://opencode.ai/auth)。

キーを保存します。

`AI_GATEWAY_API_KEY` の入力を求めます。
詳細：[Vercel AI Gateway](/docs/providers/vercel-ai-gateway)。

アカウント ID、ゲートウェイ ID、`CLOUDFLARE_AI_GATEWAY_API_KEY` の入力を求めます。
詳細：[Cloudflare AI Gateway](/docs/providers/cloudflare-ai-gateway)。

設定は自動的に書き込まれます。
詳細：[MiniMax](/docs/providers/minimax)。

`SYNTHETIC_API_KEY` の入力を求めます。
詳細：[Synthetic](/docs/providers/synthetic)。

ベース URL（デフォルト `http://127.0.0.1:11434`）の入力を求め、その後 Cloud + Local または Local モードを選択。
利用可能なモデルを検出し、デフォルトを提案します。
詳細：[Ollama](/docs/providers/ollama)。

Moonshot（Kimi K2）と Kimi Coding の設定は自動的に書き込まれます。
詳細：[Moonshot AI（Kimi + Kimi Coding）](/docs/providers/moonshot)。

OpenAI 互換および Anthropic 互換のエンドポイントに対応。

対話的なオンボーディングでは、他のプロバイダーの API キーフローと同じ保存方法を選択できます：
- **API キーを今すぐ入力**（平文）
- **シークレット参照を使用**（env 参照または設定済みプロバイダー参照。プリフライト検証付き）

非対話フラグ：
- `--auth-choice custom-api-key`
- `--custom-base-url`
- `--custom-model-id`
- `--custom-api-key`（オプション。フォールバック先は `CUSTOM_API_KEY`）
- `--custom-provider-id`（オプション）
- `--custom-compatibility <openai|anthropic>`（オプション。デフォルト `openai`）

認証を未設定のままにします。

モデルの動作：

• 検出されたオプションからデフォルトモデルを選択するか、プロバイダーとモデルを手動で入力。
• ウィザードはモデルチェックを実行し、設定されたモデルが不明または認証が不足している場合は警告します。

認証情報とプロファイルのパス：

• OAuth 認証情報：~/.openclaw/credentials/oauth.json
• 認証プロファイル（APIキー + OAuth）：~/.openclaw/agents/<agentId>/agent/auth-profiles.json

認証情報の保存モード：

• デフォルトのオンボーディング動作では、API キーを平文の値として認証プロファイルに保存します。
• --secret-input-mode ref を使用すると、平文のキー保存の代わりに参照モードを有効化します。 対話的なオンボーディングでは、以下のいずれかを選択可能：
  • 環境変数参照（例：keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }）
  • 設定済みプロバイダー参照（file または exec）のプロバイダーエイリアス + ID
• 対話的な参照モードでは、保存前に高速なプリフライト検証が実行されます。
  • 環境変数参照：変数名と現在のオンボーディング環境での空でない値を検証。
  • プロバイダー参照：プロバイダー設定を検証し、要求された 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>。
• 既存の平文セットアップはそのまま動作し続けます。

注意： ヘッドレスおよびサーバー向けのヒント：ブラウザのあるマシンで OAuth を完了し、 ~/.openclaw/credentials/oauth.json（または $OPENCLAW_STATE_DIR/credentials/oauth.json）を Gateway ホストにコピーしてください。

出力と内部動作

~/.openclaw/openclaw.json の主なフィールド：

• agents.defaults.workspace
• agents.defaults.model / models.providers（MiniMax を選択した場合）
• tools.profile（ローカルオンボーディングでは未設定時に "coding" がデフォルト。既存の明示的な値は保持）
• gateway.*（モード、バインド、認証、Tailscale）
• session.dmScope（ローカルオンボーディングでは未設定時に per-channel-peer がデフォルト。既存の明示的な値は保持）
• channels.telegram.botToken、channels.discord.token、channels.signal.*、channels.imessage.*
• チャンネル許可リスト（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 の認証情報は ~/.openclaw/credentials/whatsapp/<accountId>/ に保存されます。 セッションは ~/.openclaw/agents/<agentId>/sessions/ に保存されます。

注意： 一部のチャンネルはプラグインとして提供されます。オンボーディング中に選択すると、ウィザードは チャンネル設定の前にプラグイン（npm またはローカルパス）のインストールを促します。

Gateway ウィザード RPC：

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

クライアント（macOS アプリとコントロール UI）は、オンボーディングロジックを再実装することなくステップを描画できます。

Signal セットアップの動作：

• 適切なリリースアセットをダウンロード
• ~/.openclaw/tools/signal-cli/<version>/ に保存
• 設定に channels.signal.cliPath を書き込み
• JVM ビルドには Java 21 が必要
• ネイティブビルドが利用可能な場合はそちらを使用
• Windows では WSL2 を使用し、WSL 内で Linux の signal-cli フローに従う

関連ドキュメント

• オンボーディングハブ：オンボーディングウィザード（CLI）
• オートメーションとスクリプト：CLIオートメーション
• コマンドリファレンス：openclaw onboard