Contents
ハードウェア と OS の最低要件
| 項目 | 推奨環境 | 最低条件 |
|---|---|---|
| OS | macOS 14.0 以上 (Sonoma / Sequoia) | macOS 13 でも Rosetta2 経由で一部可（※後述） |
| CPU | Apple Silicon M1‑M4 系列 | Intel 第7世代以降（Rosetta2 必須） |
| RAM | 32 GB 以上（大規模プロンプトや同時実行を想定） | 16 GB 以上 |
| 空きディスク | 30 GB 以上（ログ・モデルキャッシュ確保） | 20 GB 以上 |
ポイント
- Apple Silicon は ARM 最適化された Node.js バイナリが公式に提供されているため、最も安定します。
- Intel Mac では Rosetta 2 が必須になることと、一部ネイティブ拡張のビルドが失敗しやすい点に注意してください。
macOS と CPU の確認方法
|
1 2 3 4 5 6 |
# OS バージョン sw_vers -productVersion # → 14.0.x 以上か？ # CPU アーキテクチャ sysctl -n machdep.cpu.brand_string # "Apple M1" / "Intel(R) Core(TM) i7‑..." が表示されます |
ソフトウェアスタックの確認とインストール手順
| コンポーネント | 必須バージョン | 推奨取得方法 |
|---|---|---|
| Homebrew | 4.x 以上 | /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" |
| Node.js | v22.x 系列（LTS） | brew install node@22 （Apple Silicon 用は自動的に ARM ビルド） |
| Python | 3.11+ | brew install python@3.11 |
| git | 任意 | brew install git |
Intel Mac の注意点
Homebrew はデフォルトで/usr/localにインストールされますが、Rosetta 2 環境下では/opt/homebrew（Apple Silicon 用）と混在しやすくなるため、必ずarch -x86_64 /bin/bash -c "$(curl …)"で x86 用 Homebrew を別ディレクトリに入れるか、公式ドキュメントの “Installing Homebrew on Intel Macs” に従ってください。
API キー・トークンの安全な管理方法
1. macOS Keychain を利用した保存
Keychain は OS 標準の暗号化ストレージで、平文がディスクに残りません。以下は security コマンドを用いた登録例です。
|
1 2 3 4 5 6 |
# Anthropic API キーを追加 security add-generic-password -a "$USER" -s "OpenClaw_Anthropic_API_Key" -w "<YOUR_KEY>" # Slack Bot Token を追加（必要に応じて App Token も同様に） security add-generic-password -a "$USER" -s "OpenClaw_Slack_Bot_Token" -w "<YOUR_TOKEN>" |
取得した値は実行時に環境変数として展開できます。
|
1 2 3 4 5 6 7 |
# .zshenv（~/.zprofile でも可）に記述 export ANTHROPIC_API_KEY=$(security find-generic-password -a "$USER" -s "OpenClaw_Anthropic_API_Key" -w) export SLACK_BOT_TOKEN=$(security find-generic-password -a "$USER" -s "OpenClaw_Slack_Bot_Token" -w) # ファイル権限は 600 にしておく chmod 600 ~/.zshenv |
利点
- キーが暗号化された状態で保存される
-source ~/.zshenvだけで安全に環境変数をロードできる
2. .env ファイルと direnv の併用（オプション）
プロジェクト単位でキーを切り替えたい場合は、.env に保存し direnv が自動的に読み込む形が便利です。
|
1 2 3 4 |
# .env.example（リポジトリには含めず、実運用時のみ作成） ANTHROPIC_API_KEY=sk-xxxxxxxxxxxx SLACK_BOT_TOKEN=xoxb-xxxxxxxxxx |
|
1 2 3 4 5 6 7 8 |
# direnv のインストールと有効化 brew install direnv echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc # プロジェクトディレクトリで許可 cd ~/openclaw-project direnv allow # .env が読み込まれ、環境変数が設定される |
注意：
.envは必ず.gitignoreに入れ、外部に漏れないようにしてください。
OpenClaw 本体のインストールと初期設定
1. 推奨インストール方法（Homebrew）
|
1 2 3 4 5 6 |
# Homebrew の tap が必要な場合は追加 brew tap openclaw/homebrew-tap # 本体インストール brew install openclaw |
Homebrew はバイナリ配布なので、ビルドエラーの心配が少なく、アップデートも brew upgrade で一括管理できます。
2. npm（グローバル）方式
|
1 2 |
npm i -g openclaw # Node.js が正しくインストールされている前提 |
比較ポイント
| 方法 | メリット | デメリット |
|------|----------|------------|
| Homebrew | バイナリ配布で高速、依存関係管理が楽 | tap の追加が必要な場合あり |
| npm | Node.js エコシステムに慣れている人向け | ビルド時にネイティブモジュールのコンパイルが走ることがある |
3. 初回ウィザードで基本設定を自動生成
|
1 2 |
openclaw wizard |
| 質問項目 | 推奨回答例 |
|---|---|
| 使用する Claude モデル | claude-3.5-sonnet（コスト・性能バランスが最適） |
| デフォルト言語 | Japanese |
| Slack ワークスペース URL | （取得済みのものを貼付） |
| Bot Token の入力 | 空欄で OK（環境変数から自動参照） |
| Anthropic API キー | 同上 |
ウィザード完了後、設定ファイルは ~/.config/openclaw/config.yaml に保存されます。主要項目は以下の通りです。
|
1 2 3 4 5 6 7 8 |
model: claude-3.5-sonnet language: ja slack: bot_token: ${SLACK_BOT_TOKEN} anthropic: api_key: ${ANTHROPIC_API_KEY} daemon: true # launchctl 用 plist が自動生成されます |
Intel Mac での代替手順（Rosetta 2 使用）
-
Rosetta 2 のインストール
bash
softwareupdate --install-rosetta --agree-to-license -
x86 用 Homebrew を別ディレクトリに導入（既存の ARM 用と衝突しないように）
bash
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" \
--prefix=/usr/local/homebrew-x86_64
echo 'eval "$(/usr/local/homebrew-x86_64/bin/brew shellenv)"' >> ~/.zshrc
source ~/.zshrc -
x86 用 Node.js と Python のインストール
bash
arch -x86_64 brew install node@22 python@3.11 -
OpenClaw 本体のインストール（npm 推奨）
Rosetta 環境で npm を実行することで、x86 向けバイナリが取得されます。
bash
arch -x86_64 npm i -g openclaw -
デーモン化は launchctl の x86 用プラグインを使用（
arch -x86_64 launchctl …）
注意点：Rosetta で走らせると CPU 使用率が約 1.3 倍になるケースがあります。可能なら Apple Silicon 環境への移行をご検討ください。
バックグラウンドデーモン化と自動起動設定
1. launchctl を利用した方法（macOS 標準）
openclaw wizard の --install-daemon オプションで生成された plist をそのまま使用します。
|
1 2 3 4 5 6 7 8 9 |
# plist が正しく配置されているか確認 ls ~/Library/LaunchAgents/com.openclaw.gateway.plist # デーモンをロード（自動起動登録） launchctl load -w ~/Library/LaunchAgents/com.openclaw.gateway.plist # 起動状態の確認 launchctl list | grep openclaw |
停止・アンロード手順
|
1 2 |
launchctl unload -w ~/Library/LaunchAgents/com.openclaw.gateway.plist |
2. Homebrew Services（Homebrew 経由インストール時）
|
1 2 3 4 |
brew services start openclaw # 起動 brew services stop openclaw # 停止 brew services restart openclaw # 再起動 |
どちらを選ぶべきか
- Homebrew でインストールした場合はbrew servicesが最も手軽。
- npm や手動インストールの場合はlaunchctlを直接操作する方が確実です。
VSCode（Claude Code）連携
VSCode の拡張機能「Claude Code」は、環境変数経由で API キーとモデル名を取得できます。以下の手順で設定しましょう。
- 環境変数のエクスポート（Keychain から読み込む例）
bash
# ~/.zshenv に追記（先ほど紹介した Keychain 方式）
export CLAUDE_API_KEY=$(security find-generic-password -a "$USER" -s "OpenClaw_Anthropic_API_Key" -w)
export CLAUDE_MODEL="claude-3.5-sonnet"
-
VSCode を再起動し、拡張設定で「Use Environment Variables」をオンにする。
-
テストプロンプトを送信
コマンドパレット (⇧⌘P) →Claude: New Chat→ 日本語で質問してみる。
ヒント：複数プロジェクトで異なるモデルやキーを使い分けたい場合は、プロジェクトごとに
.envrc（direnv）を用意し、VSCode のターミナルから自動的にロードさせると便利です。
セキュリティベストプラクティスと隔離実行
1. 隔離環境の活用例
| 手段 | 特徴 | 推奨シーン |
|---|---|---|
| Docker コンテナ | OS レベルで分離、イメージは公式 GHCR に公開済み | 開発・テスト環境、CI/CD パイプライン |
| 専用 Mac mini（M4） | ハードウェアレベルの物理隔離、低コスト | 本番運用・長時間稼働 |
| VPS（Linux）＋ Rosetta2 エミュレーション | コスト削減が可能だが構成が複雑 | 一時的なトライアルや海外拠点向け |
Docker での起動例
|
1 2 3 4 5 6 7 |
docker run -it --rm \ -e ANTHROPIC_API_KEY=$(security find-generic-password -a "$USER" -s "OpenClaw_Anthropic_API_Key" -w) \ -e SLACK_BOT_TOKEN=$(security find-generic-password -a "$USER" -s "OpenClaw_Slack_Bot_Token" -w) \ -v $HOME/.config/openclaw:/root/.config/openclaw \ ghcr.io/openclaw/openclaw:latest \ openclaw daemon --install-daemon |
ポイント
- 環境変数はdocker runの-eオプションで直接注入し、.envファイルは使用しません。
- ボリュームマウントで設定ファイルを永続化します。
2. 最小権限ユーザーの作成（macOS）
|
1 2 3 4 5 6 |
# 新規ローカルユーザー「openclaw」(UID 502) を作成 sudo sysadminctl -addUser openclaw -fullName "OpenClaw Service User" -password <random> # 必要なディレクトリだけアクセス権を付与 sudo chown -R openclaw:staff $HOME/.config/openclaw |
このユーザーで launchctl のプラグインや Docker コンテナを起動すれば、万が一侵害された場合でもシステム全体への影響は限定的です。
3. ファイアウォールとポート管理
- デフォルトポート：OpenClaw は内部で
8080（HTTP）または5000（WebSocket）を使用します。 - 推奨設定：macOS の組込みファイアウォール (
pf) で外部からの着信を遮断し、ローカルホストだけにバインドさせる。
|
1 2 3 4 5 6 |
# pfctl に簡易ルールを追加（/etc/pf.conf へ追記例） echo "block in all" | sudo tee -a /etc/pf.conf echo "pass out proto tcp from any to any port {8080,5000}" | sudo tee -a /etc/pf.conf sudo pfctl -f /etc/pf.conf sudo pfctl -e # 有効化 |
トラブルシューティング・よくあるエラー
| エラーメッセージ | 主な原因 | 解決策 |
|---|---|---|
node: command not found |
Node.js が PATH に無い、またはインストールされていない | brew install node@22 → echo 'export PATH="/opt/homebrew/opt/node@22/bin:$PATH"' >> ~/.zshrc |
Invalid API key |
Keychain から取得失敗、スペルミス、権限不足 | security find-generic-password -s "OpenClaw_Anthropic_API_Key" で確認 → 正しいキーを再登録 |
EADDRINUSE: address already in use |
デフォルトポートが他プロセスと競合 | lsof -i :8080 → 該当プロセス停止、または openclaw config set port 8181 |
npm ERR! unsupported engine |
Node.js バージョンが古い | node -v が v22 未満なら Homebrew で最新版へ更新 |
docker: command not found |
Docker が未インストール、またはパスが通っていない | brew install --cask docker → アプリ起動後 docker version で確認 |
デバッグのコツ
- ログ出力を有効化
bash
export OPENCLAW_LOG_LEVEL=debug
openclaw daemon - system.log の確認（launchctl エラー時）
bash
log show --predicate 'process == "openclaw"' --info --last 1h
アップデート／アンインストールと日常メンテナンス
アップデート手順
| インストール方法 | コマンド |
|---|---|
| Homebrew | brew upgrade openclaw |
| npm | npm update -g openclaw |
アップデート後は必ずサービスを再起動してください。
|
1 2 3 4 5 6 7 |
# launchctl 経由の場合 launchctl unload -w ~/Library/LaunchAgents/com.openclaw.gateway.plist launchctl load -w ~/Library/LaunchAgents/com.openclaw.gateway.plist # brew services の場合 brew services restart openclaw |
アンインストール手順
|
1 2 3 4 5 6 |
# Homebrew brew uninstall openclaw # npm npm uninstall -g openclaw |
設定ファイルとキャッシュは手動で削除します（必要に応じてバックアップを取ること）。
|
1 2 3 |
rm -rf ~/.config/openclaw rm -f ~/Library/LaunchAgents/com.openclaw.gateway.plist |
定期的なメンテナンス項目
| 項目 | 推奨頻度 |
|---|---|
| Keychain のキー有効期限確認 | 6 か月ごと |
Docker イメージの再取得（docker pull ghcr.io/openclaw/openclaw:latest） |
月1回 |
brew doctor / npm audit 実行で依存脆弱性チェック |
2 週間ごと |
ログローテーション設定 (logrotate 相当) |
自動（~/Library/Logs/openclaw/*.log） |
最終まとめと次のステップ
- ハードウェア要件
-
macOS 14+、Apple Silicon (M1‑M4) がベスト。Intel Mac は Rosetta 2 + x86 Homebrew で代替可。
-
ソフトウェアスタック
-
Homebrew → Node.js v22, Python 3.11, git の最新版をインストール。
-
認証情報の安全管理
- macOS Keychain に保存し、
.zshenvから環境変数としてロードする方法が推奨。 -
必要に応じて
.env+direnvの組み合わせも可。 -
OpenClaw の導入
- Homebrew が最も手軽だが、npm でも同等にインストール可能。
-
openclaw wizardによる初期設定で自動生成されるconfig.yamlを確認。 -
デーモン化と自動起動
-
launchctl（標準）か brew services（Homebrew 利用時）のいずれかを選択。
-
IDE 連携
-
VSCode の Claude Code 拡張は環境変数
CLAUDE_API_KEYとCLAUDE_MODELを使うだけで即利用可能。 -
セキュリティ対策
-
Keychain 管理、最小権限ユーザーの作成、Docker 隔離、ポート制御を実装。
-
トラブルシューティング
-
エラーはバージョン不一致・キー取得失敗・ポート競合が多いので、上表の対策をまず試す。
-
保守・アップデート
brew upgrade/npm update→ サービス再起動で最新状態を維持。
次にやるべきこと
- キー登録：Keychain に Anthropic と Slack のシークレットを保存する（上記コマンド参照）。
- インストール：Homebrew で
brew install openclaw、または npm でnpm i -g openclaw。 - ウィザード実行：
openclaw wizardを走らせ、設定ファイルを生成。 - デーモン化：
launchctl load -w …またはbrew services start openclaw。 - VSCode 連携確認：拡張機能でテストクエリを投げ、応答が返るか検証。
これらの手順を順に実施すれば、30 分以内 に安全な OpenClaw 環境が構築でき、AI エージェントとして本格的に活用できるようになります。
本ガイドは執筆時点（2026 年 4 月）での最新情報に基づいています。macOS のアップデートや OpenClaw 本体のバージョン変更があった場合は、公式ドキュメントを随時確認してください。