openclaw onboard CLI ウィザードのリファレンス

新しいツールを導入する際、設定ファイルの書き方を調べたり、環境変数を一つずつ手動で設定したりするのは時間がかかる作業です。ドキュメントを読み込みながら、どこに何を入力すべきか迷ってしまうことも少なくありません。

セットアップの手間を減らし、本来の開発作業に集中するための最適な方法を紹介します。

必要なもの

このガイドを進めるには、以下の準備が必要です。

openclaw CLI

クイックスタート

最短でセットアップを完了させる手順です。ターミナルを開き、以下のコマンドを入力してください。

openclaw onboard

このコマンドを実行すると、対話形式のウィザードが起動します。画面に表示されるガイドに従って操作を進めるだけで、プロジェクトの構成が完了します。

トラブルシューティング

現時点の源文書において、このコマンドに関する特定のトラブルシューティング情報はありません。

セットアップ中に不明な点が出てきた場合は、以下のツールで質問することをお勧めします。

AI Setup Assistant

次のステップ

Onboarding Wizard の概要

ツールを使い始める際、設定ファイルがどこに保存され、バックグラウンドで何が起きているのか把握しておきたいですよね。ブラックボックスなインストール作業は、後で設定を変更したくなった時に困る原因になります。

OpenClawのセットアップウィザードが、ローカルモードで具体的にどのような処理を行っているのか、ステップごとに見ていきましょう。

What You’ll Need

Node.js (推奨環境。WhatsAppやTelegramの利用に必要です)
npm または pnpm (パッケージマネージャー)
各種 AI プロバイダーの API key または OAuth 認証情報
macOS (LaunchAgent) または Linux (systemd) 環境

Quick Start

セットアップは以下のステップで進みます。通常、5分ほどで完了します。

1. 既存設定の検出

~/.openclaw/openclaw.json が既に存在する場合、Keep / Modify / Reset のいずれかを選択します。ウィザードを再実行しても、明示的に Reset を選ぶか --reset フラグを渡さない限り、設定が消去されることはありません。

--reset: デフォルトで config+creds+sessions を削除します。
--reset-scope full: ワークスペースも含めて完全に削除します。
設定ファイルが無効な場合、ウィザードは停止します。その際は openclaw doctor を実行して問題を解決してください。

2. Model/Auth 設定

利用する AI モデルと認証方法を設定します。

Anthropic: ANTHROPIC_API_KEY 環境変数を使用するか、プロンプトに入力します。macOS では Keychain の “Claude Code-credentials” をチェックし、Linux/Windows では ~/.claude/.credentials.json を再利用できます。
OpenAI: OPENAI_API_KEY を使用します。Codex を利用する場合は ~/.codex/auth.json の再利用や、ブラウザ経由の OAuth フローが可能です。モデルが未設定の場合は openai-codex/gpt-5.2 がデフォルトになります。
サードパーティプロバイダー: xAI (Grok), OpenCode Zen, Vercel AI Gateway, Cloudflare AI Gateway, MiniMax M2.5, Moonshot (Kimi) などに対応しています。
機密情報の管理: デフォルトでは API key はプレーンテキストで保存されます。環境変数を利用したい場合は --secret-input-mode ref を使用してください。

3. Workspace 設定

デフォルトのワークスペースは ~/.openclaw/workspace です。ここにはエージェントの動作に必要なシードファイルが配置されます。

4. Gateway 設定

API のポート、バインド設定、認証モードを決定します。

認証には Token モードを推奨します。これにより、ローカルのクライアントも認証が必要になりセキュリティが向上します。
非対話形式でトークンを設定する場合は --gateway-token-ref-env <ENV_VAR> を使用してください。

5. Channels 設定

各種メッセージングアプリとの連携を設定します。

WhatsApp / Telegram / Discord: ボットトークンや QR ログインを使用します。
BlueBubbles: iMessage を利用する場合の推奨方法です。
セキュリティ: デフォルトでは「ペアリング」が必要です。最初のメッセージ送信時にコードが届くので、openclaw pairing approve <channel> <code> で承認してください。

6. Web search 設定

Perplexity, Brave, Gemini, Grok, Kimi からプロバイダーを選択します。--skip-search でスキップすることも可能です。

7. Daemon install (自動起動設定)

OS に合わせてバックグラウンド実行の設定を行います。

macOS: LaunchAgent を使用します。
Linux: systemd unit を使用します。loginctl enable-linger によりログアウト後も Gateway を維持しようと試みます。
Runtime: Node.js を選択してください。Bun は推奨されません。

8. Health check

最後に Gateway を起動し、openclaw health を実行して正常に動作しているか確認します。詳細な状態を知りたい場合は openclaw status --deep を使用してください。

9. Skills 設定

利用可能なスキルを確認し、必要な依存関係をインストールします。パッケージマネージャーは npm または pnpm を選択してください。

Troubleshooting

ブラウザのない環境（サーバーなど）で OAuth を行いたい: ブラウザのある手元のマシンで OAuth を完了させ、~/.openclaw/credentials/oauth.json をサーバーの同じパスにコピーしてください。
デーモンのインストールがブロックされる: gateway.auth.token が SecretRef で管理されている場合、その参照が解決できないとインストールが進みません。環境変数が正しく設定されているか確認してください。
設定のリセット: リセット処理には rm ではなく trash コマンドが使用されるため、誤って実行しても復旧の余地があります。

不明な点がある場合は、AI Setup Assistant に質問してみてください。

What’s Next

開発環境を新しく構築するたびに、対話形式のプロンプトに何度も答えるのは少し面倒に感じることがあります。特に、複数の環境をセットアップする場合や、自動化スクリプトの中に組み込みたい時は、コマンド一つで設定を完了させたいですよね。

openclawのNon-interactive modeを使えば、すべての設定をフラグとして渡せるため、手動での入力をスキップしてセットアップを自動化できます。

必要なもの

使用するモデルのAPIキー（Anthropic, Gemini, Moonshotなど）
Node.js（デーモンをランタイムとして使用する場合）

クイックスタート

--non-interactive フラグを使用することで、オンボーディングを自動化できます。以下のコマンドは、AnthropicのAPIキーを使用してローカルモードでセットアップし、バックグラウンドでデーモンを起動する例です。

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 フラグを追加すると、サマリーがマシン読み取り可能な形式で出力されます。

Gatewayトークンの設定

Non-interactive modeでGatewayのトークンを環境変数から参照する場合は、--gateway-token-ref-env を使用します。

export OPENCLAW_GATEWAY_TOKEN="your-token"
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice skip \
  --gateway-auth token \
  --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN

他のプロバイダーの例

使用するモデルプロバイダーに合わせて、--auth-choice と対応するAPIキーのフラグを変更してください。

Geminiを使用する場合

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice gemini-api-key \
  --gemini-api-key "$GEMINI_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

Cloudflare AI Gatewayを使用する場合

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice cloudflare-ai-gateway-api-key \
  --cloudflare-ai-gateway-account-id "your-account-id" \
  --cloudflare-ai-gateway-gateway-id "your-gateway-id" \
  --cloudflare-ai-gateway-api-key "$CLOUDFLARE_AI_GATEWAY_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-token と --gateway-token-ref-env は同時に使用できません。直接値を渡すか、環境変数名を指定するか、どちらか一方を選択してください。

自動化が止まってしまう

--json フラグを付けても、自動的にNon-interactive modeにはなりません。スクリプト内で使用する際は、必ず --non-interactive と（必要に応じて） --workspace を明示的に指定してください。

設定の詳細やトラブルの解決については、AI Setup Assistant も活用してください。

次のステップ

新しいツールを導入する際、オンボーディングのフローをゼロから作り直すのは非常に手間がかかります。クライアントごとに同じロジックを何度も実装していると、仕様変更のたびに修正漏れが発生するリスクもあります。

Gateway の wizard RPC を使えば、こうした面倒な処理を共通化できます。バックエンド側でフローを管理できるため、フロントエンドの実装をシンプルに保てるのが大きなメリットです。

必要なもの

Java 21 (JVM build を使用する場合)
WSL2 (Windows 環境で利用する場合)

クイックスタート

Gateway は RPC を通じてウィザードフローを公開しています。これにより、macOS アプリや Control UI などのクライアントは、複雑なオンボーディングロジックを自分で持たなくても、ステップごとの描画に集中できます。

利用可能な API は以下の通りです：

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

また、このウィザードは signal-cli のセットアップも自動で行います。具体的な動作は以下の通りです：

GitHub のリリースから適切なアセットをダウンロードします。
~/.openclaw/tools/signal-cli/<version>/ にファイルを保存します。
設定ファイルの channels.signal.cliPath にパスを書き込みます。

利用可能な場合は Native build が優先的に使用されます。

トラブルシューティング

セットアップ中に問題が発生した場合は、以下の点を確認してください。

Java のバージョン: JVM build を使用している場合、Java 21 が必要です。古いバージョンでは動作しません。
Windows 環境: Windows をお使いの場合は、必ず WSL2 を使用してください。signal-cli のインストールは、WSL 内の Linux フローに従って実行されます。

不明な点がある場合や、さらに詳細なガイドが必要な場合は、AI Setup Assistant を活用してください。

次のステップ

---
title: "What the wizard writes - ウィザードが設定する内容について"
description: "OpenClawのセットアップウィザードが生成する設定ファイルの詳細と、各パラメーターの意味について解説します。"
---

新しいツールを導入したとき、自動設定（ウィザード）が裏側で何を書き換えたのか分からず、不安になったことはありませんか？設定の場所が分からないと、後でカスタマイズしたくなった時に、どこを触ればいいのか迷ってしまいますよね。

OpenClawのウィザードは非常に便利ですが、何がどこに保存されているかを把握しておくことは、環境をコントロールする上でとても大切です。今回は、ウィザードが生成する `~/.openclaw/openclaw.json` の中身と、関連するディレクトリ構造について詳しく見ていきましょう。

## 必要なもの

- OpenClaw のウィザードを実行可能な環境
- `~/.openclaw` ディレクトリへのアクセス権限

## クイックスタート

ウィザードを実行すると、主に `~/.openclaw/openclaw.json` に以下のフィールドが書き込まれます。

- `agents.defaults.workspace`: エージェントが使用するデフォルトのワークスペース
- `agents.defaults.model` / `models.providers`: 使用する AI モデルの設定（Minimax を選択した場合など）
- `tools.profile`: デフォルトのプロファイル設定。未設定の場合は `"coding"` がセットされます（既存の値がある場合は保持されます）
- `gateway.*`: Gateway に関する設定（`mode`, `bind`, `auth`, `tailscale`）
- `session.dmScope`: セッションの振る舞いに関する詳細設定（詳細は [CLI Onboarding Reference](/docs/start/wizard-cli-reference#outputs-and-internals) を参照）
- チャンネルの認証情報: `channels.telegram.botToken`, `channels.discord.token`, `channels.signal.*`, `channels.imessage.*`
- チャンネルの allowlists: ウィザードで選択した Slack, Discord, Matrix, Microsoft Teams などの許可リスト（可能な場合は名前が ID に解決されます）
- `skills.install.nodeManager`: スキルのインストールに使用する Node.js パッケージマネージャー
- ウィザードの実行メタデータ: `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 またはローカルパス経由）を求められることがあります。プロンプトに従ってインストールを完了させてください。

不明な点がある場合は、[AI Setup Assistant](/docs/#docs-chat) も活用してみてください。

## 次のステップ

- [Onboarding Wizard](/docs/start/wizard): ウィザードの概要
- [macOS App Onboarding](/docs/start/onboarding): macOS アプリでのオンボーディング
- [Gateway configuration](/docs/gateway/configuration): Gateway の詳細設定リファレンス
- チャンネル別プロバイダー設定: [WhatsApp](/docs/channels/whatsapp), [Telegram](/docs/channels/telegram), [Discord](/docs/channels/discord), [Google Chat](/docs/channels/googlechat), [Signal](/docs/channels/signal), [BlueBubbles](/docs/channels/bluebubbles), [iMessage](/docs/channels/imessage)
- スキル設定: [Skills](/docs/tools/skills), [Skills config](/docs/tools/skills-config)

OpenClaw Expert

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。