OpenClawで「envを設定したのにAPIキーが読まれない」「.envとopenclaw.jsonのどちらに書けばいいのかわからない」「DockerやGatewayで環境変数が消える」と悩んでいる人向けに、環境変数まわりを整理しました。OpenClawは複数の場所からenvを読み込みますが、ポイントは既存の値を上書きしないという挙動と、読み込み元の優先順位です。

この記事では、openclaw envで検索する人が知りたいであろう、.envの置き場所、openclaw.jsonのenvブロック、APIキー、Gateway Token、Docker運用、Path-related env vars、ログ診断、レガシー環境変数までまとめます。初めて触る人でも迷わないように、表を多めに使って整理します。

この記事のポイント
✅ OpenClawのenv読み込み優先順位がわかる
✅ APIキーが反映されない原因を切り分けられる
✅ Path-related env varsやログ用envの使い道がわかる
✅ Docker・Gateway・セキュリティ運用の注意点がわかる
今日のセールをまとめてチェック！
本日のセール・タイムセールをまとめてチェックできます。
Amazon
楽天市場
Yahooショッピング
メルカリ

openclaw envの基本と読み込み順序の全体像

openclaw envの基本と読み込み順序の全体像
  1. openclaw envの答えは「どこに書くか」より「どの順番で読まれるか」を理解すること
  2. .envはローカル用とグローバル用で役割を分けること
  3. openclaw.jsonのenvブロックは欠けている値だけを補う場所にすること
  4. APIキーはプロバイダー名に合った変数名で設定すること
  5. Shell env importはログインシェルの値を補助的に取り込む仕組みであること
  6. Runtime-injected env varsはユーザー設定ではなく実行文脈を示す目印であること
  7. SecretRefと${ENV}は似ているが使いどころが違うこと

openclaw envの答えは「どこに書くか」より「どの順番で読まれるか」を理解すること

【AI】【業務効率化】【職場】openclaw envの答えは「どこに書くか」より「どの順番で読まれるか」を理解すること

OpenClawのenvで最初に押さえるべきなのは、環境変数の読み込み元が複数あるという点です。OSの環境変数、カレントディレクトリの.env、グローバルの.env、openclaw.jsonのenvブロックなど、いくつかの入口があります。

ただし、OpenClawの考え方は比較的シンプルです。公式ドキュメントでは、既存の値を上書きしないという方針が示されています。つまり、上位の場所ですでに値が入っている場合、下位の設定は基本的に反映されません。

📌 env読み込みの基本イメージ

優先順位 読み込み元 ざっくりした意味
1 プロセス環境 起動元のシェルやサービスが持っている値
2 カレントディレクトリの.env その作業フォルダ専用のenv
3 ~/.openclaw/.env OpenClaw全体で使うグローバルenv
4 openclaw.jsonのenvブロック 足りない値を設定ファイル側で補う場所
5 Shell env import 有効化した場合だけ、ログインシェルから不足分を取り込む

この順番を知らないまま設定すると、「openclaw.jsonを直したのに変わらない」「.envに書いたのに別のキーが使われる」といった混乱が起きやすくなります。多くの場合、原因はもっと優先順位の高い場所に古い値が残っていることです。

参考：OpenClaw公式ドキュメントでは、環境変数はプロセス環境、カレント.env、グローバル.env、設定ファイルの順に扱われると説明されています。
https://docs.openclaw.ai/help/environment

特に、systemdやDockerなどでOpenClawを動かす場合は注意が必要です。普段のターミナルでecho $OPENAI_API_KEYが表示されても、サービスとして起動したOpenClawが同じ値を見ているとは限りません。起動プロセスが何を持っているかを見る必要があります。

🧭 よくある誤解と正しい見方

よくある誤解 実際の考え方
.envを書けば必ず反映される 既存値があれば上書きされない
openclaw.jsonが最優先 envブロックは不足分の補完に近い
ターミナルで見えるenvはサービスにも見える サービス起動では別環境になる場合がある
APIキー名は何でもよい OpenClawやプロバイダーが読む名前に合わせる必要がある

OpenClawのenv設定は、いきなり細かい変数名から入るより、まず優先順位の地図を持つ方が早いです。どこで設定したかではなく、OpenClawが起動時にどの順番で値を拾うのかを確認するのが近道です。

.envはローカル用とグローバル用で役割を分けること

【AI】【業務効率化】【職場】.envはローカル用とグローバル用で役割を分けること

OpenClawでは、.envを置ける場所が複数あります。代表的なのは、現在の作業ディレクトリに置く.envと、~/.openclaw/.envに置くグローバル.envです。どちらも便利ですが、使い方を分けないと管理がわかりにくくなります。

カレントディレクトリの.envは、特定のプロジェクトや検証環境だけで使いたい値に向いています。一方、~/.openclaw/.envは、OpenClaw全体で共通して使うAPIキーやGateway Tokenなどに向いています。

📁 .envの置き場所と向いている用途

置き場所 向いている用途 注意点
./.env プロジェクト単位の検証 そのディレクトリで起動した時だけ影響しやすい
~/.openclaw/.env OpenClaw全体の共通設定 複数プロジェクトに影響する
Dockerのenv_file コンテナ起動時の注入 コンテナ内から見える範囲を意識する
systemdのEnvironmentFile サービス起動時の注入 ユーザーのシェル設定とは別扱いになりやすい

公式の.env.exampleでも、ローカル実行なら.env、デーモン運用なら~/.openclaw/.envにコピーする考え方が示されています。つまり、どう起動するかによって適切な置き場所が変わります。

参考：OpenClawの.env.exampleでは、ローカル実行用の.envと、デーモン向けの~/.openclaw/.envが案内されています。
https://github.com/openclaw/openclaw/blob/main/.env.example

セキュリティ面では、.envをGitに入れないことが重要です。APIキーやトークンが入るため、.gitignoreで除外されているか確認する必要があります。特にDocker構成をGitHubに置く場合、docker-compose.ymlは共有しても.envは共有しない形が扱いやすいです。

🔐 .envで管理しやすい代表的な値

種類 例
モデルAPIキー OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY
Gateway認証 OPENCLAW_GATEWAY_TOKEN, OPENCLAW_GATEWAY_PASSWORD
チャネル連携 SLACK_BOT_TOKEN, TELEGRAM_BOT_TOKEN, DISCORD_BOT_TOKEN
追加ツール BRAVE_API_KEY, PERPLEXITY_API_KEY, FIRECRAWL_API_KEY

.envは便利ですが、増えすぎると「どの値が本番用か」「どの値が古いか」が見えにくくなります。運用が長くなる場合は、プロジェクト別、環境別、本番別にファイルの責任範囲を決めておくと事故を減らせます。

openclaw.jsonのenvブロックは欠けている値だけを補う場所にすること

【AI】【業務効率化】【職場】openclaw.jsonのenvブロックは欠けている値だけを補う場所にすること

OpenClawでは、openclaw.jsonの中にenvブロックを書くこともできます。たとえば、OPENROUTER_API_KEYやGROQ_API_KEYのような値を設定ファイル内に書く形式です。

ただし、ここで大事なのは、envブロックも既存の値を上書きしないという点です。すでにプロセス環境や.envに値が入っている場合、openclaw.json側に書いても期待通りに変わらない可能性があります。

🧩 envブロックの位置づけ

項目 内容
主な用途 足りないenvを設定ファイル側で補う
上書き 基本的に既存値を上書きしない
向いている値 秘密度が低い補助的な設定
注意点 APIキーを直書きすると漏えいリスクが上がる

公式ドキュメントでは、envブロックには直接キーを書く形式と、vars配下にまとめる形式が紹介されています。ただし、英語版の情報では、envブロックは文字列値をそのまま扱い、file:...のような省略表現を展開しないことも示されています。

つまり、XAI_API_KEY: "file:secrets/xai-api-key.txt"のように書いても、OpenClawが自動でファイルを読んでくれるとは限りません。ファイルに保存したシークレットを使いたい場合は、SecretRefの対応フィールドを使うのが自然です。

🧪 openclaw.jsonに書く時の判断表

書いてよい可能性があるもの .envやSecretRefに寄せたいもの
ログレベルの初期値 APIキー
軽い挙動設定 Bot Token
開発用の固定値 Gateway Token
秘密ではない補助変数 OAuth系の認証情報

openclaw.jsonはGit管理されることもあります。そのため、設定ファイルにAPIキーを直接書く運用は避けた方が無難です。個人検証であっても、後からリポジトリに入れてしまう可能性があります。

実務的には、秘密情報は.envまたはSecretRef、挙動設定はopenclaw.jsonと分けると整理しやすいです。OpenClawのenvは柔軟ですが、自由に書けるからこそ責任範囲を分けることが大切です。

APIキーはプロバイダー名に合った変数名で設定すること

【AI】【業務効率化】【職場】APIキーはプロバイダー名に合った変数名で設定すること

OpenClawでAIモデルを使うには、OpenAI、Anthropic、Gemini、OpenRouterなどのAPIキーを設定します。この時に重要なのが、プロバイダーが想定している変数名に合わせることです。

たとえばOpenAIならOPENAI_API_KEY、AnthropicならANTHROPIC_API_KEYが代表的です。OpenClawの.env.exampleにも、複数のモデルプロバイダー向けのキー名が並んでいます。

🔑 主要なモデルAPIキーの例

プロバイダー 代表的なenv名 備考
OpenAI OPENAI_API_KEY GPT系モデルで使う
Anthropic ANTHROPIC_API_KEY Claude系モデルで使う
Gemini GEMINI_API_KEY Google系モデルで使う
OpenRouter OPENROUTER_API_KEY 複数モデルのルーティング用途
Groq GROQ_API_KEY 設定例で登場することがある

APIキーが読まれない時は、まず変数名のスペルを見直すのが早いです。OPEN_AI_API_KEYのように余計なアンダースコアが入っていたり、ANTHROPIC_KEYのように省略していたりすると、OpenClawやプロバイダーが期待通りに読めない可能性があります。

また、Raspberry PiでOpenClawを動かす手順では、~/.openclaw/.envにOPENAI_API_KEYを設定し、openclaw.json側でモデルをClaudeからOpenAIに切り替える流れが紹介されています。モデル名とAPIキーの対応がズレると、401系の認証エラーや「API key missing」のような症状につながりやすいです。

⚠️ APIキーまわりの典型的なつまずき

症状 見るべき場所
API key missing .envに正しい変数名で入っているか
401 Unauthorized キーが有効か、対象プロバイダーが合っているか
ClaudeからOpenAIに切り替わらない openclaw.jsonのモデル指定
Dockerでは動かない env_fileやコンテナ内の環境変数

複数のキーを設定すること自体は可能です。ただし、どのモデルを使うかはOpenClaw側のモデル設定にも左右されます。.envにキーを入れるだけではなく、openclaw.json側のモデル指定も合わせて確認する必要があります。

APIキーはコストと権限に直結します。キーが漏れると第三者に使われるリスクがあるため、記事やスクリーンショットに貼らない、Gitに入れない、不要になったキーはローテーションする、という基本運用も忘れないようにしたいところです。

Shell env importはログインシェルの値を補助的に取り込む仕組みであること

【AI】【業務効率化】【職場】Shell env importはログインシェルの値を補助的に取り込む仕組みであること

OpenClawには、ログインシェルから環境変数を取り込むShell env importの仕組みがあります。設定ではenv.shellEnv.enabled、環境変数ではOPENCLAW_LOAD_SHELL_ENV=1が該当します。

これは、ログインシェルを実行して、期待されるキーのうち欠けているものだけを取り込む仕組みです。ここでも既存値を上書きしない考え方が続いています。

🧰 Shell env importの主な設定

設定 意味
env.shellEnv.enabled: true ログインシェルから不足envを取り込む
env.shellEnv.timeoutMs 取り込み処理のタイムアウト
OPENCLAW_LOAD_SHELL_ENV=1 envで有効化する方法
OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000 タイムアウトをenvで指定する方法

この機能は便利ですが、万能ではありません。サービスやDockerで動かしている場合、そもそもログインシェルの環境が期待通りではない場合があります。また、シェル設定ファイルの読み込みに時間がかかると、タイムアウトの原因にもなり得ます。

Shell env importを使うべき場面は、ローカル開発で.zshrcや.bashrcに既にAPIキーを入れていて、それをOpenClawにも補助的に使わせたい時です。ただし、APIキーをシェル設定ファイルに平文で置く運用は、セキュリティ上の判断が必要です。

📌 Shell env importが向いているケース・向かないケース

向いているケース 向かないケース
ローカル検証 本番サービス運用
一時的な開発環境 複数人で共有するGateway
既存シェル設定を活用したい時 厳密な秘密情報管理が必要な時
欠けた値だけ補いたい時 値を明示的に固定したい時

運用を安定させたい場合は、Shell env importに頼りすぎない方が見通しはよくなります。特に本番や常駐運用では、systemdのEnvironmentFileやDockerのenv_fileなど、起動単位で明示的にenvを渡す構成が管理しやすいです。

Runtime-injected env varsはユーザー設定ではなく実行文脈を示す目印であること

【AI】【業務効率化】【職場】Runtime-injected env varsはユーザー設定ではなく実行文脈を示す目印であること

OpenClawには、実行時に自動注入される環境変数があります。代表例がOPENCLAW_SHELLです。これはユーザーが必ず設定するものではなく、OpenClawが子プロセスを起動する時に文脈を示すために使うマーカーです。

たとえば、execツール経由でコマンドを実行する場合はOPENCLAW_SHELL=exec、ACP関連のプロセスではOPENCLAW_SHELL=acpのような値が入ります。英語版のドキュメントでは、CLIから起動した子プロセスにOPENCLAW_CLI=1が付くことも示されています。

🏷️ Runtime-injected env varsの例

変数 値の例 意味
OPENCLAW_SHELL exec execツール経由のコマンド
OPENCLAW_SHELL acp ACPランタイム関連
OPENCLAW_SHELL acp-client ACPブリッジプロセス関連
OPENCLAW_SHELL tui-local ローカルTUIのシェルコマンド
OPENCLAW_CLI 1 CLI起点の子プロセス

この仕組みは、シェルやプロファイル側で「OpenClawから呼ばれた時だけ処理を変える」ような使い方に向いています。たとえば、OpenClaw経由のコマンドでは重い初期化を避ける、特定のPATHだけ追加する、といった制御が考えられます。

ただし、Runtime-injected env varsをAPIキー設定の代わりに使うものではありません。あくまで実行文脈の目印です。OPENCLAW_SHELL=execを書けばOpenClawが動く、という類の設定ではありません。

🧭 ユーザー設定envとランタイムマーカーの違い

種類 例 目的
ユーザーが設定するenv OPENAI_API_KEY 外部API認証
ユーザーが設定するenv OPENCLAW_LOG_LEVEL ログレベル変更
OpenClawが注入するenv OPENCLAW_SHELL=exec 実行文脈の識別
OpenClawが注入するenv OPENCLAW_CLI=1 CLI起点の識別

この区別をしておくと、ドキュメントを読む時に混乱しにくくなります。OpenClawのenv一覧には、ユーザーが設定するものと、OpenClawが自動で入れるものが混ざっています。目的別に分けて見るのがコツです。

SecretRefと${ENV}は似ているが使いどころが違うこと

【AI】【業務効率化】【職場】SecretRefと${ENV}は似ているが使いどころが違うこと

OpenClawでは、環境変数を設定内で参照する方法として${VAR_NAME}形式とSecretRef形式があります。どちらも「設定ファイルに生のキーを書かない」ために役立ちますが、性質は同じではありません。

${VAR_NAME}は、設定文字列の中で環境変数を置換する仕組みです。たとえば、apiKey: "${VERCEL_GATEWAY_API_KEY}"のように書くと、実行時にプロセス環境から値を解決します。

一方、SecretRefは、シークレット参照に対応したフィールドで使うオブジェクト形式です。英語版ドキュメントでは、ファイルソースのシークレットを定義し、それをモデルプロバイダーのapiKeyで参照する例が示されています。

🔐 ${ENV}とSecretRefの比較

項目 ${ENV}文字列 SecretRef
形式 文字列内の置換 オブジェクト参照
向いている用途 シンプルなenv参照 シークレット管理を分けたい時
対応範囲 文字列設定値 SecretRef対応フィールド
注意点 文字列として扱われる 対応フィールドか確認が必要

特に注意したいのは、envブロックそのものがSecretRefやfile:...を解決するわけではない点です。設定ファイルのどこでも同じように使えると考えると、うまく動かない可能性があります。

🧪 使い分けの目安

状況 推奨される考え方
まず動かしたい .envにAPIキーを書く
Git管理する設定からキーを外したい ${ENV}を使う
ファイルや外部シークレット参照を使いたい SecretRef対応フィールドを使う
チームで運用したい シークレット管理サービスの利用も検討する

SecretRefは安全寄りの選択肢ですが、設定はやや複雑になります。個人検証では.env、共有設定では${ENV}、本番に近い運用ではSecretRefや外部シークレット管理、という段階的な考え方がわかりやすいです。

【AI】【業務効率化】【職場】SecretRefと${ENV}は似ているが使いどころが違うこと
忘れる前に！【ふるさと納税】今年もお得に！
ふるさと納税のポイント付与は2025年10月に廃止になりました。
Amazon
楽天市場
Yahooショッピング
メルカリ

openclaw envの実践設定とトラブル回避策

【AI】【業務効率化】【職場】SecretRefと${ENV}は似ているが使いどころが違うこと
  1. Path-related env varsは保存場所と設定ファイルの場所を切り替えるために使う
  2. ログ用envは原因調査の粒度を上げたい時だけ使う
  3. Docker運用では.envとマウント範囲を分けて考えること
  4. Gateway Tokenはリモート接続時の重要な認証情報として扱うこと
  5. nvm環境のTLS失敗はNODE_EXTRA_CA_CERTSを起動前に設定すること
  6. レガシー環境変数はOPENCLAW_に置き換えること
  7. envトラブルは「起動元・優先順位・変数名」の順に確認すること
  8. 総括：openclaw envのまとめ

Path-related env varsは保存場所と設定ファイルの場所を切り替えるために使う

【AI】【業務効率化】【職場】Path-related env varsは保存場所と設定ファイルの場所を切り替えるために使う

openclaw envで調べる人の中には、APIキーだけでなく「OpenClawのデータはどこに保存されるのか」「設定ファイルを別の場所に置けるのか」を知りたい人もいるはずです。そこで重要になるのが、Path-related env varsです。

代表的な変数は、OPENCLAW_HOME、OPENCLAW_STATE_DIR、OPENCLAW_CONFIG_PATH、OPENCLAW_INCLUDE_ROOTSです。これらはAPIキーではなく、OpenClawの内部パスや設定ファイルの場所を変えるために使います。

📁 Path-related env varsの主な役割

変数 目的
OPENCLAW_HOME OpenClawが内部パス解決に使うホームディレクトリを上書き
OPENCLAW_STATE_DIR 状態ディレクトリを変更
OPENCLAW_CONFIG_PATH 設定ファイルのパスを変更
OPENCLAW_INCLUDE_ROOTS $includeが設定ディレクトリ外を参照できる範囲を指定

特にOPENCLAW_HOMEは影響範囲が広い変数です。公式ドキュメントでは、状態ディレクトリ、設定パス、エージェントディレクトリ、セッション、認証情報などの内部パス解決に関わると説明されています。専用サービスユーザーでOpenClawを動かす場合に便利です。

OPENCLAW_STATE_DIRやOPENCLAW_CONFIG_PATHは、よりピンポイントに場所を変えたい時に使います。OPENCLAW_HOMEで全体を切り替えるのか、個別変数で明示的に指定するのかは、運用のわかりやすさで選ぶとよいでしょう。

🧭 どのパス変数を使うべきか

やりたいこと 使う候補
OpenClaw全体を別ホームに隔離したい OPENCLAW_HOME
状態ファイルだけ別ディレクトリに置きたい OPENCLAW_STATE_DIR
設定ファイルだけ別パスに置きたい OPENCLAW_CONFIG_PATH
$includeで共有設定を読みたい OPENCLAW_INCLUDE_ROOTS

ただし、パス関連のenvは便利な反面、設定が分散すると「どこを読んでいるのか」が見えにくくなります。トラブル時には、まず実際にOpenClawがどの設定ファイルと状態ディレクトリを見ているかを確認するのが大切です。

複数エージェントやサービスアカウントを分ける場合、OPENCLAW_HOMEによる分離は有効な選択肢になり得ます。ただし、共有すべき設定と分離すべき認証情報を混ぜないように、ディレクトリ設計を先に決めておく方が安全です。

ログ用envは原因調査の粒度を上げたい時だけ使う

【AI】【業務効率化】【職場】ログ用envは原因調査の粒度を上げたい時だけ使う

OpenClawにはログや診断用のenvも用意されています。代表的なのはOPENCLAW_LOG_LEVELです。debugやtraceのように設定すると、通常より詳しいログを出せます。

ただし、ログを詳しくするほど、情報量が増えます。調査には便利ですが、プロンプトやメッセージの一部がログに含まれる可能性がある設定もあるため、扱いには注意が必要です。

🧾 ログ・診断系envの例

変数 用途
OPENCLAW_LOG_LEVEL ファイルとコンソールのログレベルを上書き
OPENCLAW_DEBUG_MODEL_TRANSPORT モデル通信のタイミング診断
OPENCLAW_DEBUG_MODEL_PAYLOAD モデルペイロード診断
OPENCLAW_DEBUG_SSE ストリーミング診断
OPENCLAW_DEBUG_CODE_MODE コードモード関連の診断

OPENCLAW_DEBUG_MODEL_PAYLOADには、summary、tools、full-redactedのようなモードが示されています。full-redactedは墨消しされるとはいえ、プロンプトやメッセージテキストを含む場合があるとされているため、共有ログに出す時は慎重に扱うべきです。

📌 ログレベルの使い分け目安

状況 使い方
普段の運用 info程度で十分な場合が多い
APIキーが読まれない 起動ログとenv読み込み状況を確認
モデル通信が遅い transport診断を検討
ストリーミングが途切れる SSE診断を検討
コード実行面を調べたい code mode診断を検討

ログ用envは、常時オンにするより問題が起きた時に一時的に上げる運用が向いています。特に本番に近い運用では、ログに秘密情報や本文が残るリスクを考え、必要な期間だけ有効化するのが現実的です。

ログを確認する時は、.envに書いた値だけでなく、OpenClawの起動ログ、Gatewayログ、Dockerログ、systemdのjournalなど、起動方法に応じて見る場所が変わります。Dockerならdocker compose logs、systemdならjournalctlが基本になります。

Docker運用では.envとマウント範囲を分けて考えること

【AI】【業務効率化】【職場】Docker運用では.envとマウント範囲を分けて考えること

OpenClawをDockerで動かす情報も複数見つかります。Dockerのメリットは、ホストマシン全体にOpenClawを直接入れず、コンテナ内に実行環境を閉じ込めやすい点です。ただし、envとボリュームの扱いを間違えると、リスクが残ります。

Dockerでは、.envをenv_fileで読み込ませる構成がよく使われます。ここでAPIキーやトークンをコンテナに渡します。一方で、workspaceやconfigをどこまでマウントするかは別問題です。

🐳 Docker運用で分けて考えるもの

項目 役割 注意点
.env APIキーやトークンを渡す Gitに入れない
docker-compose.yml コンテナ構成を定義 公開ポートに注意
workspace/ AIが触る作業領域 ホスト全体をマウントしない
config/ OpenClaw設定 秘密情報を直書きしない

Docker構成の記事では、Anthropic APIキーを.envに入れ、make startやdocker compose upで起動する流れが紹介されています。また、メモリ制限やCPU制限を入れると、暴走時の影響を抑えやすいと説明されています。

参考：Docker環境でOpenClawを起動する例では、.envにAPIキーを設定し、コンテナ起動後にヘルスチェックやワンショット質問で動作確認する流れが紹介されています。
https://zenn.dev/and_dot/articles/ef838bede2604f

セキュリティ運用では、ポートを127.0.0.1に限定する考え方もよく出てきます。0.0.0.0で公開すると外部から接続される可能性があるため、初心者や個人検証ではローカル限定にする方が扱いやすいです。

🛡️ Dockerで気をつけたいチェックリスト

チェック 理由
.envをGitに入れていない APIキー漏えい防止
ポートを必要以上に公開していない 不正アクセス面を減らす
workspaceを専用フォルダにしている AIが触れる範囲を限定する
Dockerログに秘密情報が出ていない 後から漏れるリスクを減らす
docker compose down -vの影響を理解している ボリューム削除で履歴が消える可能性

Dockerは安全性を高める助けになりますが、完全な安全境界とまでは言い切れません。特に、ホストの重要フォルダを広くマウントすると、コンテナ分離のメリットが薄れます。envは渡す、workspaceは絞る、ポートは閉じるという3点を基本にすると理解しやすいです。

Gateway Tokenはリモート接続時の重要な認証情報として扱うこと

【AI】【業務効率化】【職場】Gateway Tokenはリモート接続時の重要な認証情報として扱うこと

OpenClaw Gatewayは、OpenClawの中核的な接続口です。ローカルモードでは基本的に127.0.0.1に閉じていますが、リモート接続を考える場合はGateway Tokenの扱いが重要になります。

Gateway Tokenは、リモートモードで接続するクライアントを認証するための重要な値です。.env.exampleにもOPENCLAW_GATEWAY_TOKENが掲載されており、Gatewayがループバック以外にバインドする場合は必要になることが示されています。

🔐 Gateway関連のenvと設定

項目 役割
OPENCLAW_GATEWAY_TOKEN Gateway接続用のトークン
OPENCLAW_GATEWAY_PASSWORD 代替認証モードとして使う可能性がある値
Gateway mode local / remoteの切り替え
Gateway port デフォルトでは18789がよく紹介される
Gateway host 127.0.0.1かリモート向けIPかを決める

Gatewayを外部公開する場合、単に0.0.0.0で待ち受ける構成はリスクがあります。リモート運用の記事では、TLS、リバースプロキシ、TailscaleのようなVPNを組み合わせる考え方が紹介されています。

参考：Gatewayガイドでは、ローカルモードとリモートモード、Gateway Token、Tailscaleを使ったリモートアクセスなどが整理されています。
https://www.meta-intelligence.tech/ja/insight-openclaw-gateway

個人や小規模の運用では、TailscaleのようなVPNで閉じたネットワークを作り、Gatewayを直接インターネットに出さない構成が扱いやすい場合があります。これは一般論ですが、ポート開放よりも攻撃対象を小さくしやすいです。

🌐 Gateway公開方式の比較

方式 わかりやすさ セキュリティ面の注意
ローカルのみ 高い 同一マシンからしか使えない
直接公開 低い Token・TLS・制限が弱いと危険
リバースプロキシ経由 中 設定ミスに注意
VPN経由 中 TailnetやACL管理が必要
Docker + localhost公開 高い コンテナとホストのポート対応を確認

Gateway Tokenは、APIキーと同じく秘密情報です。チャット、記事、GitHub、スクリーンショットに出さないようにしましょう。もし漏れた可能性がある場合は、ローテーションを検討するのが自然です。

nvm環境のTLS失敗はNODE_EXTRA_CA_CERTSを起動前に設定すること

【AI】【業務効率化】【職場】nvm環境のTLS失敗はNODE_EXTRA_CA_CERTSを起動前に設定すること

OpenClawの公式ドキュメントでは、nvmでNode.jsを入れているユーザー向けに、web_fetchのTLS失敗について説明があります。Node.jsの組み込みfetch()がnvm同梱のCAストアを使い、必要なルートCAが不足している場合がある、という内容です。

この場合、HTTPSサイトへのfetchが失敗し、fetch failedのような症状になることがあります。OpenClaw自体のAPIキー設定ミスではなく、Node.jsの証明書ストアまわりが原因の可能性があります。

🧪 nvm由来のTLS問題で見るポイント

症状 確認ポイント
web_fetchが失敗する nvm経由のNodeか
多くのHTTPSサイトで失敗 CAストアが古い可能性
APIキー設定は合っている TLSや証明書側を見る
.envに書いても直らない Node起動前に必要な変数か確認

公式ドキュメントでは、LinuxではOpenClawがnvmを自動検出して修正を適用する場合があるとされています。ただし、古いバージョンや直接node ...で起動する場合は、手動でNODE_EXTRA_CA_CERTSを設定する方法が紹介されています。

重要なのは、NODE_EXTRA_CA_CERTSはNodeのプロセス起動時に読まれるという点です。つまり、OpenClaw起動後に~/.openclaw/.envへ書き足しても、期待通りに効かない可能性があります。

📌 NODE_EXTRA_CA_CERTSの考え方

項目 内容
目的 Node.jsに追加CA証明書を指定する
代表例 /etc/ssl/certs/ca-certificates.crt
設定タイミング Node起動前
注意点 OpenClawの.envだけに頼らない方がよい場合がある

この問題は、openclaw envという検索意図から少し外れて見えるかもしれません。しかし、実際には「環境変数を設定したのにWeb取得が動かない」と見えるため、envトラブルとして混同されやすいです。

APIキー、Gateway Token、パス設定を確認しても解決しない場合は、Node.jsやTLS証明書の問題も候補に入れると切り分けが進みます。特にnvm利用環境では見落としやすいポイントです。

レガシー環境変数はOPENCLAW_に置き換えること

【AI】【業務効率化】【職場】レガシー環境変数はOPENCLAW_に置き換えること

OpenClawは、以前の名称や派生情報で語られることがあります。そのため、古い記事や設定例にCLAWDBOT_*やMOLTBOT_*のような環境変数が出てくる可能性があります。

公式ドキュメントでは、OpenClawはOPENCLAW_*環境変数を読むと説明されています。古いプレフィックスは無視され、Gateway起動時に非推奨警告が出る場合があるとされています。

🔁 レガシーenvの置き換え例

古い可能性がある名前 置き換え候補
CLAWDBOT_GATEWAY_TOKEN OPENCLAW_GATEWAY_TOKEN
MOLTBOT_GATEWAY_TOKEN OPENCLAW_GATEWAY_TOKEN
CLAWDBOT_* OPENCLAW_*
MOLTBOT_* OPENCLAW_*

古い記事を参考にする場合、手順自体は役に立っても、環境変数名が現在のOpenClawに合っていない可能性があります。特に2026年時点の情報でも、記事によって古い呼び名や表記が混ざることがあるため注意が必要です。

📚 古い情報を見る時のチェック項目

チェック 理由
変数名がOPENCLAW_か 現行仕様に合うか確認
モデル名が現在も使えるか プロバイダー側で変わる可能性
Dockerイメージ名が現行か 古いタグの可能性
Gatewayポートや認証設定が合うか セキュリティ仕様が変わる可能性
.envの優先順位説明が公式と合うか 誤情報を避けるため

また、OpenClaw以外の環境変数、たとえばOPENAI_API_KEYやANTHROPIC_API_KEYはプロバイダー側のキー名です。OPENCLAW_で始まらないから間違い、というわけではありません。OpenClaw本体の設定系と、モデルプロバイダーのAPIキー系を分けて考える必要があります。

🧭 env名の分類

分類 例
OpenClaw本体 OPENCLAW_HOME, OPENCLAW_LOG_LEVEL
Gateway OPENCLAW_GATEWAY_TOKEN
モデルプロバイダー OPENAI_API_KEY, ANTHROPIC_API_KEY
チャネル連携 SLACK_BOT_TOKEN, TELEGRAM_BOT_TOKEN
追加ツール BRAVE_API_KEY, FIRECRAWL_API_KEY

古いenv名が残っていると、「設定したつもりなのに読まれない」状態になります。.envやサービス定義を見直す時は、値だけでなく変数名の接頭辞も確認しましょう。

envトラブルは「起動元・優先順位・変数名」の順に確認すること

【AI】【業務効率化】【職場】envトラブルは「起動元・優先順位・変数名」の順に確認すること

OpenClawのenvトラブルは、焦って設定を増やすより、順番に切り分ける方が早いです。おすすめの順番は、起動元 → 優先順位 → 変数名です。

まず、OpenClawをどこから起動しているかを確認します。ターミナルから直接起動しているのか、Dockerなのか、systemdなのか、Gatewayデーモンなのかで、見えている環境変数が変わります。

🧭 envトラブル切り分けの順番

順番 確認すること
1 OpenClawの起動元は何か
2 どの.envや設定が読まれているか
3 優先順位の高い場所に古い値がないか
4 変数名が正しいか
5 モデル指定やGateway設定と一致しているか

次に、優先順位を見ます。プロセス環境に古いOPENAI_API_KEYが残っていれば、~/.openclaw/.envを直しても上書きされない可能性があります。OpenClawの「上書きしない」ルールを前提に、上位の値を疑う必要があります。

最後に、変数名を確認します。APIキーの名前、Gateway Token、OPENCLAW_HOMEなど、1文字違いでも読まれません。特にOPENCLAW_*とプロバイダーキーの区別は混同しやすいです。

🧪 症状別の確認表

症状 優先して見る場所
API key missing .env、変数名、モデル設定
401 Unauthorized キーの有効性、対象プロバイダー
Dockerだけ失敗 env_file、コンテナ内env、マウント
サービス再起動後に消える systemdや起動スクリプト
設定ファイルを変えても反映されない プロセス環境や上位.env
web_fetchが失敗 nvm、TLS、NODE_EXTRA_CA_CERTS

セキュリティ面では、トラブル調査中にAPIキーをそのままログやチャットに貼らないことも重要です。echo $OPENAI_API_KEYの結果を共有するのではなく、先頭と末尾だけを伏せて確認するなど、扱い方に気をつけましょう。

OpenClawのenvは、仕組みがわかれば複雑ではありません。むしろ「上書きしない」という一貫したルールがあるため、どこに何が残っているかを順番に見れば原因に近づけます。

総括：openclaw envのまとめ

【AI】【業務効率化】【職場】総括：openclaw envのまとめ

最後に記事のポイントをまとめます。

  1. openclaw envの基本は、環境変数の読み込み優先順位を理解することである。
  2. OpenClawは既存の環境変数を基本的に上書きしない設計である。
  3. 優先順位は、プロセス環境、カレント.env、グローバル.env、openclaw.jsonのenvブロック、Shell env importの順で考える。
  4. .envはローカル用とグローバル用で役割を分けるべきである。
  5. openclaw.jsonのenvブロックは、不足している値を補う用途に向いている。
  6. APIキーはOPENAI_API_KEYやANTHROPIC_API_KEYなど、プロバイダーに合った名前で設定する必要がある。
  7. SecretRefと${ENV}は似ているが、対応フィールドや使いどころが異なる。
  8. Path-related env varsは、保存場所や設定ファイルの場所を切り替えるために使う。
  9. OPENCLAW_HOMEは影響範囲が広いため、サービスユーザーや環境分離で有効である。
  10. ログ用envは、原因調査の時に一時的に使うのが扱いやすい。
  11. Docker運用では、.env、公開ポート、workspaceマウント範囲を分けて考える必要がある。
  12. Gateway Tokenはリモート接続時の重要な認証情報である。
  13. nvm環境でweb_fetchが失敗する場合、NODE_EXTRA_CA_CERTSを起動前に設定する対処が候補になる。
  14. レガシーのCLAWDBOT_*やMOLTBOT_*は、OPENCLAW_*へ置き換えるべきである。
  15. envトラブルは、起動元、優先順位、変数名の順に確認するのが近道である。

関連記事

✓刑務官はやめとけ！！そう言われる6つの理由を解説します。
✓zapier 自動返信メールの作り方が丸わかり！問い合わせ対応をラクにする設定ガイド
✓職場で笑い声がうるさい女に限界…イライラを悪化させず静かにさせる現実的な対処法
✓Zapier対応って結局どれ？使えるアプリ・確認方法・失敗しない自動化の始め方をまるっと整理
✓【徹底調査】新入社員はボーナスを返すのがマナーなのか？お礼の方法やエチケットをご紹介
✓マイナビの他己分析で結果が見れない？🤔 確認方法から活用術まで完全解説！
✓n8n yahoo連携で詰まる前に読む、メール受信とYahoo Finance活用のリアルな解決策
✓パーソナルトレーナーは「やめとけ！」そう言われる6つの理由を解説します。
✓zapier gemで詰まる人へ、Gemini連携の答えを一気に整理
✓上から目線の人の末路：プライドがもたらす自滅への道
記事作成にあたり参考にさせて頂いたサイト

各サイト運営者様へ
有益な情報をご公開いただき、誠にありがとうございます。
感謝の意を込め、このリンクはSEO効果がある形で設置させていただいております。
※リンクには nofollow 属性を付与しておりませんので、一定のSEO効果が見込まれるなど、サイト運営者様にとってもメリットとなれば幸いです。
当サイトは、インターネット上に散在する有益な情報を収集し、要約・編集してわかりやすくお届けすることを目的としたメディアです。
引用や参照の方法に不備、あるいはご不快に感じられる点がございましたら、お問い合わせフォームよりご連絡ください。
今後とも、どうぞよろしくお願いいたします。

AI 業務効率化 職場
ABOUT ME
カシワギ
『エグゼクティブワーク』編集長のカシワギです。 普段はITベンチャーで執行役員の40代男です。 元コンサルタントですが、今はテクノロジー企業で日々奮闘中。 仕事では厳しい顔をしていますが、家では小学生の子供2人のやんちゃなパパ。 休日はゴルフに行ったり、妻とワインを楽しんだり。
BLOG：https://min-biz.net/
当サイトについて
当サイトでは、インターネット上に散らばるさまざまな情報を収集し、AIを活用しながら要約・編集を行い、独自の切り口で見解を交えながらわかりやすい形でお届けしています。 情報の整理・編集にあたっては、読者やオリジナル記事の筆者へご迷惑をおかけしないよう、細心の注意を払って運営しておりますが、万が一、掲載内容に問題がある場合や修正・削除のご要望がございましたら、どうぞお気軽にお問い合わせください。 迅速に対応をさせていただきます。 その際には、該当記事の URLやタイトルをあわせてお知らせいただけますと、より速やかに対応 することができますのでそちらもご協力いただけますと大変幸いでございます。 今後とも当サイトをよろしくお願いいたします。