前のページ
Openclaw-Series

02. OpenClaw 環境構築と初回実行

本記事では OpenClaw のインストール・設定フローを詳しく解説します。npm/pnpm/bun および Docker の 4 つのインストール方法、設定ファイルの詳細、よくある問題のトラブルシューティングをカバーし、開発者が 5 分で環境構築を完了し、個人 AI アシスタントを起動できるようサポートします。

OpenClaw v2026.2 対応 | Node.js >= 22 環境と AI API Key（Anthropic Claude 推奨）があることを前提としています。

TL;DR: 5 分で OpenClaw インストール完了。npm/pnpm/bun/Docker の 4 方式に対応、推奨は npm install -g openclaw@latest && openclaw onboard。設定ファイルは ~/.openclaw/openclaw.json、openclaw gateway で起動。Docker デプロイ、設定ファイル構造、よくある問題のトラブルシューティングを詳述。

前提条件

必須環境

環境 バージョン要件 確認コマンド 説明
Node.js >= 22.0.0 node --version LTS バージョン推奨
npm >= 10.0.0 npm --version Node.js に同梱
メモリ >= 4GB - 複雑なタスクには 8GB+ 推奨
ディスク >= 2GB - 依存関係とキャッシュを含む

推奨環境

環境 説明
pnpm または bun npm より高速、ディスク使用量が少ない
Docker サンドボックスモードや隔離環境用
Tailscale リモートアクセス用（オプション）

AI API Key

OpenClaw は AI モデルに接続する必要があります。推奨：

プロバイダー 推奨モデル 取得方法 価格目安
Anthropic Claude Opus 4.6 / Sonnet 4 console.anthropic.com 使用量課金
OpenAI GPT-4o / GPT-4-turbo platform.openai.com 使用量課金
ローカルモデル Ollama + Llama 3 ローカルデプロイ 無料（ハードウェア必要）

💡 推奨：Anthropic Claude Opus 4.6 は長文コンテキスト処理とプロンプトインジェクション対策に優れています。

環境検証

# Node.js バージョン確認
node --version
# 出力例: v22.12.0

# npm バージョン確認
npm --version
# 出力例: 10.9.0

# システム情報確認
uname -a  # Linux/macOS
# または
systeminfo | findstr /B /C:"OS Name" /C:"OS Version"  # Windows

インストール方法の比較

flowchart TB
    A[インストール方法を選択] --> B{使用シーン?}
    B -->|クイック体験| C[npm グローバルインストール]
    B -->|日常使用| D[pnpm/bun インストール]
    B -->|本番デプロイ| E[Docker デプロイ]
    B -->|開発貢献| F[ソースビルド]
    
    C --> G[5分で完了]
    D --> H[より高速な依存関係管理]
    E --> I[環境隔離 再現可能]
    F --> J[カスタマイズ可能 開発参加]

方式比較表

方式 インストール速度 ディスク使用量 更新の容易さ 隔離性 推奨シーン
npm -g ⭐⭐⭐ 大きい 簡単 なし クイック体験、一時テスト
pnpm -g ⭐⭐⭐⭐ 小 簡単 なし 日常使用、マルチプロジェクト
bun -g ⭐⭐⭐⭐⭐ 小 簡単 なし 最高速度を追求
Docker ⭐⭐ 中 中程度 完全 本番デプロイ、チーム協業
ソース ⭐ 大 複雑 なし 開発貢献、深度カスタマイズ

方式一：npm グローバルインストール（初心者推奨）

インストール手順

# 1. 最新安定版をインストール
npm install -g openclaw@latest

# 2. インストール確認
openclaw --version
# 出力例: 2026.2.26

# 3. ヘルプ表示
openclaw --help

インストール後のディレクトリ構造

/usr/local/lib/node_modules/openclaw/  # グローバルインストール先
├── bin/
│   └── openclaw                        # 実行ファイル
├── lib/
│   └── ...                             # コアライブラリ
└── package.json

~/.openclaw/                            # ユーザーデータディレクトリ（初回実行時に作成）
├── openclaw.json                       # メイン設定ファイル
├── credentials/                       # チャネル認証情報保存
├── workspace/                          # Agent ワークスペース
│   ├── AGENTS.md                      # Agent 動作ガイド
│   ├── SOUL.md                        # Agent 人格設定
│   └── skills/                        # カスタムスキル
└── logs/                              # ログディレクトリ

入門ウィザードの実行

# 対話式設定ウィザードを起動
openclaw onboard --install-daemon

ウィザードで以下を案内します：

sequenceDiagram
    participant U as ユーザー
    participant W as ウィザード
    participant S as システム
    
    U->>W: onboard 起動
    W->>U: モデルプロバイダー選択
    U->>W: Anthropic を選択
    W->>U: API Key 入力
    U->>W: Key を貼り付け
    W->>U: Gateway ポート選択
    U->>W: 18789（デフォルト）
    W->>U: デーモンインストール？
    U->>W: はい
    W->>S: systemd/launchd サービス作成
    S-->>W: インストール成功
    W-->>U: 設定完了！

方式二：pnpm インストール（日常使用推奨）

pnpm のインストール

# npm で pnpm をインストール
npm install -g pnpm

# またはスタンドアロンスクリプト
curl -fsSL https://get.pnpm.io/install.sh | sh -

OpenClaw のインストール

# pnpm でインストール
pnpm add -g openclaw@latest

# 確認
openclaw --version

pnpm の利点

特性 説明
ハードリンクストレージ グローバルストア、マルチプロジェクトで依存関係共有、ディスク節約
高速インストール npm より 2-3 倍高速
厳密な依存関係 ファントム依存を回避
monorepo サポート マルチパッケージ管理をネイティブサポート

方式三：bun インストール（最高速度追求）

bun のインストール

# macOS/Linux
curl -fsSL https://bun.sh/install | bash

# または npm で
npm install -g bun

OpenClaw のインストール

# bun でインストール
bun add -g openclaw@latest

# 確認
openclaw --version

bun の利点

特性 説明
超高速インストール npm より 20-30 倍高速
組み込みバンドラー TypeScript をネイティブサポート
組み込みテスト Jest 互換のテストフレームワーク
Node.js 互換 ほとんどの npm パッケージをそのまま使用可能

方式四：Docker デプロイ（本番推奨）

イメージの取得

# 最新イメージをプル
docker pull openclaw/openclaw:latest

# またはバージョン指定
docker pull openclaw/openclaw:2026.2

基本実行

# 最小構成で実行
docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  -e ANTHROPIC_API_KEY=your_key_here \
  openclaw/openclaw:latest

# ログ確認
docker logs -f openclaw

Docker Compose 設定

docker-compose.yml を作成：

version: '3.8'

services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    ports:
      - "18789:18789"
    volumes:
      - ./openclaw-data:/root/.openclaw
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      # または設定ファイルを使用
      # - OPENCLAW_CONFIG=/root/.openclaw/openclaw.json
    healthcheck:
      test: ["CMD", "openclaw", "health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

サービス起動：

# .env ファイル作成
echo "ANTHROPIC_API_KEY=your_key_here" > .env

# 起動
docker-compose up -d

# 状態確認
docker-compose ps

# ログ確認
docker-compose logs -f

Docker ネットワーク設定

# docker-compose.yml 拡張設定
services:
  openclaw:
    # ... その他設定
    networks:
      - openclaw-net

  # オプション：リバースプロキシ
  caddy:
    image: caddy:latest
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
    networks:
      - openclaw-net

networks:
  openclaw-net:
    driver: bridge

方式五：ソースビルド（開発者向け）

リポジトリのクローン

# メインリポジトリをクローン
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 依存関係インストール（pnpm 推奨）
pnpm install

# ビルド
pnpm build

# 実行
pnpm openclaw onboard

開発モード

# 開発モード（自動リロード）
pnpm gateway:watch

# テスト実行
pnpm test

# コードチェック
pnpm lint

設定ファイル詳細

設定の優先順位

CLI パラメータ > 環境変数 > 設定ファイル > デフォルト値

ディレクトリ構造

~/.openclaw/
├── openclaw.json           # メイン設定ファイル
├── openclaw.json.backup    # 自動バックアップ
├── credentials/            # 機密認証情報（自動暗号化）
│   ├── telegram.json
│   ├── whatsapp.json
│   └── discord.json
├── workspace/              # Agent ワークスペース
│   ├── AGENTS.md          # グローバル動作ガイド
│   ├── SOUL.md            # Agent 人格
│   ├── TOOLS.md           # カスタムツール説明
│   ├── USER.md            # ユーザー情報
│   └── skills/            # スキルディレクトリ
│       ├── gmail/
│       │   └── SKILL.md
│       └── calendar/
│           └── SKILL.md
├── sessions/              # セッションデータ
├── logs/                  # ログファイル
│   ├── gateway.log
│   └── agent.log
└── cache/                 # キャッシュデータ

最小設定

~/.openclaw/openclaw.json：

{
  "agent": {
    "model": "anthropic/claude-opus-4-6"
  }
}

完全設定例

{
  "agent": {
    "model": "anthropic/claude-opus-4-6",
    "thinkingLevel": "high",
    "verboseLevel": "normal"
  },
  "gateway": {
    "port": 18789,
    "bind": "loopback",
    "host": "127.0.0.1"
  },
  "channels": {
    "telegram": {
      "botToken": "YOUR_BOT_TOKEN",
      "dmPolicy": "pairing",
      "allowFrom": []
    },
    "whatsapp": {
      "allowFrom": ["+8613800138000"],
      "groups": {
        "*": { "requireMention": true }
      }
    },
    "discord": {
      "token": "YOUR_DISCORD_TOKEN",
      "guilds": {}
    }
  },
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace",
      "sandbox": {
        "mode": "off"
      }
    }
  },
  "models": {
    "fallback": [
      {
        "model": "anthropic/claude-sonnet-4",
        "condition": "rate_limit"
      }
    ]
  },
  "webhooks": [],
  "cron": []
}

設定項目説明

設定項目 型 デフォルト 説明
agent.model string claude-opus-4-6 使用する AI モデル
agent.thinkingLevel string normal 思考深度：off/minimal/low/medium/high/xhigh
gateway.port number 18789 Gateway 待ち受けポート
gateway.bind string loopback バインドアドレス：loopback/all
channels.*.dmPolicy string pairing DM ポリシー：pairing/open
agents.defaults.sandbox.mode string off サンドボックスモード：off/non-main/always

環境変数

OpenClaw は環境変数で設定を上書きできます：

# API Keys
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."

# チャネル設定
export TELEGRAM_BOT_TOKEN="123456:ABC..."
export DISCORD_BOT_TOKEN="..."

# Gateway 設定
export OPENCLAW_PORT=18789
export OPENCLAW_BIND="loopback"

起動と検証

Gateway の起動

# フォアグラウンド実行（デバッグモード）
openclaw gateway --verbose

# バックグラウンド実行（デーモン）
openclaw gateway --daemon

# ポート指定
openclaw gateway --port 18790

稼働状態の検証

# ヘルスチェック
openclaw doctor

# 出力例：
# ✓ Node.js version: v22.12.0
# ✓ OpenClaw version: 2026.2.26
# ✓ Gateway running on port 18789
# ✓ API key configured
# ✓ Workspace directory exists

Web コンソールへのアクセス

Gateway 起動後、ブラウザで以下にアクセス：

http://127.0.0.1:18789

Web Control UI が表示されます：

ページ 機能
Chat Agent との対話
Sessions セッション管理
Config 設定管理
Nodes デバイスノード管理
Logs ログ表示

会話テスト

# コマンドラインでテスト
openclaw agent --message "こんにちは、自己紹介してください"

# 出力例：
# こんにちは！私はあなたの OpenClaw アシスタントです。お手伝いできることは...

よくある問題のトラブルシューティング

問題 1：ポートが使用中

症状：

Error: EADDRINUSE: address already in use 127.0.0.1:18789

解決策：

# ポートを使用しているプロセスを検索
lsof -i :18789
# または
netstat -tlnp | grep 18789

# プロセスを終了
kill -9 <PID>

# または別のポートを使用
openclaw gateway --port 18790

問題 2：API Key が無効

症状：

Error: Invalid API key

解決策：

# 設定を検証
openclaw config get agent.model

# 環境変数を確認
echo $ANTHROPIC_API_KEY

# 再設定
openclaw onboard

問題 3：Node バージョンが低い

症状：

Error: OpenClaw requires Node.js >= 22.0.0

解決策：

# nvm でバージョン切り替え
nvm install 22
nvm use 22
nvm alias default 22

# 確認
node --version

問題 4：権限エラー

症状：

Error: EACCES: permission denied

解決策：

# npm 権限を修正
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) ~/.openclaw

# または nvm で Node.js を管理（推奨）

問題 5：Docker ネットワーク問題

症状：

Error: Cannot connect to Gateway from container

解決策：

# ネットワーク確認
docker network ls
docker network inspect bridge

# host ネットワークを使用
docker run --network host ...

# またはポートを正しくマッピング
docker run -p 127.0.0.1:18789:18789 ...

問題 6：認証情報の紛失

症状：

Warning: Telegram credentials not found

解決策：

# チャネルに再ログイン
openclaw channels login telegram

# 認証情報ファイルを確認
ls ~/.openclaw/credentials/

# 認証情報をバックアップ
cp -r ~/.openclaw/credentials/ ~/.openclaw/credentials.backup/

問題 7：メモリ不足

症状：

Error: JavaScript heap out of memory

解決策：

# Node.js メモリ制限を増加
export NODE_OPTIONS="--max-old-space-size=8192"
openclaw gateway

# または Docker 内で
docker run -e NODE_OPTIONS="--max-old-space-size=8192" ...

更新とメンテナンス

OpenClaw の更新

# npm で更新
npm update -g openclaw@latest

# pnpm で更新
pnpm update -g openclaw@latest

# Docker で更新
docker pull openclaw/openclaw:latest
docker-compose up -d

# バージョン確認
openclaw --version

リリースチャネルの切り替え

# 安定版（推奨）
openclaw update --channel stable

# ベータ版
openclaw update --channel beta

# 開発版（最新機能、不安定の可能性）
openclaw update --channel dev

バックアップと復元

# 設定をバックアップ
tar -czvf openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw/

# 設定を復元
tar -xzvf openclaw-backup-20260226.tar.gz -C ~/

# 重要ファイルのみバックアップ
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup
cp -r ~/.openclaw/credentials/ ~/.openclaw/credentials.backup/

次のステップ

おめでとうございます！OpenClaw 環境の構築が完了しました。次は：

  1. 最初のチャネルを設定 → 次回：チャネル設定入門
  2. 最初の Skill をインストール → Web UI で検索してインストール
  3. Agent の人格をカスタマイズ → ~/.openclaw/workspace/SOUL.md を編集

本記事のまとめ：

  • 5 つのインストール方法とその適用シーンを習得
  • 設定ファイルの構造と優先順位を理解
  • 起動検証とよくある問題のトラブルシューティングを習得
  • 更新・メンテナンスの基本操作を理解

更新履歴：

  • 2026-02-26：初版公開、OpenClaw v2026.2 ベース

シリーズナビゲーション：