OpenClaw ゲートウェイはモデル API キー、Webhook 署名シークレット、チャネルトークンを環境変数から読みます——ところが launchd が絡むと macOS における「環境」は一つではありません。本 2026 プレイブックでは Keychain 保管と dotenv ファイルを比較し、対話シェルに漏らさず LaunchAgent へシークレットを配線する方法、ヘッドレスクラウド Mac mini M4 でコンプライアンスを保ちつつチームチャットに貼らないローテ手順をまとめます。
初回ブートストラップは OpenClaw macOS インストール と併読してください。リモートアクセス経路のデバッグでは SSH トンネルによるリモート管理 も参照し、トークンをコピーするためにバインドアドレスを広げる誘惑を避けます。運用衛生は ログ・アップグレード・ロールバックの運用 Runbook に揃え、シークレットのローテがバイナリ更新と同じ変更記録に載るようにします。
ストレージ方式の比較
| 仕組み | 強み | 弱み |
|---|---|---|
| macOS Keychain | OS 保護の ACL。デフォルトでワールドリーダブルではない | ヘッドレス初回は一回限り GUI か security CLI の規律が要る |
ディスク上の .env |
ローカル反復が最速 | バックアップがホームを丸ごとコピーしがち——漏えい経路になりやすい |
Plist EnvironmentVariables |
launchd ネイティブ。IaC で再現可能 | 静止時も平文——plist 権限を 600 に |
シークレット種別のルーティング表
| シークレット種別 | 推奨ストア | ローテ周期 |
|---|---|---|
| LLM プロバイダ API キー | Keychain またはボールトエージェント → プロセス起動時に環境へ | 60～90 日、またはオフボード時 |
| Webhook HMAC シークレット | チャネルごとの Keychain 項目 | 90 日。切替中はデュアルキー |
| 非機密フラグ | Plist または git 管理の設定 JSON | アプリリリースとバージョン管理 |
絶対に：本番キーを Slack・メール・画面録画に貼らない。起きたら即ローテ——「プライベート」メッセージでもバーン済みとみなす。
再現可能なシークレットブートストラップ 8 ステップ
- サービスユーザーを作る：ゲートウェイ専用の非管理者。ホームは
700。 - 帯域外でキー生成：ボールト UI かプロバイダコンソール。シェル履歴に echo しない。
- Keychain に投入：シークレットごとに項目を分け、ラベルとゲートウェイバイナリのみの ACL。
- 起動コマンドをラップ：小さなシェルで
security find-generic-password -wから変数を export して OpenClaw を exec——値ではなく stderr をログ。 - LaunchAgent はラッパーを指す：ProgramArguments はラッパーへ。plist に平文シークレットを置かない。
- ドライラン検証：ゲートウェイ起動、ヘルスエンドポイント確認。移行ならプロバイダ UI で旧キーを失効。
- ローテを文書化：チケットテンプレに依存チャネルとロールバック ≤ 30 分を明記。
- 四半期監査：Keychain パス外で
sk-やANTHROPICを誤って grep しないか。
チームが実際に守る数値ガードレール
3 つの数値を内部 README に載せ、レビューで強制する：ディスク上の平文シークレットファイル上限（本番 0）、長寿命トークンの最大寿命（デフォルト 90 日）、ゲートウェイアカウントの sudo 可能人数（指名 2 名）。請負アクセスは Keychain ACL を恒久的に広げる代わりに、保守ウィンドウに合わせて SSH キーを期限付きにする。
- Plist 権限：シークレットへのパスを含むファイルはすべて
chmod 600。本文が Keychain にあっても同様。 - ラッパータイムアウト：Keychain 参照は 2 秒未満。超えるとヘッドレスで UI プロンプトがブロックしているサイン——一度 VNC で確認して再テスト。
- シークレット最大経過：180 日ローテなしは次スプリントで強制チケット。
シークレットを印字せず監査ログを取る
コンプライアンスは「誰がキーに触れたか」を聞きます——「キーの中身」ではありません。ゲートウェイログには資格情報ソースのハッシュ指紋（Keychain 項目 UUID、ボールトパス、ローテバッチ ID）を出し、リテラルトークンは出さない。OpenClaw のエラーでは上流 API キーを含みうるクエリをマスク。多くの HTTP クライアントが URL 全文をログします。SOC 的統制ならホット 30 日、コールド 1 年。SSH セッション録画はブレイクグラス口座のみ。日常はレビュー済み設定変更へ寄せ、ライブ貼り付けを避ける。
dev/stage/prod でゲートウェイを分けるなら Keychain パーティションも分け、~/Library/Keychains をホスト間コピーしない——破損扱いやヘッドレスでの無限プロンプトの原因になります。環境ごとに項目を再ブートストラップし、内部 Wiki に項目名を書き、security find-generic-password -a service -s LABEL で存在確認だけできるようにします。
レンタル Mac 上のヘッドレス macOS の落とし穴
クラウド Mac に「常に許可」をクリックする人はほぼいません。初回 Keychain 承認は VNC で完了し、2 日目以降の編集は SSH。複数エンジニアが同一アカウントを共有すると ACL がぼやける——クレデンシャル共有ではなく環境ごとにゲートウェイを分ける。デバッグで人間可読な環境が一時的に必要なら ramdisk のファイルをログアウトで消し、一部イメージではリブート後も残る /tmp は避ける。
NodeMac は香港・日本・韓国・シンガポール・米国で SSH と VNC 付きの専用 Mac mini M4 を提供——自動化は SSH、TCC プロンプトは VNC の実用的分割です。本番シークレットをステージング実験から隔離するホスト構成は リージョン別料金 で比較できます。ボールト駆動デプロイをフリートへ広げる前に ヘルプ で SSH 鍵オンボーディングを確認してください。
FAQ
シークレットは LaunchAgent plist と同じ git リポジトリに置く？
plist の構造と非機密キーだけ——機密値は決して。CI のデプロイジョブがインストール時にボールト API へ取りに行く形にします。
キーローテで API 使用量を二重課金しないには？
コンソールで新旧を並行有効にし、新しい Keychain 項目でゲートウェイをデプロイしつつ旧キーを維持、24 時間グリーンを見てから旧キーを失効。真夜中の一括切替でラッパーの typo が中途半端に失敗するパターンを避けます。
Mac mini M4 は OpenClaw のシークレット処理に強いプラットフォームです：Apple Silicon は常時デーモンに効率的、ネイティブ Keychain はサービス ID と統合、物理分離はコンプライアンス質問票のハイパーバイザ側チャネルノイズを減らします。NodeMac は HK・JP・KR・SG・US で SSH／VNC 付き専用 Mac mini を提供し、ゲートウェイを予測可能なベアメタルに載せられます。オンデマンド賃借で、5 クローゼット分の Mac を前払いせずリージョンごとにハードンド「シークレット参照」ホストを複製できます。