OpenClaw 閘道行程讀取的設定裡，既有顯式欄位，也有透過 SecretRef 間接掛載的權杖與憑證路徑。只要啟動方式從「SSH 裡手動 openclaw gateway」換成「使用者域 LaunchAgent 自動拉起」，PATH、HOME、LANG、SSH_AUTH_SOCK 以及 Keychain 是否解鎖 都可能與你在終端機裡看到的不一致。
 
     
讀完本文，你將得到：① 以 openclaw env 列印的可對齊快照；② LaunchAgent 與 SSH 前景對照矩陣；③ SecretRef 型態與風險取捨；④ 七步 Runbook + 可引用閾值；⑤ FAQ。全文假設主機為實體 Mac（非容器內嵌 macOS），以便討論真實 Keychain 與檔案權限。
 
    
 
  
    
    
 
     
 
      
環境繼承鏈不同。SSH 登入工作階段會執行 shell profile，可能悄悄改了 PATH 與 nvm／fnm；LaunchAgent 由 launchd 直接 exec，預設只有 plist 裡顯式宣告的 EnvironmentVariables，極易漏掉「你以為全域生效」的 export。
 
      
SecretRef 解析依賴檔案位置與權限。若 Ref 指向 ~/.openclaw/secrets/...，而作業的工作目錄或 HOME 與互動使用者不一致，相對路徑會靜默指向錯誤位置，表現為偶發 401 或啟動階段直接退出。
 
      
Keychain 與明文 plist 的合規張力。把 API Token 寫進 plist 的 EnvironmentVariables 最快，但備份、設定管理工具與磁碟鑑識都會碰到明文；純 Keychain 又可能因無人登入未解鎖而失敗。需要可稽核的折中策略，而不是「先跑起來再說」。
 
     
 
    
 
  
    
    
 
     
下表用於快速判斷「該改 plist 還是改 shell 設定」。使用者域 Agent 以登入使用者身分執行，但與完整 GUI Session 仍可能有 Keychain 差異。
 
     
 
      

        PATH／Node 繼承 
       ~/.zprofile 等，易與前者不一致 環境變數來源 
       EnvironmentVariables、 
       ProgramArguments 包裝指令稿 目前 shell、 
       ssh -o SendEnv、手動 export Keychain 若同使用者已解鎖或互動執行 
       security，更易成功 排障姿勢 改 plist → bootout／bootstrap；看 
       log show 同工作階段跑 
       openclaw env 與閘道指令對比 
      
 
     
 
    
 
  
    
    
 
     
 
      

        plist 內明文 
       EnvironmentVariables 
      
 
     
 
    
 
  
    
    
 
     
CLI 子命令 openclaw env（若你的發行版使用同名指令）用於在目前行程脈絡列印解析後的環境：包括合併後的 PATH、OpenClaw 辨識的設定路徑、以及 SecretRef 是否已解析為具體值或僅顯示指紋／占位（取決於日誌層級與安全模式）。
 
     
建議在兩種情境各執行一次並 diff：① SSH 登入後、與正式環境相同的 shell；② 以 launchctl asuser 或最小包裝指令稿模擬 LaunchAgent 環境。下方為示意輸出（欄位名隨版本可能微調）：
 
     
$ openclaw env --json 
 
     
{ “configPath”: “/Users/deploy/.openclaw/openclaw.json”, “node”: { “execPath”: “/opt/homebrew/bin/node”, “version”: “v22.14.0” }, “env”: {
 
     
"PATH": "/opt/homebrew/bin:/usr/bin:/bin", "HOME": "/Users/deploy", "OPENCLAW_PROFILE": "prod-gateway" 
 
     
}, “secrets”: {
 
     
"anthropic": { "ref": "keychain:service:openclaw-anthropic", "resolved": true }, "webhookHmac": { "ref": "file:~/.openclaw/secrets/webhook.hmac", "resolved": true } 
 
     
} }
 
    

 
若 resolved: false 或 node 路徑指向系統舊版，而你在互動 shell 裡已經 fnm use 22，幾乎可以斷定是 LaunchAgent 未注入 PATH——在 plist 增加 PATH 與 NODE_BINARY，或改為以絕對路徑的包裝指令稿啟動閘道。
 
  
    
    
 
     
 
      
固定身分：確認 LaunchAgent plist 位於 ~/Library/LaunchAgents 且 UserName（若使用）與手動除錯使用者一致。
 
      
採集 SSH 基線：登入後執行 openclaw env --json > /tmp/env.ssh.json。
 
      
採集 launchd 基線：在無人值守視窗重啟 Agent 或 launchctl kickstart 後，從同機另一工作階段讀取閘道行程環境（或讓包裝指令稿把 openclaw env 重新導向到日誌）。
 
      
Diff 關鍵欄位：PATH、HOME、LANG、TMPDIR、與 OpenClaw 相關的 OPENCLAW_*；SecretRef 是否解析失敗。
 
      
修正 plist：補齊 EnvironmentVariables，或以 /bin/zsh -lc '/opt/homebrew/bin/openclaw gateway' 強制經過登入 shell（注意引號與效能）。
 
      
Keychain 分診：對失敗的 SecretRef 執行 security find-generic-password -s "service" -a "account" -w 驗證可讀性；不可讀則調整 ACL 或改檔案型 SecretRef。
 
      
迴歸：openclaw doctor、打一則最小 Webhook 或本機回環探測，確認無「首輪成功、重啟後失敗」。
 
     
 
     
 
     
       
        
 
     
" target="_blank">http://www.apple.com/DTDs/PropertyList-1.0.dtd”> 
       
        
        
          Label 
         
        
          com.example.openclaw.gateway 
         
        
          ProgramArguments 
         
         
        
      
 
     
 
     
       
       
         /opt/homebrew/bin/openclaw 
        
     
       
       
         gateway 
        
 
     
 
      
        EnvironmentVariables 
       
      
 
     
 
     
       
       
         PATH 
        
     
       
       
         /opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin 
        
     
       
       
         HOME 
        
     
       
       
         /Users/deploy 
        
 
     
 
      
        RunAtLoad 
       
       
 
    

 
將敏感權杖寫入上表 最後手段；更穩妥是保持 plist 乾淨，僅引用 SecretRef 與檔案權限受控的金鑰路徑。
 
  
    
    
 
     
 
      
檔案權限：含金鑰的 plist 或 secret 檔案建議 chmod 600，目錄 chmod 700；群組共用目錄需單獨設計 POSIX ACL，避免「同群組唯讀」誤配。
 
      
Node 主版本：與 OpenClaw 發行說明一致（範例採 Node 22 LTS）；LaunchAgent 情境務必以 which node 對齊到 Homebrew 絕對路徑。
 
      
排查時效：一次完整「SSH vs launchd」diff 應在 15 分鐘內可重複執行，避免依賴個人筆電裡未文件化的 export。
 
     
 
    
 
  
    
    
 
     
 
      
 
       
LaunchAgent 不會自動讀取你的 ~/.zshrc；除非透過 plist 或包裝指令稿顯式載入。請以本文第二節矩陣對照，並以 openclaw env 兩次取樣確認。
 
      
 
      
 
       
優先檢查鑰匙圈是否解鎖、項目的 ACL 是否允許該二進位讀取；必要時在維護視窗以受控指令稿解鎖，或遷移到檔案型 SecretRef。
 
      
 
      
 
       
強烈不建議。若短期必須，限制檔案權限、禁止同步到雲端硬碟，並規劃一次金鑰輪換遷移到 SecretRef 或外部保管庫。
 
      
 
      
 
       
若錯誤是 command not found 或 Node 版本漂移，先對齊 PATH 與 which node；若是 401/403 或 “secret not found”，再查 SecretRef 解析與掛載順序。openclaw env 會同時給出兩類訊號，減少來回猜。