# OpenClaw入門｜導入手順から社内Kubernetes本番運用まで完全ガイド【2026年版】｜テクノスフィア > OSSのAIエージェント基盤 OpenClaw の導入手順を実体験で解説。Docker Composeでの最短起動から、Codex Pro＋ローカルLLMのハイブリッド構成、Raspberry Pi 5 + k3s での本番運用、ハマりどころ7つまで。社内活用を検討する方向けの完全ガイド。 URL: https://technosphere.co.jp/blog/openclaw-getting-started ** 目次 1. はじめに：なぜ社内に OpenClaw を立てるのか 2. OpenClaw とは何か（Claude Code・Cursor との違い） 3. 弊社で採用したアーキテクチャ全体像 4. 最短ステップ：Docker Compose でローカル起動 5. LLM プロバイダ設定（Codex Pro + ローカル fallback） 6. 本番運用：Raspberry Pi 5 + k3s への展開 7. Secret / ConfigMap / PVC の設計指針 8. 初回 OAuth ログインの儀式 9. テクノスフィアでハマったポイント 7 つ 10. よくある質問（FAQ） 11. まとめ ** 本記事のスコープ 本記事は OpenClaw v2026.5 系の構成情報をもとに、社内 LAN に閉じた運用を前提とした環境構築手順を解説します。OpenClaw 本体の仕様は活発に更新されているため、最終的なバージョンや CLI 引数は [公式ドキュメント](https://openclaw.ai/) も併せてご確認ください。 ## はじめに：なぜ社内に OpenClaw を立てるのか ここ1〜2年で、エンジニアの開発・運用・営業フローに AI アシスタントが組み込まれるのは当たり前になりました。Claude Code、Cursor、Codex、Aider、Continue……選択肢は爆発的に増えています。一方で、業務利用が深くなるほど次のような**「クラウド SaaS だけでは困る」**場面が増えてきます。 - 社内ファイルサーバ・Redmine・社内 Gitea などの**クローズドな業務システムを叩かせたい** - 機密情報を外部 SaaS にそのまま渡したくない - 長尺の自動化スクリプトを **24時間動く常駐エージェント**として走らせたい - 各部門で **用途別のスキル（プロンプト + ツール）** を整備・共有したい そこで弊社が選んだのが **OpenClaw** です。Claude Code 系のターミナル CLI ではなく、**サーバ常駐型・スキル拡張可能・ローカル LLM もクラウド LLM も差し替え可能**な OSS のエージェント基盤として、社内 Kubernetes 上で運用しています。本記事ではその環境構築の全体像と、実運用で得た知見を解説します。 ** テクノスフィアでの活用範囲 弊社では OpenClaw を「**常駐型の業務AIアシスタント（社内コードネーム mio）**」として運用しています。社内 Redmine の更新、Obsidian Vault への作業ログ自動同期、Google Analytics の集計、SUGUMEN / 現場IQ など自社プロダクトの問い合わせ起票、画像生成・動画生成・Web 検索などを 1 つの会話チャネルから扱える状態にしています。 ## OpenClaw とは何か（Claude Code・Cursor との違い） OpenClaw（オープンクロウ）は、複数 LLM プロバイダを切り替えながら使える **OSS の AI エージェント基盤**です。Claude Code や Cursor のように開発者個人の手元で動かす CLI / IDE プラグインとは少し位置づけが異なり、**HTTP サーバとして常時稼働させ、複数のクライアント・チャネルから接続して使う**形が基本になります。 | 軸 | Claude Code / Codex CLI | Cursor / Continue | OpenClaw | | 形態 | ターミナル CLI | IDE プラグイン | HTTP サーバ常駐 | | LLM | 提供元固定（Anthropic / OpenAI） | クラウド SaaS 中心 | **差し替え自由**（OAuth / OpenAI 互換 / ローカル） | | スキル拡張 | ○（CLI 同梱） | △ | ◎（workspace/skills/ で配布） | | マルチユーザ | ×（個人端末） | × | ○（gateway トークン認証） | | 常駐運用 | × | × | ○（systemd / k8s） | | チャネル | ターミナルのみ | IDE のみ | Web UI / Slack / WhatsApp / Telegram 他 | つまり OpenClaw は、Claude Code のような**「便利な対話 CLI」**を、Slack / Teams / Web チャットからも叩けて、しかも複数の LLM をフォールバックさせ、社内データに永続的にアクセスできるエージェントに昇格させたい場合に刺さるツールです。コードを書く瞬間の体験は Claude Code に分がありますが、**業務全体を支える「社内AI窓口」**としてのポジションでは OpenClaw が圧倒的に扱いやすいと感じています。 ## 弊社で採用したアーキテクチャ全体像 テクノスフィアの社内 LAN（`192.168.11.0/24`）に閉じた構成です。Pi5 を OpenClaw 本体の稼働ホスト、NAS と Ubuntu サーバを周辺サービスにあてています。 ``` ┌─────────────────────────────────────────────────────────────┐ │ 社内 LAN (192.168.11.0/24) │ │ │ │ ┌──────────────────┐ ┌──────────────────────────────┐ │ │ │ Synology NAS │ │ Ubuntu Server │ │ │ │ 192.168.11.241 │ │ 192.168.11.248 │ │ │ │ ├ Redmine :8080 │ │ ├ Lemonade LLM :8000 │ │ │ │ ├ Growi :3000 │ │ │ (Qwen / Gemma local) │ │ │ │ └ chatgpt-bridge │ │ └ docker registry │ │ │ │ :18080 │ └──────────────────────────────┘ │ │ │ (gpt-image-2) │ │ │ └──────────────────┘ │ │ ▲ │ │ │ image-gen skill │ │ ┌────────┴───────────────────────────────────┐ │ │ │ Raspberry Pi 5 (192.168.11.250) │ │ │ │ ┌────────────────────────────────────────┐ │ │ │ │ │ k3s (single-node, Traefik, local-path)│ │ │ │ │ │ ┌──────────────────────────────────┐ │ │ │ │ │ │ │ Namespace: openclaw │ │ │ │ │ │ │ │ ├ Deployment: openclaw │ │ │ │ │ │ │ │ │ image: ghcr.io/openclaw │ │ │ │ │ │ │ │ │ port: 18789 │ │ │ │ │ │ │ │ ├ ConfigMap: openclaw-config │ │ │ │ │ │ │ │ ├ Secret: openclaw-secrets │ │ │ │ │ │ │ │ └ PVC: openclaw-data │ │ │ │ │ │ │ └──────────────────────────────────┘ │ │ │ │ │ └────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` ### 採用理由 - **Pi5 + k3s：**消費電力 10W 未満で 24h 動かせる。社内 AI 基盤を専用サーバ化するほど大規模ではないので、コスト・スペースともに Pi5 が最適 - **LLM のローカル化：**Ubuntu 機の Lemonade（llama.cpp + OpenAI 互換 API）に Qwen 3.6 35B を載せ、社内データの問い合わせはこちらに流す。クラウド料金もゼロ - **クラウド LLM の併用：**コード生成や深い推論が必要な場合は Codex Pro のサブスク枠を OAuth で組み込み - **NAS の chatgpt-bridge：**OpenAI 互換エンドポイントで `gpt-image-2` を社内 LAN 内に閉じて提供。OpenClaw からは `image-gen` スキル経由で叩く ## 最短ステップ：Docker Compose でローカル起動 まずは個人 PC や検証用 VM 上で動くようにするのが最短ルートです。**k3s からいきなり始めるとデバッグが辛い**ので、必ずローカル起動を通してから本番展開する流れをおすすめします。 ### 1. compose.yaml を用意する ``` services: openclaw: image: ghcr.io/openclaw/openclaw:2026.5.7 container_name: openclaw ports: - "18789:18789" environment: OPENCLAW_SKIP_ONBOARDING: "1" OPENCLAW_DISABLE_BONJOUR: "1" volumes: - ./data:/home/node/.openclaw - ./openclaw.json:/home/node/.openclaw/openclaw.json:ro restart: unless-stopped ``` ### 2. openclaw.json の最小構成 ``` { "gateway": { "bind": "custom", "customBindHost": "0.0.0.0", "auth": { "mode": "token", "token": "REPLACE_ME_RANDOM_32CHARS" } }, "models": { "mode": "merge", "providers": { "lemonade-local": { "baseUrl": "http://192.168.11.248:8000/api/v1", "api": "openai-completions", "models": [ { "id": "user.Qwen3.6-35B-A3B-Q4", "name": "Qwen 3.6 35B A3B Q4 (Local)", "reasoning": true, "input": ["text"], "cost": { "input": 0, "output": 0 }, "contextWindow": 262144, "contextTokens": 240000, "maxTokens": 16384 } ] } } }, "agents": { "defaults": { "model": { "primary": "lemonade-local/user.Qwen3.6-35B-A3B-Q4" } } } } ``` ### 3. 起動と動作確認 ``` docker compose up -d curl http://127.0.0.1:18789/healthz # → {"status":"ok"} # ブラウザで http://localhost:18789/ にアクセス # 起動時に gateway token を入れるとログイン完了 ``` ** Docker 推奨の理由 弊社のグローバルルールとして **本番サーバへの直接 `apt install` / `pip install` は禁止**しています。OpenClaw もホストに Node.js を入れず、必ず Docker イメージで稼働させてください。理由は依存関係の汚染防止と、後で k8s に移行する際の互換性確保です。 ## LLM プロバイダ設定（Codex Pro + ローカル fallback） OpenClaw の真価は **LLM プロバイダを混ぜて使える**ところにあります。コード生成のような重い処理はクラウド LLM に投げ、雑談や軽い要約はローカル LLM で済ませる、という**段階運用**がそのまま設定ファイルで書けます。 ### 弊社の本番構成（primary + fallback） ``` { "agents": { "defaults": { "model": { "primary": "openai-codex/gpt-5.5", "fallbacks": [ "lemonade-local/user.Qwen3.6-35B-A3B-Q4" ] } } } } ``` - **primary：**Codex Pro の `gpt-5.5`（OAuth ログインで Codex Pro サブスク枠を利用） - **fallback：**クラウド API 障害・サブスク枠切れ時に Lemonade のローカル Qwen 3.6 35B に落ちる 運用してみるとわかりますが、**「primary が落ちても止まらない」**のは社内 AI の SLA としては大きなメリットです。Qwen の応答品質は GPT-5.5 と比べれば劣りますが、要約・整形・社内検索程度なら十分実用になります。 ** なぜ Lemonade を経由するのか **Lemonade** は llama.cpp 系のローカル推論サーバを OpenAI 互換 API として公開してくれるラッパーです。OpenClaw 側のプロバイダ設定は `"api": "openai-completions"` 1 行で済むので、モデルを Qwen → Gemma → Llama 3 などに差し替えるたびに OpenClaw を触らずに済みます。社内 LLM の入れ替えサイクルが速い現状ではこの分離が効きます。 ## 本番運用：Raspberry Pi 5 + k3s への展開 ローカルで挙動を確認したら、いよいよ社内 k3s に展開します。弊社のリポジトリ `technosphere-openclaw` の `k3s/` ディレクトリには Kustomize 一式を置いてあり、これを `kubectl apply -k` で投入する形にしています。 ### マニフェスト一式の全体像 ``` k3s/ ├── kustomization.yaml ├── namespace.yaml # openclaw namespace ├── configmap.yaml # openclaw.json (Gemma/Qwen + Codex 設定) ├── pvc.yaml # /home/node/.openclaw 永続化（local-path） ├── deployment.yaml # ghcr image + Secret 注入 ├── service.yaml # ClusterIP / LoadBalancer └── ingress.yaml # openclaw.192.168.11.250.sslip.io ``` ### deployment.yaml の要点 ``` apiVersion: apps/v1 kind: Deployment metadata: { name: openclaw, namespace: openclaw } spec: replicas: 1 strategy: type: Recreate # PVC が RWO なので Recreate 必須 template: spec: securityContext: runAsUser: 1000 runAsGroup: 1000 fsGroup: 1000 fsGroupChangePolicy: OnRootMismatch # 起動高速化の必須設定 initContainers: - name: seed-config image: busybox:1.36 # PVC 上に openclaw.json が無いときだけ ConfigMap から seed # → runtime に書き換えた auth profile を保護 containers: - name: openclaw image: ghcr.io/openclaw/openclaw:2026.5.7 ports: [ { name: http, containerPort: 18789 } ] env: - { name: OPENCLAW_SKIP_ONBOARDING, value: "1" } - { name: OPENCLAW_DISABLE_BONJOUR, value: "1" } # ... Secret から各種 API トークンを注入 volumeMounts: - { name: data, mountPath: /home/node/.openclaw } - { name: obsidian-vault, mountPath: /home/node/obsidian-vault } livenessProbe: { httpGet: { path: /healthz, port: http } } readinessProbe: { httpGet: { path: /readyz, port: http } } ``` ** 弊社で踏んだ落とし穴：fsGroupChangePolicy OpenClaw の workspace（skills / canvas / sessions）はファイル数が万単位に膨らみます。`fsGroupChangePolicy` を指定しないと、Pod 起動のたびに **PVC 全体に対して再帰的に chown が走り、起動に数分かかる**事態になりました。`OnRootMismatch` に設定することで、ルートディレクトリのオーナーが正しい限り再帰 chown をスキップでき、起動時間が一気に短縮されます。 ### デプロイスクリプト ``` # scripts/deploy.sh sudo BRIDGE_API_TOKEN= ./scripts/deploy.sh # 内部処理: # 1. namespace 作成 (openclaw) # 2. init-secret.sh で GATEWAY_TOKEN 乱数生成 → Secret 作成 # BRIDGE_API_TOKEN 等の追加トークンがあれば同 Secret に併合 # 3. kubectl apply -k k3s/ # 4. rollout status の完了待ち ``` ### アクセス方法 | 方式 | URL | 備考 | | ポート指定（推奨） | `http://192.168.11.250:18789/` | Service の klipper-lb (svclb) 経由 | | Ingress | `http://openclaw.192.168.11.250.sslip.io/` | Traefik 経由、DNS 解決可能な環境のみ | | port-forward | `http://127.0.0.1:18789/` | 外出先 / VPN 経由のデバッグ時 | ## Secret / ConfigMap / PVC の設計指針 OpenClaw 運用で意外と効くのが **「どの設定をどこに置くか」**のレイヤ設計です。雑にやると **OAuth トークンが pod 再起動で消える**、**Secret 更新がポッドに反映されない**、**誰がトークンを発行したか分からなくなる**といった事故が起きます。 | レイヤ | 置く物 | 更新頻度 | | ConfigMap | openclaw.json テンプレ（gateway / models / agents） | 低（半年〜年単位） | | Secret | GATEWAY_TOKEN / BRIDGE_API_TOKEN / REDMINE_API_KEY / Google SA JSON / SNS トークン群 | 中（数ヶ月） | | PVC | auth-profiles.json（OAuth 状態）/ skills/ / sessions/ / canvas/ | 高（毎日） | ** init-container での seed パターン 弊社では `ConfigMap → PVC` の seed を **init-container で「PVC が空のときだけ」**実行する設計にしました。これにより、Pod が再起動しても PVC 側の runtime 設定（OAuth トークン / カスタムスキル）が ConfigMap で上書きされません。一方、設定を完全に作り直したいときは `kubectl delete pvc openclaw-data` で意図的にリセットできます。 ### 典型的な Secret キー一覧（弊社の例） ``` # openclaw-secrets （Secret） GATEWAY_TOKEN # OpenClaw 自身のゲートウェイ認証 BRIDGE_API_TOKEN # NAS の chatgpt-bridge → gpt-image-2 REDMINE_URL # 社内 Redmine REDMINE_API_KEY # 〃 GSK_API_KEY # Genspark CLI X_API_KEY/X_API_SECRET # SNS自動投稿 (X) IG_ACCESS_TOKEN # Instagram Graph API FB_PAGE_TOKEN # Facebook Page # openclaw-ga4 （別 Secret） service-account.json # GA4 Data API 用 Google サービスアカウント鍵 ``` ※ Secret は `kubectl create secret generic ... --from-literal=KEY=VALUE` で個別投入。鍵管理は `~/.credentials` に集約し **必ず .gitignore**。 ## 初回 OAuth ログインの儀式 Codex Pro のサブスク枠を OpenClaw から使う場合、初回だけ対話 TTY で OAuth ログインが必要です。Pod 内に `kubectl exec -it` で入って実行します。 ``` POD=$(sudo KUBECONFIG=/etc/rancher/k3s/k3s.yaml \ kubectl get pod -n openclaw -l app=openclaw \ -o jsonpath='{.items[0].metadata.name}') sudo KUBECONFIG=/etc/rancher/k3s/k3s.yaml \ kubectl exec -it -n openclaw $POD -c openclaw -- \ openclaw models auth login --provider openai-codex ``` 表示される URL とコードをブラウザで Codex Pro アカウントに承認すると、トークンが PVC 上の `~/.openclaw/agents/main/agent/auth-profiles.json` に保存されます。gateway は設定変更を **hot reload** するので、ログイン直後から Codex モデルが使えるようになります。 ** トークン期限切れに備える Codex Pro の OAuth トークンは数週間〜数ヶ月で `expiresAt` を超えます。期限切れになると Codex 呼び出しは失敗しますが、**fallback の Lemonade ローカル LLM に自動で落ちる**ため即停止はしません。alertmanager で「24h Codex 0 件」みたいな指標を引いて、トークン更新を促すのが運用上の現実解です。 ## テクノスフィアでハマったポイント 7 つ 弊社が OpenClaw を実運用に乗せるまでに踏み抜いたトラップを、再発防止メモを兼ねて公開します。 ### ① fsGroup の再帰 chown で起動 5 分超 workspace のファイル数が膨らむと、`fsGroup` 適用のための再帰 chown が起動毎に走って **Pod が Ready にならない**事態に。`fsGroupChangePolicy: OnRootMismatch` で解決。 ### ② Gemma の reasoning_content で本文が空 thinking モード対応モデル（Gemma 4 など）は `max_tokens` を小さくすると、**推論パートで全部消費されて本文が返らない**挙動になります。最低でも 2048 トークン、要約系で本気を出すなら 4096〜8192 を確保。 ### ③ コンテキスト長は推論サーバ側が支配 OpenClaw 側の `contextWindow` を 200k に書いても、Lemonade の `recipe_options.json` で `ctx_size: 16384` なら実効 16k です。**下位レイヤを揃えないと意味がない**。 ### ④ 同時実行は LLM 1 インスタンスあたり 3〜4 並列が限界 llama.cpp 系は KV キャッシュ非共有のため、同時セッションが増えると VRAM 不足で落ちます。社内利用で「会議中に同時に 5 人が叩く」みたいなピークが見えたら、Lemonade を 2 つに分けるか、サブスク枠の LLM に逃がす設計を入れる。 ### ⑤ Service の type 選択 Pi5 単一ノード k3s の場合、`type: LoadBalancer` でも k3s 同梱の klipper-lb (svclb) が hostPort 公開してくれて、わざわざ NodePort や Ingress を立てなくても LAN からポート直叩きできます。検証時は **LoadBalancer が一番素直**。 ### ⑥ Pod 内には pip も python3-venv も無い OpenClaw 公式イメージは Node ベース。Python 系スキルを足したいときは **既存スキルの venv にある pip を借りる**パターンが正解です（例：`google-calendar` スキルの venv で `pip install --target=...`）。 ### ⑦ 設定の hot reload と PVC seed の競合 初期は ConfigMap を毎回上書きする init-container にしていましたが、運用で書き換えた auth profile が rollout のたびに消える事故が頻発。**PVC に既存ファイルがあれば seed をスキップ**するロジックに変えて解消。 ** 詳しい運用事例は次回以降の記事で 本記事では環境構築までを扱いましたが、実際の業務効果を生むのは **スキル（skills/）**の設計です。続編として、Obsidian 作業ログ自動同期・Redmine チケット運用自動化、画像生成・ブラウザ自動操作のスキル活用事例を順次公開していきます。 - [OpenClaw スキル活用事例①｜作業ログとRedmine運用を完全自動化](https://technosphere.co.jp/blog/openclaw-skills-obsidian-redmine) - [OpenClaw スキル活用事例②｜画像生成・ブラウザ自動操作で広がる業務自動化](https://technosphere.co.jp/blog/openclaw-skills-image-browser) ## まとめ ### この記事のまとめ - OpenClaw は **サーバ常駐型・LLM 差し替え自由・スキル拡張可能**な OSS の AI エージェント基盤 - Claude Code 等の CLI 系とは違い、**Slack / Web / IDE など複数チャネル**から叩ける社内 AI 窓口として刺さる - まずは **Docker Compose でローカル起動**、動作確認後に k3s へ展開する流れがリスク最小 - LLM は **Codex Pro (primary) + ローカル Qwen/Gemma (fallback)** のハイブリッドが SLA とコストの両立に効く - k3s 展開時は **PVC + Secret + ConfigMap** の役割分離と、**init-container での seed パターン** が運用を安定させる - 初回だけ **OAuth ログインを `kubectl exec -it` で行う**儀式が必要 - **fsGroupChangePolicy / contextSize / 同時実行数 / hot reload と seed の競合**など、本記事に書いた 7 つの落とし穴で時間を失わないように テクノスフィアでは社内 AI アシスタント（OpenClaw / Claude Code / Codex / Lemonade）の構築・運用、社内データを安全に扱える RAG / エージェント基盤の設計をご支援しています。「外部 SaaS に出せないデータを AI に使わせたい」「業務システム連携まで含めて AI を社内に住ませたい」といったご相談は、ぜひお気軽にどうぞ。 ／この内容の受託開発・PoC相談はこちら＼ ### 社内 AI 基盤・AI エージェントの受託開発 OpenClaw / Claude Code を含む社内 AI 基盤の選定・構築・運用、業務エージェント設計、MCP サーバー構築まで、テクノスフィアにお任せください。要件ヒアリングから本番運用まで一気通貫で対応します。 [AI開発サービスを見る](https://technosphere.co.jp/ai-solution) [社内AI基盤構築相談](https://technosphere.co.jp/contact) # OpenClaw # AIエージェント # Kubernetes # k3s # Docker # OSS # LLM # Codex # Qwen # 社内DX ## 次に読む｜OpenClaw シリーズ - [OpenClaw シリーズ スキル活用事例①｜Obsidian作業ログ＋Redmineチケット運用の完全自動化 日次の作業記録を AI が勝手に書き続ける運用とは](https://technosphere.co.jp/blog/openclaw-skills-obsidian-redmine) - [OpenClaw シリーズ スキル活用事例②｜画像生成・ブラウザ自動操作で広がるマルチモーダル業務自動化 gpt-image-2 / Browser Use を OpenClaw に統合](https://technosphere.co.jp/blog/openclaw-skills-image-browser) - [関連記事 RAGチャットボットとは？仕組み・メリット・導入方法 OpenClaw のスキル設計と相性のよい RAG の基礎](https://technosphere.co.jp/blog/what-is-rag-chatbot) - [サービス AI ソリューション開発 社内AI基盤・RAG・エージェント基盤の構築支援](https://technosphere.co.jp/ai-solution) ## よくある質問（FAQ） ### Q. OpenClawとは何ですか？無料で使えますか？ OpenClawは、複数のLLMプロバイダを切り替えながら使える**OSSのAIエージェント基盤**です。ソフトウェア自体は無料で利用でき、費用は接続するLLM（クラウドAPIの従量課金、またはローカルLLMなら電気代のみ）と稼働させるサーバ分だけです。 ### Q. Claude CodeやCursorとの違いは何ですか？ Claude CodeやCursorが開発者個人の手元で動くCLI・IDEプラグインであるのに対し、OpenClawは**HTTPサーバとして常時稼働させ、複数のクライアント・チャネルから接続して使う**「社内共有のAIエージェント」という位置づけです。詳しくはOpenClawとは何かをご覧ください。 ### Q. ローカルLLMだけで運用できますか？ 可能です。ただし応答品質とのバランスから、本記事ではクラウドLLM（Codex Pro）をプライマリ、ローカルLLMをフォールバックにするハイブリッド構成を推奨しています。機密性の高い用途では完全ローカル構成も選択できます。 ### Q. 動かすのにどんな環境が必要ですか？ お試しならDocker Composeによるローカル起動が最短です。本記事ではRaspberry Pi 5 + k3sという小規模構成での本番運用例を紹介しており、専用GPUサーバがなくても社内運用を始められます。 [技術コラム一覧に戻る](https://technosphere.co.jp/blog/)