1. 項目概述為什么我們需要為OpenClaw的GLM-4.7-Flash配置加密最近在折騰OpenClaw一個開源的AI智能體框架發現它確實是個好東西能輕松地把各種大模型、工具和技能串聯起來構建自己的AI助手。特別是當我把GLM-4.7-Flash這類輕量高效的模型接入進去后響應速度和本地推理能力都上了一個臺階。但很快一個現實問題就擺在了面前配置文件里的連接憑證怎么辦OpenClaw的配置文件比如那個關鍵的config.yaml或者.env文件里面往往躺著模型的API密鑰、數據庫的連接字符串、第三方服務的訪問令牌。就拿GLM-4.7-Flash來說如果你用的是云端API服務那個API Key就是打開模型能力的“鑰匙”。把這些敏感信息以明文形式寫在配置文件里然后直接提交到Git倉庫無異于把家門鑰匙掛在公告欄上。一旦倉庫泄露或者服務器被不當訪問后果不堪設想。這不僅僅是GLM-4.7-Flash的問題所有通過OpenClaw集成的、需要憑證的外部服務都存在這個安全隱患。所以這個“配置加密”項目核心目標非常明確為OpenClaw特別是其集成的GLM-4.7-Flash模型連接憑證找到一個既安全又實用的存儲方案。安全意味著憑證不能以明文形式存在實用意味著在部署和運行時OpenClaw能夠無縫、自動地解密并使用這些憑證。這不僅僅是加個密那么簡單它涉及到開發流程、部署流程和密鑰管理策略的整體調整。下面我就結合自己的踩坑經驗詳細拆解一下如何實現這套方案。2. 安全存儲方案的核心設計思路在動手寫代碼或改配置之前得先把思路理清楚。我們的目標不是創造一個“絕對無法破解”的系統那幾乎不存在而是在安全性和易用性之間找到一個合理的平衡點顯著提升攻擊門檻。核心思路可以概括為“環境隔離密鑰分離按需解密”。2.1 從明文配置到加密配置的轉變最原始的、也是最危險的做法就是直接在config.yaml里寫glm_model: api_base: “https://api.example.com/v1 api_key: “sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx“這個文件一旦進入版本控制風險就永久存在了。我們的第一步就是要把api_key這樣的敏感字段替換成一個“密文”或者一個“指向密文的引用”。例如變成glm_model: api_base: “https://api.example.com/v1 api_key_encrypted: “gAAAAABnB6b8...很長一串密文“或者更優雅一點使用一個環境變量名或一個指向加密文件的路徑glm_model: api_base: “https://api.example.com/v1 api_key_ref: “${ENCRYPTED_GLM_API_KEY}“ # 或 “file:///secure/glm_key.enc“2.2 密鑰管理對稱加密與非對稱加密的抉擇加密數據需要密鑰。這里有兩個主流選擇對稱加密如AES加密和解密使用同一個密鑰。優點是速度快適合加密大量數據。但關鍵問題來了這個“同一個密鑰”本身放在哪里如果把它硬編碼在代碼里或另一個配置文件中不過是把“藏鑰匙”的問題轉移了沒有根本解決。非對稱加密如RSA使用公鑰加密私鑰解密。我們可以把公鑰放在開發環境用于加密敏感配置項而私鑰則嚴格保管在生產服務器或**安全的密鑰管理服務KMS**中。運行時OpenClaw進程用私鑰解密。這樣即使加密后的配置文件和公鑰都泄露了攻擊者沒有私鑰也無法解密。對于OpenClaw配置加密這個場景我強烈推薦非對稱加密方案。理由很直接公鑰可以放心地放入代碼庫用于CI/CD流程的加密環節而私鑰永遠不離開生產環境。這完美契合了“密鑰分離”的原則。2.3 集成點讓OpenClaw在啟動時自動解密我們不能要求每次運行OpenClaw都手動輸入解密命令。理想的狀態是OpenClaw在啟動加載配置時能自動識別出需要解密的字段并調用解密邏輯。這通常需要通過一個配置預處理器或自定義的配置加載器來實現。例如我們可以寫一個Python腳本在OpenClaw主程序讀取config.yaml之后、正式使用配置之前攔截配置字典遍歷所有值查找符合特定模式如前綴為enc:或后綴為_encrypted的字段然后用本地存儲的私鑰對其進行解密將解密后的明文替換回配置字典中。這樣OpenClaw的業務代碼感知不到加密過程它拿到的始終是明文但磁盤上存儲的已是密文。3. 基于SOPS與Age的實戰加密方案理論說完了我們來點實在的。經過一番選型我最終采用了SOPSSecrets OPerationS這款工具搭配Age加密算法來管理OpenClaw的加密配置。這是一套在云原生領域備受推崇的方案輕量、易用、且與Git工作流集成良好。3.1 工具選型為什么是SOPSAgeSOPS它不是一個簡單的加密庫而是一個針對YAML、JSON、ENV等配置文件格式的“智能”加密工具。它的強大之處在于可以只加密配置文件中的值比如api_key對應的字符串而保持文件結構鍵名、注釋等明文不變。這樣文件依然可讀、可版本控制只是敏感內容被保護了。Age一個簡單、現代、高效的加密工具。它生成的是簡單的Ed25519密鑰對對應我們說的非對稱加密命令行操作極其簡便。相比傳統的GPGAge沒有復雜的信任網絡密鑰就是簡單的文本字符串管理起來直觀很多。這套組合拳的好處是開發人員用公鑰加密配置加密后的文件可以安全地提交到Git。運維人員在生產環境放置私鑰SOPS在運行時能自動用私鑰解密。整個流程清晰工具鏈成熟。3.2 具體操作步驟假設我們有一個原始的OpenClaw配置文件config.yaml其中包含GLM-4.7-Flash的明文API密鑰。步驟一生成Age密鑰對在生產服務器或你的本地安全環境中生成Age密鑰對age-keygen -o age-key.txt這個命令會生成一個文件age-key.txt內容類似# created: 2024-01-01T00:00:00Z # public key: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p AGE-SECRET-KEY-1U9CPVJ0H8XMK0VQ5FYGZJGN0T2SJW3VK5J6XQ0ZJQZJQZJQZJQZJQ其中以age1開頭的行是公鑰以AGE-SECRET-KEY-開頭的是私鑰。將公鑰age1ql3z7...安全地分發給所有需要加密配置的開發人員。將私鑰AGE-SECRET-KEY-...絕密地保存在生產服務器上例如/etc/openclaw/age-key.txt并設置嚴格的文件權限如chmod 600。步驟二安裝SOPS在開發機和生產服務器上安裝SOPS。以macOS和Linux為例# macOS brew install sops # Linux (通過go安裝) go install go.mozilla.org/sops/v3/cmd/sopslatest步驟三創建.sops.yaml規則文件在OpenClaw項目根目錄創建.sops.yaml文件告訴SOPS如何加密我們的配置文件creation_rules: - path_regex: .*\.yaml$ # 匹配所有yaml文件 age: - age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p # 替換成你的公鑰這個文件可以提交到Git它只包含公鑰信息是安全的。步驟四加密配置文件現在將原始的config.yaml中的敏感值替換為占位符或者直接復制一份為config.enc.yaml用于加密。更常見的做法是直接讓SOPS編輯并加密原文件。但為了清晰我們先加密sops --encrypt --in-place config.yaml執行后config.yaml文件本身會被加密。你會發現像api_key對應的值變成了一串加密的密文數據塊而其他的鍵和結構保持不變。這個加密后的文件就可以安全地提交到Git倉庫了。步驟五開發時編輯加密文件如果你后續需要修改加密文件中的某個非敏感配置或者增加新的敏感項可以直接用SOPS編輯它會自動處理解密和再加密sops config.yaml這會用你默認的編輯器如vim, code打開文件你看到的是解密后的明文編輯保存后SOPS會自動將其重新加密。步驟六生產環境配置與OpenClaw集成這是最關鍵的一步。在生產服務器上我們有了加密的config.yaml和保密的私鑰文件age-key.txt。方案A使用SOPS作為預處理器推薦我們不在OpenClaw的代碼里直接集成解密邏輯而是通過一個啟動包裝腳本。創建一個start_openclaw.sh腳本#!/bin/bash # 設置Age私鑰的環境變量 export SOPS_AGE_KEY_FILE/etc/openclaw/age-key.txt # 使用sops解密配置文件輸出到標準輸出然后作為環境變量或臨時文件傳遞給OpenClaw # 假設OpenClaw支持從環境變量讀取配置或者我們可以生成一個臨時解密文件 DECRYPTED_CONFIG$(sops --decrypt /path/to/openclaw/config.yaml) # 將解密后的配置寫入一個臨時文件確保該文件僅對當前用戶可讀 TEMP_CONFIG$(mktemp) echo “$DECRYPTED_CONFIG” “$TEMP_CONFIG“ chmod 600 “$TEMP_CONFIG“ # 啟動OpenClaw指定使用臨時配置文件 python openclaw_app.py --config “$TEMP_CONFIG“ # 啟動后可刪除臨時文件可選進程持有文件描述符時可能無法立即刪除 rm -f “$TEMP_CONFIG“然后你的系統服務如systemd就啟動這個腳本而不是直接啟動Python程序。方案B在OpenClaw應用層集成解密如果OpenClaw是Python項目你可以在加載配置的代碼部分比如在config.py或主程序開頭集成SOPS解密import subprocess import yaml import os import tempfile def load_encrypted_config(config_path): 加載并解密SOPS加密的配置文件 # 檢查文件是否被SOPS加密過 try: result subprocess.run( [“sops“, “--decrypt“, config_path], capture_outputTrue, textTrue, checkTrue, env{**os.environ, “SOPS_AGE_KEY_FILE“: “/etc/openclaw/age-key.txt“} ) config_data yaml.safe_load(result.stdout) except subprocess.CalledProcessError as e: # 如果解密失敗可能文件未加密則嘗試直接加載 print(f“Decryption failed, trying plain load: {e}“) with open(config_path, ‘r’) as f: config_data yaml.safe_load(f) return config_data # 在主程序中 config load_encrypted_config(“config.yaml“) # 接下來config就是一個包含明文數據的字典可以正常使用了注意無論哪種方案都必須確保生產服務器上的私鑰文件 (age-key.txt) 權限盡可能嚴格如chmod 600并且僅限于運行OpenClaw服務的用戶有權讀取。絕對不要將私鑰提交到任何版本的代碼庫或構建鏡像中除非是專門的安全密鑰管理鏡像且有其特定流程。4. 方案進階與密鑰管理實踐基礎的SOPSAge方案已經能解決大部分問題但在團隊協作和更復雜的生產環境中我們還需要考慮更多。4.1 多環境與多密鑰管理一個項目通常有開發、測試、生產等多個環境。每個環境應該使用不同的Age密鑰對。這樣可以實現環境隔離開發配置泄露不會影響生產。在.sops.yaml中你可以定義更復雜的規則根據文件路徑匹配不同的公鑰。creation_rules: - path_regex: config/production/.*\.yaml$ age: age1productionpublickey... - path_regex: config/staging/.*\.yaml$ age: age1stagingpublickey... - path_regex: config/development/.*\.yaml$ age: age1developmentpublickey...在生產服務器上只部署對應環境的私鑰。4.2 與CI/CD流水線集成在自動化部署流程中如何安全地使用私鑰硬編碼在流水線腳本里同樣是危險的。推薦的做法是使用CI/CD系統提供的**機密變量Secrets**功能。GitHub Actions 將Age私鑰的內容存入倉庫的Settings - Secrets and variables - Actions中命名為AGE_SECRET_KEY。然后在 workflow 文件中jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Decrypt config for deployment run: | echo “${{ secrets.AGE_SECRET_KEY }}“ /tmp/age-key.txt sops --decrypt --age /tmp/age-key.txt config.enc.yaml config.yaml # 接下來使用解密后的config.yaml進行部署GitLab CI、Jenkins等也有類似的機密存儲功能。核心原則是私鑰只以環境變量的形式存在于流水線運行時內存中不落地到日志或普通文件。4.3 密鑰輪換與應急預案沒有任何密鑰是永恒的定期輪換密鑰是安全最佳實踐。生成新密鑰對 按照上述步驟生成新的Age密鑰對。更新加密配置 用新的公鑰重新加密所有配置文件。使用SOPS可以很方便地編輯加密文件在編輯保存時會自動使用.sops.yaml中當前生效的公鑰可以配置多個接收方重新加密。部署新私鑰 將新私鑰安全地部署到生產服務器替換或與舊私鑰并存如果SOPS配置了多個接收方則可以用多個私鑰解密。驗證與切換 驗證新私鑰可以成功解密配置文件并確保OpenClaw服務正常運行。廢棄舊密鑰 確認一切正常后從.sops.yaml中移除舊公鑰并安全地銷毀舊私鑰。應急預案務必保留一份加密配置的明文備份通過安全的離線方式存儲如密碼管理器以防密鑰丟失導致所有配置無法解密、服務完全癱瘓。同時確保部署和回滾流程不依賴于單一的密鑰解密步驟。5. 常見問題與故障排查實錄在實際操作中你肯定會遇到一些坑。這里記錄了幾個我踩過以及社區常見的問題。5.1 SOPS解密失敗權限問題與密鑰格式問題現象 執行sops --decrypt config.yaml時報錯提示Error: failed to get the data key或age: no identity matched any of the recipients。排查思路檢查私鑰文件路徑和權限 確保SOPS_AGE_KEY_FILE環境變量指向正確的路徑并且運行SOPS的用戶對該文件有讀取權限。使用ls -l /etc/openclaw/age-key.txt檢查權限是否為600。檢查私鑰內容 確保私鑰文件內容完整以AGE-SECRET-KEY-開頭且沒有多余的空格或換行。可以用cat -A /etc/openclaw/age-key.txt檢查是否有不可見字符。確認加密所用的公鑰 使用sops config.yaml查看加密文件的元數據它會列出加密時使用的所有公鑰。確保你當前持有的私鑰與其中至少一個公鑰對應。環境變量未生效 在腳本或服務中確保環境變量在調用SOPS命令之前已經正確設置。有時候在systemd service文件中設置環境變量需要特別注意語法。5.2 OpenClaw啟動時找不到解密后的配置問題現象 解密腳本執行成功生成了臨時配置文件但OpenClaw啟動報錯提示找不到某個配置項或配置文件格式錯誤。排查思路檢查臨時文件內容 在啟動腳本中在啟動OpenClaw之前添加一行cat “$TEMP_CONFIG“或將內容輸出到日志確認解密后的YAML格式是否正確、完整。檢查文件路徑傳遞 確保傳遞給OpenClaw的--config參數是臨時文件的絕對路徑。相對路徑可能因工作目錄不同而導致找不到文件。檢查OpenClaw配置加載邏輯 確認你的OpenClaw應用確實是通過你傳遞的參數來加載配置的。有些框架可能有默認的配置文件路徑和加載順序。進程權限 確保運行OpenClaw的用戶對臨時文件有讀取權限。使用mktemp創建的文件默認所有者是當前用戶通常沒問題。5.3 在Docker容器中運行時的密鑰管理問題描述 使用Docker部署OpenClaw時如何安全地將私鑰注入容器解決方案絕對不要將私鑰直接打包進Docker鏡像。有以下安全方法Docker SecretsSwarm模式 如果你使用Docker Swarm可以使用docker secret管理私鑰并在服務中掛載為內存文件。Kubernetes Secrets 在K8s中將Age私鑰創建為Secret對象然后通過Volume掛載或環境變量注入到Pod中。動態掛載 在docker run或docker-compose中通過-v卷掛載將宿主機上的私鑰文件映射到容器內特定路徑。務必控制宿主機上源文件的權限。# docker-compose.yml 示例片段 services: openclaw: image: your-openclaw-image volumes: - “/etc/openclaw/age-key.txt:/run/secrets/age-key.txt:ro“ environment: - SOPS_AGE_KEY_FILE/run/secrets/age-key.txt環境變量注入 在啟動容器時通過-e將私鑰內容作為環境變量傳入。注意命令行歷史可能泄露更安全的方式是通過文件或編排工具設置。docker run -e SOPS_AGE_KEY“$(cat /etc/openclaw/age-key.txt)“ your-openclaw-image5.4 配置項部分加密與混合加密策略有時我們可能只想加密配置文件中的幾個字段而不是整個文件。SOPS完美支持這一點它默認就是加密YAML/JSON中的字符串值。但如果你有一些非字符串的敏感信息或者想加密整個區塊可以在編輯加密文件時直接修改那些值SOPS會處理加密。對于混合策略比如有些配置來自環境變量有些來自加密文件可以在OpenClaw的配置加載邏輯中做優先級合并先加載加密的base配置然后用環境變量覆蓋特定的值。這樣即使某些關鍵憑證通過更動態、更安全的方式如云平臺的IAM角色提供也能兼容。最后再分享一個小心得在團隊中推行配置加密文檔和工具鏈的完善至關重要。你需要編寫清晰的README說明如何安裝SOPS、如何獲取公鑰、如何加密新配置。可以考慮將加密/解密腳本封裝成Makefile任務或簡單的Python工具降低團隊成員的使用門檻。畢竟安全措施如果太復雜導致大家不愿意用反而會滋生更大的風險——比如有人圖省事又把明文密鑰寫進了配置文件。 OpenClaw配置加密實戰：基于SOPS與Age保護GLM-4.7-Flash等模型密鑰
1. 項目概述為什么我們需要為OpenClaw的GLM-4.7-Flash配置加密最近在折騰OpenClaw一個開源的AI智能體框架發現它確實是個好東西能輕松地把各種大模型、工具和技能串聯起來構建自己的AI助手。特別是當我把GLM-4.7-Flash這類輕量高效的模型接入進去后響應速度和本地推理能力都上了一個臺階。但很快一個現實問題就擺在了面前配置文件里的連接憑證怎么辦OpenClaw的配置文件比如那個關鍵的config.yaml或者.env文件里面往往躺著模型的API密鑰、數據庫的連接字符串、第三方服務的訪問令牌。就拿GLM-4.7-Flash來說如果你用的是云端API服務那個API Key就是打開模型能力的“鑰匙”。把這些敏感信息以明文形式寫在配置文件里然后直接提交到Git倉庫無異于把家門鑰匙掛在公告欄上。一旦倉庫泄露或者服務器被不當訪問后果不堪設想。這不僅僅是GLM-4.7-Flash的問題所有通過OpenClaw集成的、需要憑證的外部服務都存在這個安全隱患。所以這個“配置加密”項目核心目標非常明確為OpenClaw特別是其集成的GLM-4.7-Flash模型連接憑證找到一個既安全又實用的存儲方案。安全意味著憑證不能以明文形式存在實用意味著在部署和運行時OpenClaw能夠無縫、自動地解密并使用這些憑證。這不僅僅是加個密那么簡單它涉及到開發流程、部署流程和密鑰管理策略的整體調整。下面我就結合自己的踩坑經驗詳細拆解一下如何實現這套方案。2. 安全存儲方案的核心設計思路在動手寫代碼或改配置之前得先把思路理清楚。我們的目標不是創造一個“絕對無法破解”的系統那幾乎不存在而是在安全性和易用性之間找到一個合理的平衡點顯著提升攻擊門檻。核心思路可以概括為“環境隔離密鑰分離按需解密”。2.1 從明文配置到加密配置的轉變最原始的、也是最危險的做法就是直接在config.yaml里寫glm_model: api_base: “https://api.example.com/v1 api_key: “sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx“這個文件一旦進入版本控制風險就永久存在了。我們的第一步就是要把api_key這樣的敏感字段替換成一個“密文”或者一個“指向密文的引用”。例如變成glm_model: api_base: “https://api.example.com/v1 api_key_encrypted: “gAAAAABnB6b8...很長一串密文“或者更優雅一點使用一個環境變量名或一個指向加密文件的路徑glm_model: api_base: “https://api.example.com/v1 api_key_ref: “${ENCRYPTED_GLM_API_KEY}“ # 或 “file:///secure/glm_key.enc“2.2 密鑰管理對稱加密與非對稱加密的抉擇加密數據需要密鑰。這里有兩個主流選擇對稱加密如AES加密和解密使用同一個密鑰。優點是速度快適合加密大量數據。但關鍵問題來了這個“同一個密鑰”本身放在哪里如果把它硬編碼在代碼里或另一個配置文件中不過是把“藏鑰匙”的問題轉移了沒有根本解決。非對稱加密如RSA使用公鑰加密私鑰解密。我們可以把公鑰放在開發環境用于加密敏感配置項而私鑰則嚴格保管在生產服務器或**安全的密鑰管理服務KMS**中。運行時OpenClaw進程用私鑰解密。這樣即使加密后的配置文件和公鑰都泄露了攻擊者沒有私鑰也無法解密。對于OpenClaw配置加密這個場景我強烈推薦非對稱加密方案。理由很直接公鑰可以放心地放入代碼庫用于CI/CD流程的加密環節而私鑰永遠不離開生產環境。這完美契合了“密鑰分離”的原則。2.3 集成點讓OpenClaw在啟動時自動解密我們不能要求每次運行OpenClaw都手動輸入解密命令。理想的狀態是OpenClaw在啟動加載配置時能自動識別出需要解密的字段并調用解密邏輯。這通常需要通過一個配置預處理器或自定義的配置加載器來實現。例如我們可以寫一個Python腳本在OpenClaw主程序讀取config.yaml之后、正式使用配置之前攔截配置字典遍歷所有值查找符合特定模式如前綴為enc:或后綴為_encrypted的字段然后用本地存儲的私鑰對其進行解密將解密后的明文替換回配置字典中。這樣OpenClaw的業務代碼感知不到加密過程它拿到的始終是明文但磁盤上存儲的已是密文。3. 基于SOPS與Age的實戰加密方案理論說完了我們來點實在的。經過一番選型我最終采用了SOPSSecrets OPerationS這款工具搭配Age加密算法來管理OpenClaw的加密配置。這是一套在云原生領域備受推崇的方案輕量、易用、且與Git工作流集成良好。3.1 工具選型為什么是SOPSAgeSOPS它不是一個簡單的加密庫而是一個針對YAML、JSON、ENV等配置文件格式的“智能”加密工具。它的強大之處在于可以只加密配置文件中的值比如api_key對應的字符串而保持文件結構鍵名、注釋等明文不變。這樣文件依然可讀、可版本控制只是敏感內容被保護了。Age一個簡單、現代、高效的加密工具。它生成的是簡單的Ed25519密鑰對對應我們說的非對稱加密命令行操作極其簡便。相比傳統的GPGAge沒有復雜的信任網絡密鑰就是簡單的文本字符串管理起來直觀很多。這套組合拳的好處是開發人員用公鑰加密配置加密后的文件可以安全地提交到Git。運維人員在生產環境放置私鑰SOPS在運行時能自動用私鑰解密。整個流程清晰工具鏈成熟。3.2 具體操作步驟假設我們有一個原始的OpenClaw配置文件config.yaml其中包含GLM-4.7-Flash的明文API密鑰。步驟一生成Age密鑰對在生產服務器或你的本地安全環境中生成Age密鑰對age-keygen -o age-key.txt這個命令會生成一個文件age-key.txt內容類似# created: 2024-01-01T00:00:00Z # public key: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p AGE-SECRET-KEY-1U9CPVJ0H8XMK0VQ5FYGZJGN0T2SJW3VK5J6XQ0ZJQZJQZJQZJQZJQ其中以age1開頭的行是公鑰以AGE-SECRET-KEY-開頭的是私鑰。將公鑰age1ql3z7...安全地分發給所有需要加密配置的開發人員。將私鑰AGE-SECRET-KEY-...絕密地保存在生產服務器上例如/etc/openclaw/age-key.txt并設置嚴格的文件權限如chmod 600。步驟二安裝SOPS在開發機和生產服務器上安裝SOPS。以macOS和Linux為例# macOS brew install sops # Linux (通過go安裝) go install go.mozilla.org/sops/v3/cmd/sopslatest步驟三創建.sops.yaml規則文件在OpenClaw項目根目錄創建.sops.yaml文件告訴SOPS如何加密我們的配置文件creation_rules: - path_regex: .*\.yaml$ # 匹配所有yaml文件 age: - age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p # 替換成你的公鑰這個文件可以提交到Git它只包含公鑰信息是安全的。步驟四加密配置文件現在將原始的config.yaml中的敏感值替換為占位符或者直接復制一份為config.enc.yaml用于加密。更常見的做法是直接讓SOPS編輯并加密原文件。但為了清晰我們先加密sops --encrypt --in-place config.yaml執行后config.yaml文件本身會被加密。你會發現像api_key對應的值變成了一串加密的密文數據塊而其他的鍵和結構保持不變。這個加密后的文件就可以安全地提交到Git倉庫了。步驟五開發時編輯加密文件如果你后續需要修改加密文件中的某個非敏感配置或者增加新的敏感項可以直接用SOPS編輯它會自動處理解密和再加密sops config.yaml這會用你默認的編輯器如vim, code打開文件你看到的是解密后的明文編輯保存后SOPS會自動將其重新加密。步驟六生產環境配置與OpenClaw集成這是最關鍵的一步。在生產服務器上我們有了加密的config.yaml和保密的私鑰文件age-key.txt。方案A使用SOPS作為預處理器推薦我們不在OpenClaw的代碼里直接集成解密邏輯而是通過一個啟動包裝腳本。創建一個start_openclaw.sh腳本#!/bin/bash # 設置Age私鑰的環境變量 export SOPS_AGE_KEY_FILE/etc/openclaw/age-key.txt # 使用sops解密配置文件輸出到標準輸出然后作為環境變量或臨時文件傳遞給OpenClaw # 假設OpenClaw支持從環境變量讀取配置或者我們可以生成一個臨時解密文件 DECRYPTED_CONFIG$(sops --decrypt /path/to/openclaw/config.yaml) # 將解密后的配置寫入一個臨時文件確保該文件僅對當前用戶可讀 TEMP_CONFIG$(mktemp) echo “$DECRYPTED_CONFIG” “$TEMP_CONFIG“ chmod 600 “$TEMP_CONFIG“ # 啟動OpenClaw指定使用臨時配置文件 python openclaw_app.py --config “$TEMP_CONFIG“ # 啟動后可刪除臨時文件可選進程持有文件描述符時可能無法立即刪除 rm -f “$TEMP_CONFIG“然后你的系統服務如systemd就啟動這個腳本而不是直接啟動Python程序。方案B在OpenClaw應用層集成解密如果OpenClaw是Python項目你可以在加載配置的代碼部分比如在config.py或主程序開頭集成SOPS解密import subprocess import yaml import os import tempfile def load_encrypted_config(config_path): 加載并解密SOPS加密的配置文件 # 檢查文件是否被SOPS加密過 try: result subprocess.run( [“sops“, “--decrypt“, config_path], capture_outputTrue, textTrue, checkTrue, env{**os.environ, “SOPS_AGE_KEY_FILE“: “/etc/openclaw/age-key.txt“} ) config_data yaml.safe_load(result.stdout) except subprocess.CalledProcessError as e: # 如果解密失敗可能文件未加密則嘗試直接加載 print(f“Decryption failed, trying plain load: {e}“) with open(config_path, ‘r’) as f: config_data yaml.safe_load(f) return config_data # 在主程序中 config load_encrypted_config(“config.yaml“) # 接下來config就是一個包含明文數據的字典可以正常使用了注意無論哪種方案都必須確保生產服務器上的私鑰文件 (age-key.txt) 權限盡可能嚴格如chmod 600并且僅限于運行OpenClaw服務的用戶有權讀取。絕對不要將私鑰提交到任何版本的代碼庫或構建鏡像中除非是專門的安全密鑰管理鏡像且有其特定流程。4. 方案進階與密鑰管理實踐基礎的SOPSAge方案已經能解決大部分問題但在團隊協作和更復雜的生產環境中我們還需要考慮更多。4.1 多環境與多密鑰管理一個項目通常有開發、測試、生產等多個環境。每個環境應該使用不同的Age密鑰對。這樣可以實現環境隔離開發配置泄露不會影響生產。在.sops.yaml中你可以定義更復雜的規則根據文件路徑匹配不同的公鑰。creation_rules: - path_regex: config/production/.*\.yaml$ age: age1productionpublickey... - path_regex: config/staging/.*\.yaml$ age: age1stagingpublickey... - path_regex: config/development/.*\.yaml$ age: age1developmentpublickey...在生產服務器上只部署對應環境的私鑰。4.2 與CI/CD流水線集成在自動化部署流程中如何安全地使用私鑰硬編碼在流水線腳本里同樣是危險的。推薦的做法是使用CI/CD系統提供的**機密變量Secrets**功能。GitHub Actions 將Age私鑰的內容存入倉庫的Settings - Secrets and variables - Actions中命名為AGE_SECRET_KEY。然后在 workflow 文件中jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Decrypt config for deployment run: | echo “${{ secrets.AGE_SECRET_KEY }}“ /tmp/age-key.txt sops --decrypt --age /tmp/age-key.txt config.enc.yaml config.yaml # 接下來使用解密后的config.yaml進行部署GitLab CI、Jenkins等也有類似的機密存儲功能。核心原則是私鑰只以環境變量的形式存在于流水線運行時內存中不落地到日志或普通文件。4.3 密鑰輪換與應急預案沒有任何密鑰是永恒的定期輪換密鑰是安全最佳實踐。生成新密鑰對 按照上述步驟生成新的Age密鑰對。更新加密配置 用新的公鑰重新加密所有配置文件。使用SOPS可以很方便地編輯加密文件在編輯保存時會自動使用.sops.yaml中當前生效的公鑰可以配置多個接收方重新加密。部署新私鑰 將新私鑰安全地部署到生產服務器替換或與舊私鑰并存如果SOPS配置了多個接收方則可以用多個私鑰解密。驗證與切換 驗證新私鑰可以成功解密配置文件并確保OpenClaw服務正常運行。廢棄舊密鑰 確認一切正常后從.sops.yaml中移除舊公鑰并安全地銷毀舊私鑰。應急預案務必保留一份加密配置的明文備份通過安全的離線方式存儲如密碼管理器以防密鑰丟失導致所有配置無法解密、服務完全癱瘓。同時確保部署和回滾流程不依賴于單一的密鑰解密步驟。5. 常見問題與故障排查實錄在實際操作中你肯定會遇到一些坑。這里記錄了幾個我踩過以及社區常見的問題。5.1 SOPS解密失敗權限問題與密鑰格式問題現象 執行sops --decrypt config.yaml時報錯提示Error: failed to get the data key或age: no identity matched any of the recipients。排查思路檢查私鑰文件路徑和權限 確保SOPS_AGE_KEY_FILE環境變量指向正確的路徑并且運行SOPS的用戶對該文件有讀取權限。使用ls -l /etc/openclaw/age-key.txt檢查權限是否為600。檢查私鑰內容 確保私鑰文件內容完整以AGE-SECRET-KEY-開頭且沒有多余的空格或換行。可以用cat -A /etc/openclaw/age-key.txt檢查是否有不可見字符。確認加密所用的公鑰 使用sops config.yaml查看加密文件的元數據它會列出加密時使用的所有公鑰。確保你當前持有的私鑰與其中至少一個公鑰對應。環境變量未生效 在腳本或服務中確保環境變量在調用SOPS命令之前已經正確設置。有時候在systemd service文件中設置環境變量需要特別注意語法。5.2 OpenClaw啟動時找不到解密后的配置問題現象 解密腳本執行成功生成了臨時配置文件但OpenClaw啟動報錯提示找不到某個配置項或配置文件格式錯誤。排查思路檢查臨時文件內容 在啟動腳本中在啟動OpenClaw之前添加一行cat “$TEMP_CONFIG“或將內容輸出到日志確認解密后的YAML格式是否正確、完整。檢查文件路徑傳遞 確保傳遞給OpenClaw的--config參數是臨時文件的絕對路徑。相對路徑可能因工作目錄不同而導致找不到文件。檢查OpenClaw配置加載邏輯 確認你的OpenClaw應用確實是通過你傳遞的參數來加載配置的。有些框架可能有默認的配置文件路徑和加載順序。進程權限 確保運行OpenClaw的用戶對臨時文件有讀取權限。使用mktemp創建的文件默認所有者是當前用戶通常沒問題。5.3 在Docker容器中運行時的密鑰管理問題描述 使用Docker部署OpenClaw時如何安全地將私鑰注入容器解決方案絕對不要將私鑰直接打包進Docker鏡像。有以下安全方法Docker SecretsSwarm模式 如果你使用Docker Swarm可以使用docker secret管理私鑰并在服務中掛載為內存文件。Kubernetes Secrets 在K8s中將Age私鑰創建為Secret對象然后通過Volume掛載或環境變量注入到Pod中。動態掛載 在docker run或docker-compose中通過-v卷掛載將宿主機上的私鑰文件映射到容器內特定路徑。務必控制宿主機上源文件的權限。# docker-compose.yml 示例片段 services: openclaw: image: your-openclaw-image volumes: - “/etc/openclaw/age-key.txt:/run/secrets/age-key.txt:ro“ environment: - SOPS_AGE_KEY_FILE/run/secrets/age-key.txt環境變量注入 在啟動容器時通過-e將私鑰內容作為環境變量傳入。注意命令行歷史可能泄露更安全的方式是通過文件或編排工具設置。docker run -e SOPS_AGE_KEY“$(cat /etc/openclaw/age-key.txt)“ your-openclaw-image5.4 配置項部分加密與混合加密策略有時我們可能只想加密配置文件中的幾個字段而不是整個文件。SOPS完美支持這一點它默認就是加密YAML/JSON中的字符串值。但如果你有一些非字符串的敏感信息或者想加密整個區塊可以在編輯加密文件時直接修改那些值SOPS會處理加密。對于混合策略比如有些配置來自環境變量有些來自加密文件可以在OpenClaw的配置加載邏輯中做優先級合并先加載加密的base配置然后用環境變量覆蓋特定的值。這樣即使某些關鍵憑證通過更動態、更安全的方式如云平臺的IAM角色提供也能兼容。最后再分享一個小心得在團隊中推行配置加密文檔和工具鏈的完善至關重要。你需要編寫清晰的README說明如何安裝SOPS、如何獲取公鑰、如何加密新配置。可以考慮將加密/解密腳本封裝成Makefile任務或簡單的Python工具降低團隊成員的使用門檻。畢竟安全措施如果太復雜導致大家不愿意用反而會滋生更大的風險——比如有人圖省事又把明文密鑰寫進了配置文件。