2026年、OpenClaw MCP の環境変数：SSH セッションでは見える API キーが launchd ゲートウェイから消える理由（ProxyMac Mac mini）
ディスクと PATH のベースラインが緑なら、SSH 初回ブートチェックリスト（2026-05-13） と本稿をセットで読んでください。OpenClaw を 香港・日本・韓国・シンガポール・米国 にまたがるレンタル Mac mini M4 で運用しているチームは、対話的な SSH では完璧に動くバイナリが、デーモン経由の MCP ツールだけ「API キー欠落」で落ちる—というパターンを繰り返し見ます。原因がほぼ無いのは「OpenClaw が暗号を忘れた」ではなく、別々のプロセス木が別々の環境ブロックを継承している ことです。本稿では (1) launchd の LaunchAgent がどう変数を削るか、(2) 非ログインシェルが整った .zshrc を読み飛ばす理由、(3) Terminal・SSH・launchd を並べた 三層比較表、(4) 強化された plist パターンと任意のラッパ、(5) 推測を止める 9 段階監査、(6) ログへトークンを垂れ流さずシークレット指針へ揃える方法をまとめます。横断リンクとして PATH と Homebrew、Keychain とシークレット、JSONL 診断、dev／staging／prod の分離 を参照してください。
運用上は「開発者が自分のシェルで試した結果」と「夜間も動くべきサービスアカウントの常駐プロセス」を同一視しないことが出発点です。前者はログイン・対話の文脈でファイルやキーチェーンを開ける一方、後者は権限とファイル記述子の最小集合だけを持ちます。ここを混ぜると、認証まわりのミドルウェアが DNS 再試行や認証エンドポイントへの再接続を繰り返し、レイテンシ問題に見えることがあります。
プロセス木が違えば、環境の DNA も違う
mini に SSH して openclaw を手で叩く場合、シェルはログインまたは対話として動き、~/.zprofile や ~/.zshrc が読まれ、ここに書いた export FOO=bar がそのセッション全体へ伝播します。ブート時に立ち上がる LaunchAgent が継承するのは launchd が注入したものだけで、典型的には PATH は縮められ /opt/homebrew/bin が消え、先週追記したトークンはそもそも知りません。ゲートウェイから fork される MCP 子プロセスはこの薄い環境をコピーするため、ターミナルエミュレータだけに存在する変数はモデルが呼び出すツールから見えません。
- スケールしたギャップ： エスカレーションでは「SSH では動くがデーモンでは落ちる」の報告のおよそ 35% が、エクスポートを
EnvironmentVariablesかラッパへ移しただけで終わる。 - タイムアウトの誤読： キー欠落で SDK が DNS や認証をリトライすると 30〜45 秒 のハングに見えることがあり、HK→US の経路ロスと混同されやすい。
- 並行性： 並列エージェント を複数走らせるほど、競合なく環境を読み込む設計が重要になる。
この節の実務的結論は、「SSH で export したら production に反映された気になる」運用をやめることです。変更は plist、ラッパ、または鍵管理パイプラインにのみ入れ、シェル履歴に秘密が残らないフローを組みます。
三つ組マトリクス：GUI Terminal／SSH／launchd
| ソース | 典型的な PATH | .zshrc を読むか | Keychain ヘルパが見えるか | MCP 本番向け推奨 |
|---|---|---|---|---|
| Terminal.app のログインシェル | Homebrew 込みのフル | はい | ユーザセッション経由でしばしば | いいえ—ドリフトリスク |
ssh user@host command | シェルモード次第 | 場合により | 不定 | デバッグ限定 |
| LaunchAgent | plist で定義 | いいえ | コードしたときだけ | はい—明示環境 |
表の「本番向け推奨」はセキュリティと再現性の観点です。開発者各自のローカルシェル設定に依存すると、オンボーディングとインシデント対応の両方が再現不能になります。
plist パターン：EnvironmentVariables、ProgramArguments、小型ラッパ
Apple のドキュメントどおり、LaunchAgent の plist には EnvironmentVariables 辞書を置けます。NODE_ENV=production や PYTHONNOUSERSITE=1 のような非秘密フラグに向きます。秘密はサービスユーザだけが読めるファイル（chmod 600）へ退避するか、security find-generic-password で資格情報を取り出してから exec する Node ラッパを噛ませます。ラッパは /usr/local/libexec や専用の ~svc/bin に置き、所有権を固定してください。
この節の変更は ゲートウェイ再起動とリカバリ とセットで、編集のたびに試験済みの launchctl kickstart -k 手順へ載せます。
plist の XML エスケープや ProgramArguments の配列順を誤ると、シェル一行で書けていた設定が黙って無視されます。diff をレビューに載せ、ステージング mini で smoke を通してから本番へ載せ替えてください。
「MCP がキーを見えない」9 段階監査
- launchd 下で再現： 手動 SSH を止め、実際のゲートウェイ経由だけで失敗ツールを叩く。
- launchd の env を dump：
launchctl print gui/$(id -u)/com.example.openclaw（ラベルは環境に合わせる）で EnvironmentVariables を読む。 - PATH を比較： Homebrew が消えているなら絶対パスか PATH キーで補う—詳細は PATH 記事。
- シェルモードを試す：
ssh host 'env'とssh -t host zsh -lic envを並べ、ログイン／非ログイン差を露出させる。 - MCP 設定ファイルを突合： サーバによって
API_KEYとOPENAI_API_KEYなど期待名が違う。上流ドキュメントに合わせる。 - stdio バッファを疑う： 無音ハングは認証ではなくバッファのことがある。stdio ガイド を見る。
- JSONL を横断： ツール失敗を 構造化ログ と突き合わせ、外部共有前にトークンをマスク。
- ulimit を確認： 大量バッチで記述子が枯れると環境とは無関係に落ちる。ulimit 記事 を参照。
- 修正を記録： plist の差分にチケット ID を紐づけ、設定のバージョン管理 実践へ載せる。
9 段階はチェックボックスですが、順序には意味があります。まず「どのプロセスが親か」を固定しないまま PATH をいじると、別ユーザや別ドメインのジョブを誤って調整する事故が起きます。
シークレット境界：Keychain、ファイル、ローテーション
LaunchAgent から Keychain にアクセスするには適切な ACL が要り、対話 Terminal は視覚プロンプトで救われてもヘッドレスデーモンは閉じたまま失敗します。シークレット衛生 に沿って自動化用キーチェーンを分け、規制ワークロードでは 90 日 ローテーションを前提にします。HK／JP／KR／SG／US の複製インスタンス間ではポリシーを共有し、場当たりの .env 複製を避けてください。
一台の mini を複数テナントで共有するラボ（推奨されないが現場ではある）では、分離ガイド に沿って環境変数名を名前空間し、ステージングが本番トークンを継承事故で読まないようにします。
クラウド側でユーザ権限とデーモン権限がズレていると、ファイルベースのシークレットでも片方だけ読める状態が起きます。ls -le と監査ログで所有者と POSIX ACL を確認してください。
FAQ
OpenClaw をコンテナ化すれば環境問題は消えるか？ 再現性は上がるが、明示の -e かシークレットボリュームが依然必要で、無料ランチではない。
ProgramArguments で .env を source できるか？ launchd 自体は dotenv を解釈しない。シェルラッパ経由にするしかない。
sudo -E は？ 昇格しつつ呼び出し元環境を残せるのでテストには便利だが、恒久的な MCP 戦略には攻撃面が広がりすぎる。
追加で、組織 ID の切り替えや複数クラウドプロバイダキーを同一ホストで使う場合は、変数名の衝突よりも「どの LaunchAgent ラベルがどのファイルを読むか」の線引きが先です。
MCP の環境を硬くするなら ProxyMac Mac mini が適している理由
HK／JP／KR／SG／US に置いた専用 Mac mini M4 は、長寿命の launchd 監督者とラッパのための予測可能なファイルパス、常時オンゲートウェイ向けの Apple Silicon 効率を一度に提供します—地域ごとに金属を買い占める必要はありません。CI・ステージング・本番で環境ブロックが揃えば、SSH からログアウトした瞬間にエージェントがフラップする現象も止まります。コロケーションの比較は 料金、アクセスパターンの確認は ヘルプセンター、Keychain の視覚プロンプトが要る検証は VNC でリハーサルしてください。
