教程 08

教程 08 — 配置系統深度解析：API Key 的正確存法

目標：理解 OpenClaw 的三層配置體系，掌握 Secret Provider 的三種模式，讓你的金鑰既安全又靈活。

你會學到什麼

  • OpenClaw 配置檔案的結構和讀取順序
  • API Key 的三種寫法：字串 / 環境變數引用 / 外部命令
  • Secret Provider 系統的安全設計
  • 如何對接 1Password、Vault 等金鑰管理工具

一、配置檔案在哪裡

OpenClaw 的配置存放在 ~/.openclaw/openclaw.json（或 .yaml），網關啟動時自動讀取。

# 查看當前配置
openclaw config show
 
# 通過命令列設定某個欄位
openclaw config set gateway.mode local

整體結構如下：

{
  "gateway": { ... },        // 網關運行模式
  "agents": { ... },         // AI 代理預設行為
  "models": { ... },         // 模型提供商列表
  "channels": { ... },       // 訊息渠道（Telegram、Discord 等）
  "env": { ... },            // 運行時注入的環境變數
  "secrets": { ... },        // Secret Provider 配置（進階）
  "hooks": { ... }           // 生命週期鉤子
}

二、API Key 的三種寫法

方式 A：直接寫字串（快速體驗用）

最簡單，但不推薦在生產或多人共用場景使用，因為金鑰會明文儲存在配置檔案裡。

{
  "models": {
    "providers": {
      "openai": {
        "apiKey": "sk-proj-xxxxxxxxxxxxxxxx"
      }
    }
  }
}

方式 B：環境變數引用（日常推薦）

用 ${VAR_NAME} 佔位符引用系統環境變數，配置檔案裡不存真實金鑰。

第一步：在 shell 裡 export，或寫入 ~/.profile：

export OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxx"
export MINIMAX_API_KEY="eyJhbGci..."

第二步：配置檔案裡用佔位符引用：

{
  "models": {
    "providers": {
      "openai": {
        "apiKey": "${OPENAI_API_KEY}"
      },
      "minimax": {
        "apiKey": "${MINIMAX_API_KEY}"
      }
    }
  }
}

也可以用結構化寫法（更明確）：

{
  "apiKey": { "source": "env", "provider": "default", "id": "OPENAI_API_KEY" }
}

工作原理：網關啟動時，OpenClaw 匹配 ${VAR_NAME} 模式，從 process.env 讀取對應值，僅在記憶體中解析，不寫入磁碟。

方式 C：Secret Provider（團隊 / 伺服器部署）

這是最安全、也是最靈活的方式，適合：

  • 伺服器上不想設定環境變數
  • 團隊共用網關，金鑰集中管理
  • 接入 1Password CLI、HashiCorp Vault 等工具

Secret Provider 有三種 source：

source: "file" — 從檔案讀取

適合把金鑰存在權限嚴格的檔案裡（OpenClaw 會驗證檔案權限，不允許 group-writable）：

{
  "secrets": {
    "providers": {
      "my-keys": {
        "source": "file",
        "path": "~/.openclaw/secrets.json",
        "mode": "json"
      }
    }
  },
  "models": {
    "providers": {
      "openai": {
        "apiKey": { "source": "file", "provider": "my-keys", "id": "/openai/apiKey" }
      }
    }
  }
}

對應的 ~/.openclaw/secrets.json：

{
  "openai": { "apiKey": "sk-proj-xxxxxxxx" },
  "minimax": { "apiKey": "eyJhbGci..." }
}

安全要求：檔案必須是當前使用者所有，且權限不超過 600（chmod 600 ~/.openclaw/secrets.json）。

source: "exec" — 調用外部程式

適合對接 1Password CLI、Vault、系統鑰匙圈：

{
  "secrets": {
    "providers": {
      "op-vault": {
        "source": "exec",
        "command": "/usr/local/bin/op-resolver",
        "timeoutMs": 5000
      }
    }
  },
  "models": {
    "providers": {
      "openai": {
        "apiKey": { "source": "exec", "provider": "op-vault", "id": "openai/api-key" }
      }
    }
  }
}

外部程式通過 stdin 接收請求，通過 stdout 返回結果，協議如下：

# stdin 收到（JSON）：
{ "protocolVersion": 1, "provider": "op-vault", "ids": ["openai/api-key"] }

# stdout 返回（JSON）：
{ "protocolVersion": 1, "values": { "openai/api-key": "sk-proj-xxx" } }

三、1Password 接入示例

如果你用 1Password 存 API Key，可以寫一個簡單的 resolver 腳本：

#!/usr/bin/env bash
# ~/.openclaw/op-resolver.sh
# 權限設定：chmod 700 ~/.openclaw/op-resolver.sh
 
set -euo pipefail
INPUT=$(cat)
ID=$(echo "$INPUT" | jq -r '.ids[0]')
 
# 從 1Password 讀取
VALUE=$(op read "op://Private/$ID" 2>/dev/null)
 
echo "{\"protocolVersion\":1,\"values\":{\"$ID\":\"$VALUE\"}}"

然後配置：

{
  "secrets": {
    "providers": {
      "1password": {
        "source": "exec",
        "command": "/Users/你的使用者名/.openclaw/op-resolver.sh",
        "timeoutMs": 8000
      }
    }
  }
}

注意：command 必須是絕對路徑，且檔案不能被其他使用者寫入。

四、配置中的 env 區塊

除了 Secret Provider，env 區塊提供了另一種簡便方式——直接在配置檔案裡宣告運行時環境變數：

{
  "env": {
    "vars": {
      "HTTP_PROXY": "http://127.0.0.1:7890",
      "OPENAI_BASE_URL": "https://api.openai.com"
    }
  }
}

規則：

  • 只有配置檔案中的 env.vars 值才會注入，不會覆蓋系統已存在的同名變數
  • PATH、LD_PRELOAD 等危險變數名被自動遮蔽，無法通過此方式注入

五、敏感欄位自動脫敏

OpenClaw 用 Zod sensitive registry 標記所有金鑰欄位。當配置資訊暴露給 Dashboard 或日誌時，這些欄位會自動替換為 [REDACTED]：

# 日誌或 API 回應裡看到的是：
{ "apiKey": "[REDACTED]" }

# 記憶體裡真實值不會出現在日誌

六、完整配置示例（多模型 + 安全金鑰）

{
  "gateway": { "mode": "local" },
 
  "secrets": {
    "providers": {
      "env-keys": { "source": "env" }
    },
    "defaults": { "env": "env-keys" }
  },
 
  "agents": {
    "defaults": {
      "model": { "primary": "openai/gpt-4o" }
    }
  },
 
  "models": {
    "mode": "merge",
    "providers": {
      "openai": {
        "apiKey": "${OPENAI_API_KEY}",
        "models": [
          { "id": "gpt-4o", "name": "GPT-4o" }
        ]
      },
      "minimax": {
        "baseUrl": "https://api.minimax.io/anthropic",
        "apiKey": "${MINIMAX_API_KEY}",
        "api": "anthropic-messages",
        "models": [
          {
            "id": "MiniMax-M2.1",
            "name": "MiniMax M2.1",
            "contextWindow": 200000,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
 
  "channels": {
    "telegram": {
      "token": "${TELEGRAM_BOT_TOKEN}"
    }
  }
}

對應的環境變數（寫入 ~/.profile 或 .env）：

export OPENAI_API_KEY="sk-proj-..."
export MINIMAX_API_KEY="eyJhbGci..."
export TELEGRAM_BOT_TOKEN="8543054163:AAH..."

七、常見問題

配置改了為什麼沒生效？

網關需要重啟才會重新讀取配置，技能（SKILL.md）除外：

openclaw gateway restart

怎麼驗證金鑰被正確讀取了？

openclaw models list
# 看到對應 provider 的模型就說明 apiKey 解析成功

如果模型列表為空，執行 openclaw config show 查看配置是否被正確解析，檢查 ${VAR_NAME} 佔位符對應的環境變數是否已 export。

檔案 source 報權限錯誤怎麼辦？

chmod 600 ~/.openclaw/secrets.json
# 確保檔案屬於當前使用者
ls -la ~/.openclaw/secrets.json

OpenClaw 要求金鑰檔案權限不超過 600，且檔案必須歸當前使用者所有（不能是 root 所有但運行使用者可讀）。

exec source 的腳本超時了怎麼處理？

增大 timeoutMs（最大 120000ms）。最常見的原因是外部命令需要登入態，例如 1Password CLI 需要先 op signin。建議在腳本中加入自動重新登入的邏輯，或將 session token 快取到檔案中。

.env 檔案和 openclaw.json 裡的 env 區塊有什麼區別？

.env 檔案是系統級環境變數，對所有進程生效；openclaw.json 的 env.vars 區塊只在 OpenClaw 網關進程內生效，不影響其他程式。兩者都支援用 ${VAR_NAME} 在 apiKey 等欄位中引用，推薦用 .env 存敏感資料，env.vars 存 OpenClaw 專用的非敏感配置（如代理地址）。

可以同時存在多個配置檔案嗎？

OpenClaw 支援配置合併（"mode": "merge"），但主配置檔案路徑固定為 ~/.openclaw/openclaw.json。你可以在 openclaw.json 中通過 import 欄位引入其他配置檔案片段，實現配置的模組化管理。

下一步

  • 教程 05 — 配置多個模型 Provider，自動切換
  • 教程 03 — 給 AI 加自定義技能

关注我们，获取最新 AI 动态

在 X 上关注 @lanmiaoai，第一时间获取教程更新、AI 工具推荐。

立即关注
← 上一篇教程 07 — 隨手拍識圖助手下一篇 →教程 09 — OpenClaw self-improving-agent 教程：讓 AI 自動記錄錯誤、持續自我進化（2026）