Advanced setup

セットアップ

要約

更新頻度と、Gateway を自分で実行するかどうかに応じて、セットアップのワークフローを選択します。

カスタマイズはリポジトリの外に配置: 設定とワークスペースは ~/.openclaw/openclaw.json と ~/.openclaw/workspace/ に保持し、リポジトリの更新による影響を受けないようにします。
安定版ワークフロー（ほとんどの場合に推奨）: macOS アプリをインストールし、同梱の Gateway を実行させます。
最新開発版ワークフロー（開発用）: pnpm gateway:watch で Gateway を自分で実行し、macOS アプリを Local モードで接続します。

前提条件（ソースから実行する場合）

Node 24.15+ を推奨（Node 22 LTS、現在は 22.22.3+ も引き続きサポート）
ソースチェックアウトには pnpm が必要です。OpenClaw は開発モードで、同梱 Plugin を extensions/* pnpm ワークスペースパッケージから読み込むため、ルートの npm install ではソースツリー全体の準備は行われません。
Docker（任意。コンテナ化されたセットアップ/E2E の場合のみ。Dockerを参照）

カスタマイズ方針（更新の影響を避けるため）

「自分向けに 100% カスタマイズ」しつつ更新を容易にしたい場合は、カスタマイズを次の場所に保持します。

設定: ~/.openclaw/openclaw.json（JSON/JSON5 形式に近い）
ワークスペース: ~/.openclaw/workspace（Skills、プロンプト、メモリ。非公開 git リポジトリにすることを推奨）

完全なオンボーディングウィザードを実行せずに、設定とワークスペースのフォルダーを一度だけ初期化します。

bash

openclaw setup --baseline

まだグローバルインストールしていない場合は、代わりにこのリポジトリから実行します。

bash

pnpm openclaw setup --baseline

（--baseline を付けない単独の openclaw setup は openclaw onboard のエイリアスであり、完全な対話型ウィザードを実行します。）

このリポジトリから Gateway を実行する

pnpm build の後、パッケージ化された CLI を直接実行できます。

bash

node openclaw.mjs gateway --port 18789 --verbose

安定版ワークフロー（macOS アプリを優先）

OpenClaw.app（メニューバー）をインストールして起動します。
オンボーディング/権限のチェックリスト（TCC プロンプト）を完了します。
Gateway が Local で実行中であることを確認します（アプリが管理します）。
サービスを連携します（例: WhatsApp）。

bash

openclaw channels login

正常性を確認します。

bash

openclaw health

使用しているビルドでオンボーディングを利用できない場合:

openclaw setup、続いて openclaw channels login を実行し、Gateway を手動で起動します（openclaw gateway）。

最新開発版ワークフロー（ターミナルで Gateway を実行）

目的: TypeScript Gateway を開発し、ホットリロードを利用しながら、macOS アプリの UI を接続した状態に保ちます。

0) （任意）macOS アプリもソースから実行する

macOS アプリも最新開発版で使用する場合:

bash

./scripts/restart-mac.sh

1) 開発用 Gateway を起動する

bash

pnpm install# 初回実行時のみ（またはローカルの OpenClaw 設定/ワークスペースをリセットした後）pnpm openclaw setuppnpm gateway:watch

gateway:watch は、名前付き tmux セッション（openclaw-gateway-watch-main）で Gateway の監視プロセスを起動または再起動し、対話型ターミナルからは自動的に接続します。非対話型シェルは接続せず、 tmux attach -t openclaw-gateway-watch-main を出力します。対話型実行を接続しない状態に保つには OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch を使用し、フォアグラウンド監視モードには pnpm gateway:watch:raw を使用します。ウォッチャーは、設定済みまたはデフォルトのポートを引き継ぐ前に、アクティブなプロファイルにインストールされた Gateway サービスを停止し、サービススーパーバイザーがソースプロセスを置き換えることを防ぎます。サービスはインストールされたままです。監視を終了したら pnpm openclaw gateway start を実行してください。起動に失敗した後も tmux ペインは利用可能なため、別のターミナルやエージェントから接続したり、ログを取得したりできます。ウォッチャーは、関連するソース、設定、同梱 Plugin のメタデータが変更されると再読み込みします。監視対象の Gateway が起動中に終了した場合、gateway:watch は openclaw doctor --fix --non-interactive を一度実行して再試行します。この開発専用の修復処理を無効にするには、 OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0 を設定します。 pnpm gateway:watch は dist/control-ui を再ビルドしないため、ui/ の変更後は pnpm ui:build を再実行するか、Control UI の開発中は pnpm ui:dev を使用してください。

2) 実行中の Gateway に macOS アプリを接続する

OpenClaw.app で:

Connection Mode: Local アプリは、設定されたポートで実行中の Gateway に接続します。

3) 確認する

アプリ内の Gateway ステータスに "Using existing gateway …" と表示されることを確認します。
または CLI で確認します。

bash

openclaw health

よくある落とし穴

ポートが違う: Gateway WS のデフォルトは ws://127.0.0.1:18789 です。アプリと CLI で同じポートを使用してください。
状態の保存場所:
- チャンネル/プロバイダーの状態: ~/.openclaw/credentials/
- モデル認証プロファイル: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
- セッションとトランスクリプト: ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite
- レガシー/アーカイブ済みセッションの成果物: ~/.openclaw/agents/<agentId>/sessions/
- ログ: /tmp/openclaw/

認証情報の保存場所

認証をデバッグする場合や、バックアップ対象を判断する場合に使用してください。

WhatsApp: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
Telegram ボットトークン: 設定/環境変数または channels.telegram.tokenFile（通常のファイルのみ。シンボリックリンクは拒否されます）
Discord ボットトークン: 設定/環境変数または SecretRef（env/file/exec プロバイダー）
Slack トークン: 設定/環境変数（channels.slack.*）
ペアリング許可リスト:
- ~/.openclaw/credentials/<channel>-allowFrom.json（デフォルトアカウント）
- ~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json（デフォルト以外のアカウント）
モデル認証プロファイル: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
ファイルベースのシークレットペイロード（任意）: ~/.openclaw/secrets.json
レガシー OAuth インポート: ~/.openclaw/credentials/oauth.json 詳細: セキュリティ。