セットアップ

注意： 初めてセットアップする場合は、はじめにから始めてください。 ウィザードの詳細はオンボーディングウィザードをご覧ください。

最終更新：2026-01-01

要約

  • カスタマイズはリポジトリ外で管理： ~/.openclaw/workspace（ワークスペース）+ ~/.openclaw/openclaw.json（設定）。
  • 安定版ワークフロー： macOS アプリをインストールし、バンドルされた Gateway を実行。
  • 最新版ワークフロー： pnpm gateway:watch で Gateway を自分で実行し、macOS アプリをローカルモードで接続。

前提条件（ソースからビルドする場合）

  • Node >=22
  • pnpm
  • Docker（オプション。コンテナ化されたセットアップ／e2e テスト用。Docker を参照）

カスタマイズ戦略（アップデートに強くする）

「自分専用に100%カスタマイズ」しつつ、アップデートの影響を最小限に抑えたい場合は、カスタマイズを以下に集約してください。

  • 設定： ~/.openclaw/openclaw.json（JSON/JSON5風）
  • ワークスペース： ~/.openclaw/workspace（スキル、プロンプト、メモリ。プライベートgitリポジトリにするのがおすすめ）

初回セットアップ：

openclaw setup

このリポジトリ内から実行する場合は、ローカルのCLIエントリを使用：

openclaw setup

グローバルインストールがまだの場合は pnpm openclaw setup で実行できます。

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

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

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

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

  1. OpenClaw.app をインストール・起動（メニューバー）。
  2. オンボーディング／権限チェックリストを完了（TCC プロンプト）。
  3. Gateway をローカルにして起動中であることを確認（アプリが管理）。
  4. チャンネルを接続（例：WhatsApp）：
openclaw channels login
  1. 動作確認：
openclaw health

お使いのビルドにオンボーディングがない場合：

  • openclaw setup を実行してから openclaw channels login、その後 Gateway を手動で起動（openclaw gateway）。

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

目標：TypeScript の Gateway を開発しながら、ホットリロードを使い、macOS アプリの UI は接続したままにする。

0）（オプション）macOSアプリもソースから実行

macOS アプリも最新版にしたい場合：

./scripts/restart-mac.sh

1）開発用Gatewayを起動

pnpm install
pnpm gateway:watch

gateway:watch は Gateway をウォッチモードで起動し、TypeScript の変更時に自動リロードします。

2）macOSアプリを起動中のGatewayに接続

OpenClaw.app で：

  • 接続モード：ローカル アプリが設定されたポートで動作中の Gateway に接続します。

3）確認

  • アプリ内の Gateway ステータスに “Using existing gateway …” と表示されること。
  • もしくは CLI で確認：
openclaw health

よくあるミス

  • ポートの不一致： Gateway の WS デフォルトは ws://127.0.0.1:18789。アプリと CLI で同じポートを使ってください。
  • 状態の保存場所：
    • 認証情報：~/.openclaw/credentials/
    • セッション：~/.openclaw/agents/<agentId>/sessions/
    • ログ：/tmp/openclaw/

認証情報の保存先マップ

認証のデバッグやバックアップ対象の確認に使ってください。

  • WhatsApp：~/.openclaw/credentials/whatsapp/<accountId>/creds.json
  • Telegramボットトークン：設定/env もしくは channels.telegram.tokenFile（通常のファイルのみ。シンボリックリンクは拒否）
  • Discordボットトークン：設定/env もしくは SecretRef（env/file/exec プロバイダー）
  • Slackトークン：設定/env（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 詳細：セキュリティ。

アップデート（セットアップを壊さずに）

  • ~/.openclaw/workspace と ~/.openclaw/ は「自分のもの」として保持してください。個人のプロンプトや設定を openclaw リポジトリに入れないでください。
  • ソースのアップデート：git pull + pnpm install（lockfile が変わった場合）、引き続き pnpm gateway:watch を使用。

Linux（systemdユーザーサービス）

Linux では systemd ユーザーサービスを使用します。デフォルトでは、systemd はログアウト／アイドル時にユーザーサービスを停止するため、Gateway が終了してしまいます。オンボーディング時に lingering の有効化を試みます（sudo を要求する場合があります）。まだ無効な場合は以下を実行してください。

sudo loginctl enable-linger $USER

常時稼働やマルチユーザーサーバーの場合は、ユーザーサービスの代わりにシステムサービスの利用を検討してください（lingering は不要）。Gatewayランブックの systemd に関する記述を参照してください。

関連ドキュメント

arrow_back
前へ
Session Management Compaction
次へ
Pi Dev
arrow_forward