OpenClaw OAuth 與 API 認證完整設定指南：多模型身份驗證架構實踐

核心重點

OpenClaw 支援四種主要認證方式：Anthropic Claude OAuth、OpenAI API Key、本地模型 Endpoint 以及企業 SSO，每種方式的安全特性與設定流程各有不同。
Anthropic Claude OAuth 採用標準 OAuth 2.0 授權碼流程，提供比靜態 API Key 更高的安全性，並支援 Token 自動刷新與撤銷機制。
CrowdStrike 與 Cisco 安全研究人員在 2026 年初分別披露 OpenClaw 的認證架構存在嚴重弱點，包含第三方 Skills 洩漏 API 金鑰的風險。
企業部署建議採用環境變數管理所有憑證，絕不將 API Key 或 Token 寫入版本控制；並定期執行金鑰輪換（建議每 90 天一次）。
多模型切換場景下，需為每個模型供應商建立獨立的認證上下文，避免跨供應商憑證污染。

在 AI 代理（AI Agent）普及的浪潮中，OpenClaw 作為整合多模型能力的超級代理平台，其認證架構的複雜度遠超傳統 SaaS 應用。一個 OpenClaw 實例可能同時對接 Anthropic Claude、OpenAI GPT、DeepSeek 以及本地部署的 Ollama 模型——每個供應商都有自己的認證協議、Token 生命週期管理與安全要求。

更棘手的是，2026 年初 The Register 的調查報告揭露，OpenClaw Skills Marketplace 中的第三方技能包存在 API 金鑰洩漏漏洞^[7]，而 CrowdStrike 的安全研究也指出平台的認證邊界設計存在可被利用的弱點^[6]。在這樣的背景下，正確理解並設定 OpenClaw 的認證架構，已從「技術細節」升格為「安全關鍵任務」。

本指南將完整拆解 OpenClaw 的多模型認證體系，從 Anthropic Claude OAuth 的逐步設定、OpenAI API Key 的安全管理，到企業 SSO 整合與安全審計 Checklist，為企業技術團隊提供一份可直接付諸實踐的操作手冊。

一、AI 代理時代的身份驗證挑戰

1.1 自主代理帶來的憑證風險新維度

傳統應用程式的身份驗證設計，預設使用者是「人類」——有認知能力判斷請求的合法性，有意識在異常時中止操作。然而，AI 代理改變了這個前提。當 OpenClaw 以自主模式運行時，它可能在無人監督的情況下發起數百次 API 呼叫：查詢資料庫、發送郵件、執行程式碼、呼叫外部服務——每一次操作都需要對應的認證憑證。

這種「機器代表人類行動」的模式，帶來了三個傳統認證設計未曾充分考量的風險維度：

憑證擴散（Credential Sprawl）：OpenClaw 可能同時持有 Anthropic API Key、OpenAI API Key、Google Workspace Service Account、GitHub Personal Access Token、Slack Bot Token 等十餘種憑證。任何一個洩漏，影響範圍可能超越單一服務。

提示注入攻擊（Prompt Injection）：攻擊者可能透過惡意設計的外部資料（網頁內容、郵件正文、文件），誘騙代理執行未授權的認證操作，例如將現有 Token 傳送至攻擊者控制的端點。Cisco 的研究報告詳細記錄了此類攻擊在 OpenClaw 環境中的可行性^[10]。

最小權限原則的崩潰：為了讓代理能夠完成多樣化任務，開發者往往傾向授予過度寬泛的權限。OWASP API Security Top 10 中，「物件層級授權失效」與「功能層級授權失效」長期位居前三^[5]，在 AI 代理場景中這些問題被顯著放大。

1.2 OpenClaw 的認證責任邊界

理解 OpenClaw 的認證架構，必須先釐清其「認證責任邊界」：哪些認證由 OpenClaw 平台管理，哪些由使用者自行負責，哪些由第三方 Skills 處理。

OpenClaw 平台負責：使用者帳號認證（登入 OpenClaw 本身）、模型供應商的 API 憑證儲存與傳遞、內建工具（瀏覽器、終端機）的執行沙箱隔離。

使用者自行負責：提供正確的 API Key 或完成 OAuth 授權、定期輪換憑證、監控異常用量、評估第三方 Skills 的可信度。

第三方 Skills 的灰色地帶：這正是 2026 年初安全事件的核心問題。部分 Skills 要求存取宿主環境的憑證，而 OpenClaw 的 Skills 沙箱隔離機制在當時並不完善，導致惡意或設計不良的 Skills 可以讀取、甚至外傳其他供應商的 API Key^[7]。

二、OpenClaw 認證架構概覽

2.1 四層架構中的認證層

OpenClaw 的技術架構分為四層：對話介面層、代理協調層、工具執行層與模型推理層。認證機制貫穿所有層次，但主要集中在兩個節點：使用者進入系統時（對話介面層的帳號認證）以及代理呼叫外部服務時（工具執行層與模型推理層的 API 認證）。

在模型推理層，OpenClaw 的認證管理器（Auth Manager）負責：

儲存各模型供應商的憑證（加密儲存於本地設定檔或環境變數）
在每次模型呼叫前注入對應的認證標頭（Authorization Header）
監控 Token 過期時間，於必要時自動刷新（限 OAuth 流程）
在日誌中遮蔽憑證內容，防止意外洩漏

2.2 支援的認證方式矩陣

下表整理 OpenClaw 對各主要模型供應商的認證支援情況^[1]：

供應商	認證方式	Token 刷新	撤銷支援	安全等級
Anthropic Claude	OAuth 2.0 / API Key	是（OAuth）	是	高
OpenAI GPT	API Key	否	手動	中
DeepSeek	API Key	否	手動	中
Ollama（本地）	無認證 / Bearer Token	否	否	低（需網路隔離）
Azure OpenAI	API Key / Azure AD	是（Azure AD）	是	高
Google Gemini	OAuth 2.0 / API Key	是（OAuth）	是	高

2.3 設定檔位置與結構

OpenClaw 的認證設定儲存於使用者主目錄下的隱藏設定目錄。不同作業系統的路徑如下：

# macOS / Linux
~/.openclaw/config.yaml
~/.openclaw/credentials.enc  # 加密憑證檔案

# Windows
%APPDATA%\OpenClaw\config.yaml
%APPDATA%\OpenClaw\credentials.enc

config.yaml 的基本結構如下（憑證值應留空，以環境變數或 credentials.enc 填充）：

models:
  default: claude-3-5-sonnet
  providers:
    anthropic:
      auth_method: oauth  # 或 api_key
      model: claude-3-5-sonnet-20241022
    openai:
      auth_method: api_key
      model: gpt-4o
    deepseek:
      auth_method: api_key
      base_url: https://api.deepseek.com/v1
      model: deepseek-chat
    ollama:
      auth_method: none
      base_url: http://localhost:11434
      model: llama3.2

security:
  credential_storage: keychain  # keychain | env | file
  log_redaction: true
  audit_log: true

三、Anthropic Claude OAuth 設定

3.1 OAuth 2.0 授權碼流程解析

Anthropic 為 OpenClaw 提供標準 OAuth 2.0 授權碼流程（Authorization Code Flow），這是比靜態 API Key 更安全的認證方式：Access Token 有時效限制、可被撤銷、不需要在設定檔中永久儲存敏感憑證^[4]。

完整的 OAuth 授權流程如下：

使用者在 OpenClaw 設定介面選擇「連接 Anthropic 帳號」
OpenClaw 生成隨機 state 參數（防 CSRF）與 PKCE code_verifier
瀏覽器跳轉至 Anthropic 授權端點：https://console.anthropic.com/oauth/authorize
使用者在 Anthropic Console 完成登入並確認授權範圍（Scope）
Anthropic 將授權碼（Authorization Code）回傳至 OpenClaw 的回調 URL
OpenClaw 後端以授權碼換取 Access Token 與 Refresh Token
Token 對以加密形式儲存，後續 API 呼叫自動附加 Authorization Header

此流程中，使用者的 Anthropic 密碼永遠不會接觸 OpenClaw，大幅降低憑證洩漏風險^[2]。

3.2 透過 GUI 完成 Claude OAuth 授權

對大多數使用者而言，透過 OpenClaw 圖形介面設定 Claude OAuth 是最直觀的方式：

步驟一：開啟設定面板

點擊 OpenClaw 主介面右上角的齒輪圖示，進入「設定」→「模型供應商」→「Anthropic」。

步驟二：選擇認證方式

在認證方式下拉選單中選擇「OAuth（推薦）」而非「API Key」。

步驟三：啟動授權流程

點擊「連接 Anthropic 帳號」按鈕，系統將自動開啟瀏覽器並跳轉至 Anthropic 授權頁面。

步驟四：確認授權範圍

在 Anthropic Console 中，確認以下授權範圍已勾選：

completions:write：允許發送訊息給 Claude
models:read：允許讀取可用模型列表
usage:read（可選）：允許查詢用量統計

步驟五：完成授權並驗證

點擊「授權」後，瀏覽器將回跳至 OpenClaw 並顯示「Anthropic 帳號已成功連接」。此時可發送測試訊息確認認證正常。

3.3 使用 `claude setup-token` 命令列設定

對於偏好命令列操作的進階使用者或自動化部署場景，OpenClaw 提供 setup-token 子命令，支援非互動式 Token 注入^[9]：

# 基本語法
openclaw claude setup-token [OPTIONS]

# 互動式設定（會提示輸入 Token）
openclaw claude setup-token

# 從環境變數讀取（適合 CI/CD）
ANTHROPIC_TOKEN="sk-ant-..." openclaw claude setup-token --from-env

# 從檔案讀取（適合 secrets 管理工具）
openclaw claude setup-token --token-file /run/secrets/anthropic_token

# 指定 Token 有效期（秒）
openclaw claude setup-token --expires-in 86400

# 驗證已設定的 Token
openclaw claude verify-auth

注意：setup-token 接受的是 Anthropic 的 API Key（格式 sk-ant-api03-...），而非 OAuth Access Token。若要使用 OAuth，必須透過 GUI 流程或實作完整的 OAuth 回調伺服器。

3.4 Token 刷新與生命週期管理

透過 OAuth 取得的 Anthropic Access Token 預設有效期為 1 小時。OpenClaw 的 Token 管理器會在 Token 過期前 5 分鐘自動使用 Refresh Token 進行刷新，整個過程對使用者透明。

手動觸發刷新：

# 強制刷新所有 OAuth Token
openclaw auth refresh --provider anthropic

# 查看 Token 狀態
openclaw auth status --provider anthropic

# 輸出示例
# Provider: anthropic
# Auth Method: oauth
# Token Status: valid
# Expires At: 2026-02-22T14:30:00Z (45 minutes remaining)
# Refresh Token: present

若 Refresh Token 也過期（通常有效期為 30 天），需重新執行 OAuth 授權流程。建議在 Anthropic Console 設定 Refresh Token 的到期通知警報，以避免代理服務中斷。

四、OpenAI API Key 設定

4.1 在 OpenAI Platform 生成 API Key

OpenAI 目前僅支援靜態 API Key 認證（Project API Key 或 User API Key）^[3]。建議遵循以下原則生成金鑰：

使用 Project API Key（強烈推薦）：Project API Key 的權限範圍限定於特定 Project，即使洩漏也不會影響其他 Project 或帳號層級的設定。操作步驟：

登入 platform.openai.com
在左側選單點擊「API keys」→「Project API keys」
選擇或建立一個 Project（建議為 OpenClaw 建立專屬 Project）
點擊「Create new secret key」
設定金鑰名稱（例如：openclaw-production-2026Q1）並指定權限範圍
複製金鑰（此後無法再次查看完整金鑰）

設定用量限制：在 Project 設定中，建議設定每月最高用量上限，避免因代理失控或憑證濫用導致意外帳單。

4.2 在 OpenClaw 中設定 OpenAI API Key

OpenAI API Key 的設定可透過以下三種方式完成，安全性由高至低排列：

方式一：環境變數（最推薦）

# 在 shell profile 中設定（~/.zshrc 或 ~/.bashrc）
export OPENAI_API_KEY="sk-proj-..."

# OpenClaw 啟動時自動讀取此環境變數
# 無需在設定檔中寫入任何憑證

方式二：系統 Keychain（macOS / Windows）

# macOS：透過命令列存入 Keychain
openclaw auth set --provider openai --key "sk-proj-..." --storage keychain

# 或透過 GUI：設定 → 模型供應商 → OpenAI → 儲存至 Keychain

方式三：加密設定檔（次要選項）

# OpenClaw 使用主密碼加密儲存
openclaw auth set --provider openai --key "sk-proj-..." --storage encrypted-file

# 系統將提示設定或輸入主密碼（Master Password）

絕對禁止的做法：直接將 API Key 寫入 config.yaml 明文欄位，或將包含金鑰的設定檔提交至 Git 版本控制。

4.3 API Key 驗證與模型可用性確認

# 驗證 OpenAI 認證設定
openclaw auth verify --provider openai

# 列出可用模型（同時測試認證是否正常）
openclaw models list --provider openai

# 預期輸出示例
# OpenAI Models:
# - gpt-4o (available)
# - gpt-4o-mini (available)
# - gpt-4-turbo (available)
# - o1 (available)
# - o1-mini (available)

# 傳送測試訊息
openclaw run --model gpt-4o --prompt "回覆'認證成功'即可" --provider openai

4.4 API Key 輪換流程

OWASP API Security 建議定期輪換靜態 API Key^[5]。建議的 OpenAI API Key 輪換流程如下：

在 OpenAI Platform 建立新的 Project API Key（命名包含日期，例如 openclaw-prod-2026Q2）
在 OpenClaw 中更新 API Key 設定（使用環境變數的話，更新 shell profile 並重啟）
執行 openclaw auth verify --provider openai 確認新金鑰正常
在 OpenAI Platform 撤銷舊金鑰
在輪換日誌中記錄此次操作（日期、操作人、原因）

建議每 90 天執行一次輪換，或在以下情況立即輪換：人員離職、懷疑洩漏、安全事件響應。

五、開源模型認證（DeepSeek、Ollama）

5.1 DeepSeek API Key 設定

DeepSeek 的認證方式與 OpenAI 類似，使用靜態 API Key，透過標準 Bearer Token 格式傳遞：

# 環境變數設定
export DEEPSEEK_API_KEY="sk-..."

# OpenClaw 設定（config.yaml）
models:
  providers:
    deepseek:
      auth_method: api_key
      base_url: https://api.deepseek.com/v1
      model: deepseek-chat
      # API Key 從環境變數 DEEPSEEK_API_KEY 自動讀取

DeepSeek 官方 API 端點支援 OpenAI 相容的 API 格式，因此 OpenClaw 可使用 OpenAI 相容模式連接 DeepSeek：

# 使用 OpenAI 相容模式連接 DeepSeek
openclaw auth set \
  --provider custom \
  --name deepseek \
  --base-url https://api.deepseek.com/v1 \
  --key "$DEEPSEEK_API_KEY" \
  --openai-compat true

特別注意：DeepSeek 的伺服器位於中國境內，若企業有資料主權合規要求，應在使用前評估資料傳輸路徑是否符合 GDPR、PDPA 或其他適用法規。

5.2 Ollama 本地模型認證設定

Ollama 預設以無認證模式在本地運行，僅監聽 localhost:11434。在標準本地部署場景下，OpenClaw 可直接連接無需任何認證憑證：

# 確認 Ollama 服務運行狀態
curl http://localhost:11434/api/tags

# OpenClaw 設定（無認證模式）
models:
  providers:
    ollama:
      auth_method: none
      base_url: http://localhost:11434
      model: llama3.2

然而，若 Ollama 部署於遠端伺服器（例如內部 GPU 叢集），則必須加入認證機制，否則任何可連接到該伺服器的人都能免費使用算力：

# 為 Ollama 啟用 Bearer Token 認證（在 Ollama 伺服器端）
export OLLAMA_API_KEY="your-secret-token"
ollama serve

# OpenClaw 設定（使用 Bearer Token）
models:
  providers:
    ollama:
      auth_method: bearer_token
      base_url: http://gpu-server.internal:11434
      model: llama3.2
      # Token 從環境變數 OLLAMA_API_KEY 自動讀取

若需更高安全性，建議在 Ollama 前加一層反向代理（如 Nginx 或 Caddy），在代理層實施 TLS 加密與更完善的存取控制。

5.3 自架模型 API 端點的通用設定

對於其他自架模型服務（如 vLLM、LM Studio、LocalAI），OpenClaw 提供通用的 OpenAI 相容端點設定：

# 通用 OpenAI 相容端點設定範例（vLLM）
openclaw provider add \
  --name vllm-internal \
  --type openai-compat \
  --base-url http://vllm.internal:8000/v1 \
  --api-key "$VLLM_API_KEY" \
  --default-model "meta-llama/Llama-3-70b-instruct"

# 測試連線
openclaw auth verify --provider vllm-internal

六、多模型切換的認證管理

6.1 認證上下文的隔離原則

在多模型場景下，最常見的安全錯誤是讓不同供應商的憑證共用同一個環境上下文，導致「憑證污染」——一個模型的錯誤配置可能影響另一個模型的認證行為。

OpenClaw 的最佳實踐是為每個供應商維護獨立的認證命名空間：

# 各供應商環境變數命名規範
export ANTHROPIC_API_KEY="sk-ant-..."     # Anthropic
export OPENAI_API_KEY="sk-proj-..."       # OpenAI
export DEEPSEEK_API_KEY="sk-..."          # DeepSeek
export OLLAMA_BASE_URL="http://..."       # Ollama（無需金鑰）
export AZURE_OPENAI_KEY="..."             # Azure OpenAI
export AZURE_OPENAI_ENDPOINT="https://..." # Azure OpenAI Endpoint

# OpenClaw 按供應商前綴自動匹配環境變數

6.2 模型路由策略與認證切換

OpenClaw 支援基於任務類型、成本、延遲等因素的模型路由策略。在設定路由規則時，需確保每條路由路徑都有對應的有效認證：

# config.yaml 路由設定示例
routing:
  rules:
    - name: "code-tasks"
      condition: "task_type == 'coding'"
      provider: anthropic
      model: claude-3-5-sonnet-20241022
      # 使用 anthropic 供應商的認證

    - name: "fast-responses"
      condition: "latency_budget < 2000"
      provider: openai
      model: gpt-4o-mini
      # 使用 openai 供應商的認證

    - name: "local-sensitive"
      condition: "data_classification == 'confidential'"
      provider: ollama
      model: llama3.2
      # 本地模型，無認證，資料不離境

    - name: "default"
      provider: anthropic
      model: claude-3-5-sonnet-20241022

6.3 認證健康檢查與自動容錯

在生產環境中，建議設定定期認證健康檢查，當某個供應商的認證失效時自動切換至備援模型：

# 設定認證健康檢查（config.yaml）
health_check:
  enabled: true
  interval: 300  # 每 300 秒檢查一次
  providers:
    - anthropic
    - openai
  on_failure:
    anthropic:
      fallback_provider: openai
      alert_webhook: "https://hooks.slack.com/services/..."
    openai:
      fallback_provider: ollama

# 手動觸發健康檢查
openclaw health check --all-providers

七、Token 安全管理最佳實踐

7.1 憑證儲存的安全分級

不同的憑證儲存方式有截然不同的安全特性，選擇時應根據部署環境與安全需求做出明智決策：

等級一：系統 Keychain（最高安全性）

macOS Keychain、Windows Credential Manager 或 Linux Secret Service API 提供作業系統層級的加密儲存，只有擁有對應權限的程序才能存取。憑證不會以明文形式出現在磁碟上，即使攻擊者取得檔案系統存取權也無法直接讀取。

等級二：環境變數（高安全性，適合 Server 部署）

環境變數存在於行程記憶體中，不寫入磁碟。然而需注意：子行程可繼承父行程的環境變數，部分日誌系統可能意外記錄環境變數內容。在容器化部署（Docker/Kubernetes）中，應使用 Secret 物件管理環境變數，而非寫入 Dockerfile 或 docker-compose.yaml。

# Kubernetes Secret 示例（正確做法）
kubectl create secret generic openclaw-credentials \
  --from-literal=ANTHROPIC_API_KEY="sk-ant-..." \
  --from-literal=OPENAI_API_KEY="sk-proj-..."

# 在 Pod 中透過 secretKeyRef 注入（不寫入映像層）
env:
  - name: ANTHROPIC_API_KEY
    valueFrom:
      secretKeyRef:
        name: openclaw-credentials
        key: ANTHROPIC_API_KEY

等級三：加密設定檔（中等安全性）

OpenClaw 支援使用主密碼加密的 credentials.enc 檔案。主密碼應具備足夠複雜度（至少 20 個字元，混合大小寫、數字、符號），並透過獨立渠道儲存（如密碼管理器）。

絕對禁止：明文設定檔或環境變數檔案提交至 Git

# .gitignore 必須包含以下規則
.env
.env.*
.env.local
config.yaml
credentials.enc
**/secrets/**
**/*_secret*
**/*_key*
*.pem
*.key

7.2 版本控制中的憑證防護

即使設定了 .gitignore，仍需採取額外防護措施，因為開發者可能在不知情的情況下提交含有憑證的檔案：

# 安裝 git-secrets（防止 API Key 意外提交）
brew install git-secrets  # macOS

# 為 OpenClaw 專案設定偵測規則
git secrets --install
git secrets --register-aws  # 同時偵測 AWS 金鑰格式
git secrets --add 'sk-ant-[A-Za-z0-9_-]{40,}'  # Anthropic Key 格式
git secrets --add 'sk-proj-[A-Za-z0-9_-]{40,}' # OpenAI Project Key 格式

# 掃描現有歷史提交（修復過往洩漏）
git secrets --scan-history

若發現 API Key 已被提交至 Git 歷史，必須立即執行以下操作（按優先順序）：

立即至對應供應商的控制台撤銷（Revoke）已洩漏的金鑰
生成新金鑰並更新所有使用該金鑰的服務
使用 git filter-branch 或 BFG Repo-Cleaner 從 Git 歷史移除敏感資料
強制推送清理後的歷史（需協調所有協作者重新 Clone）
調查是否有人在洩漏期間存取或濫用了該金鑰

7.3 金鑰輪換時程表

建立系統化的金鑰輪換計畫，是降低長期憑證洩漏風險的關鍵措施：

憑證類型	建議輪換週期	觸發立即輪換的條件
Anthropic API Key	每 90 天	人員異動、可疑用量、安全事件
OpenAI API Key	每 90 天	同上
DeepSeek API Key	每 60 天	同上
OAuth Refresh Token	每 180 天（或過期時）	帳號安全事件
Ollama Bearer Token	每 30 天	伺服器存取日誌異常
企業 SSO 服務帳號	每 365 天	人員離職、合規審計

7.4 用量監控與異常告警

有效的用量監控可以及早發現憑證被濫用的跡象：

# OpenClaw 內建用量監控設定（config.yaml）
monitoring:
  usage_alerts:
    enabled: true
    thresholds:
      anthropic:
        daily_tokens: 1000000      # 超過 100 萬 Token 告警
        daily_cost_usd: 50         # 超過 $50 USD 告警
      openai:
        daily_tokens: 500000
        daily_cost_usd: 30
    alert_channels:
      - type: email
        address: "[email protected]"
      - type: webhook
        url: "https://hooks.slack.com/..."

# 查看當前用量
openclaw usage report --period today --all-providers

八、企業 SSO 與 SAML 整合

8.1 企業認證架構設計原則

對於企業部署，OpenClaw 的認證架構需要在以下三個層次建立完整的身份管理體系：

使用者身份層：員工透過企業 SSO（Okta、Azure AD、Google Workspace 等）登入 OpenClaw，無需管理獨立帳號密碼。

模型供應商憑證層：企業統一管理各 AI 供應商的 API Key，員工無需也無法看到實際的 API Key。OpenClaw Gateway 模式在此架構下扮演憑證代理角色。

授權政策層：基於使用者角色（Role）決定哪些員工可以使用哪些 AI 模型、哪些功能、每月用量上限為多少。

8.2 SAML 2.0 整合設定

OpenClaw Enterprise 版本支援 SAML 2.0 標準，可與主流企業身份提供商整合。以 Okta 為例：

在 Okta 端設定：

在 Okta Admin Console 建立新的 SAML 2.0 應用程式
設定 Single Sign On URL：https://your-openclaw-instance/auth/saml/callback
設定 Audience URI（SP Entity ID）：https://your-openclaw-instance
設定 Attribute Statements（屬性映射）：
- email → user.email
- firstName → user.firstName
- lastName → user.lastName
- groups → user.groups（用於角色映射）
下載 IdP Metadata XML 檔案

在 OpenClaw 端設定：

# config.yaml SAML 設定
auth:
  method: saml
  saml:
    idp_metadata_url: "https://your-company.okta.com/app/.../sso/saml/metadata"
    # 或使用本地檔案
    idp_metadata_file: "/etc/openclaw/okta-metadata.xml"
    sp_entity_id: "https://your-openclaw-instance"
    callback_url: "https://your-openclaw-instance/auth/saml/callback"
    attribute_mapping:
      email: "email"
      name: "displayName"
      groups: "groups"

# 角色映射設定
rbac:
  group_mapping:
    "OpenClaw-Admins":
      role: admin
      model_access: ["all"]
      monthly_token_limit: unlimited
    "OpenClaw-Power-Users":
      role: power_user
      model_access: ["claude-3-5-sonnet", "gpt-4o"]
      monthly_token_limit: 5000000
    "OpenClaw-Basic":
      role: basic
      model_access: ["claude-3-haiku", "gpt-4o-mini"]
      monthly_token_limit: 1000000

8.3 Azure Active Directory 整合

對於 Microsoft 生態系的企業，OpenClaw 支援 Azure AD OAuth 2.0 整合：

# Azure AD 應用程式設定（在 Azure Portal）
# 1. 建立 App Registration
# 2. 設定 Redirect URI: https://your-openclaw-instance/auth/azure/callback
# 3. 設定 API Permissions: Microsoft Graph → User.Read
# 4. 建立 Client Secret 並記錄值

# config.yaml Azure AD 設定
auth:
  method: azure_ad
  azure:
    tenant_id: "your-tenant-id"
    client_id: "your-client-id"
    # Client Secret 從環境變數讀取
    # 環境變數：AZURE_CLIENT_SECRET
    redirect_uri: "https://your-openclaw-instance/auth/azure/callback"
    scopes:
      - "openid"
      - "profile"
      - "email"
      - "offline_access"

8.4 服務帳號與非互動式認證

對於自動化工作流程（排程任務、CI/CD 整合、API 自動化），需要使用服務帳號（Service Account）進行非互動式認證：

# 建立 OpenClaw 服務帳號
openclaw admin service-account create \
  --name "automation-bot" \
  --description "CI/CD 自動化任務帳號" \
  --role service_account \
  --model-access "claude-3-haiku,gpt-4o-mini" \
  --monthly-token-limit 2000000

# 生成服務帳號 Token
openclaw admin service-account token create \
  --account "automation-bot" \
  --expires-in 2592000  # 30 天

# 服務帳號 Token 在 API 呼叫中的使用方式
curl https://your-openclaw-instance/api/v1/chat \
  -H "Authorization: Bearer sa-tok-..." \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello", "model": "claude-3-haiku"}'

九、常見錯誤與排除指南

9.1 認證錯誤代碼速查表

以下整理 OpenClaw 中最常見的認證相關錯誤及其解決方案：

錯誤：AUTH_401: Invalid API Key

原因：API Key 格式錯誤、金鑰已撤銷或已過期。

排除步驟：

確認 API Key 完整複製（無多餘空格或換行）
至對應供應商控制台確認金鑰狀態
若使用環境變數，執行 echo $ANTHROPIC_API_KEY 確認值正確
重新生成新金鑰並更新設定

錯誤：AUTH_403: Permission Denied

原因：API Key 有效但權限不足（如 Project Key 缺少所需 Scope）。

排除步驟：

至供應商控制台確認 API Key 的權限範圍
對於 OpenAI Project Key，確認 Project 的模型存取權限
對於 Anthropic OAuth，重新授權並確認已勾選必要 Scope

錯誤：AUTH_429: Rate Limit Exceeded

原因：短時間內請求量超過供應商的速率限制。

排除步驟：

# 查看速率限制狀態
openclaw debug rate-limit --provider anthropic

# 調整重試策略（config.yaml）
retry:
  max_attempts: 3
  backoff_strategy: exponential
  initial_delay_ms: 1000
  max_delay_ms: 30000
  jitter: true

錯誤：OAUTH_TOKEN_EXPIRED

原因：OAuth Access Token 過期，且 Refresh Token 刷新失敗。

排除步驟：

# 嘗試手動刷新
openclaw auth refresh --provider anthropic

# 若刷新失敗，重新執行 OAuth 授權
openclaw auth login --provider anthropic

# 查看 Token 詳細狀態
openclaw auth status --provider anthropic --verbose

錯誤：CONFIG_CREDENTIAL_NOT_FOUND

原因：OpenClaw 找不到對應供應商的認證憑證。

排除步驟：

# 確認環境變數已設定
env | grep -E "(ANTHROPIC|OPENAI|DEEPSEEK)_API_KEY"

# 確認 Keychain 中有儲存憑證
openclaw auth list --storage keychain

# 重新設定憑證
openclaw auth set --provider openai --key "sk-proj-..."

9.2 OAuth 流程常見問題

問題：授權後瀏覽器跳轉失敗（Callback URL 無法存取）

在本地開發環境或防火牆限制的環境中，OAuth 回調 URL 可能無法正常運作。解決方案：

# 使用 Device Flow 代替 Authorization Code Flow（不需要回調 URL）
openclaw auth login --provider anthropic --flow device

# 系統將顯示設備碼和驗證 URL
# Device Code: XXXX-XXXX
# Verification URL: https://console.anthropic.com/device
# 請在瀏覽器中開啟驗證 URL 並輸入設備碼

問題：多用戶共享環境中的 OAuth Token 衝突

在多用戶共享的 Linux 伺服器上，不同用戶的 OAuth Token 可能發生衝突。解決方案：確保每個用戶有獨立的 OpenClaw 設定目錄，並設定適當的檔案權限：

# 確認設定目錄權限
ls -la ~/.openclaw/
# 應顯示 drwx------（700）只有擁有者可讀寫

# 若權限不正確，修復之
chmod 700 ~/.openclaw
chmod 600 ~/.openclaw/credentials.enc
chmod 600 ~/.openclaw/config.yaml

9.3 Skills 相關的認證問題

鑑於 2026 年初披露的 Skills API 金鑰洩漏事件^[7]，以下是使用第三方 Skills 時的認證安全注意事項：

# 查看已安裝 Skills 的權限請求
openclaw skills list --show-permissions

# 移除可疑 Skill
openclaw skills remove "suspicious-skill-name"

# 稽核 Skill 的憑證存取記錄
openclaw audit log --filter "resource_type=credential" --last 7d

# 設定 Skills 沙箱限制（禁止 Skills 存取模型供應商憑證）
security:
  skills_sandbox:
    deny_credential_access: true
    deny_env_var_read: true
    allow_network: false  # 完全禁止外部網路存取

十、安全審計 Checklist

10.1 初始部署安全審計

在首次部署 OpenClaw 或進行重大設定變更後，應執行完整的安全審計。以下是分類的審計 Checklist：

憑證管理類

所有 API Key 均透過環境變數或系統 Keychain 儲存，無明文寫入設定檔
.gitignore 包含所有敏感檔案類型規則
Git 歷史中未包含任何 API Key 或 Token（使用 git secrets --scan-history 驗證）
已為每個 AI 供應商設定月度用量上限與告警
API Key 命名規範包含日期與用途，便於追蹤
已建立金鑰輪換時程表並設定行事曆提醒

OAuth 認證類

Anthropic OAuth 已設定最小必要 Scope（無多餘授權）
OAuth 回調 URL 僅接受 HTTPS（生產環境）
已確認 Refresh Token 的有效期限並設定到期前通知
已測試 Token 自動刷新機制的正確運作
已設定 OAuth 狀態參數（state）以防止 CSRF 攻擊

存取控制類

已應用最小權限原則，每個 API Key 僅具備完成任務所需的最低權限
企業部署已設定基於角色的存取控制（RBAC）
服務帳號與個人帳號使用獨立憑證
已設定 IP 白名單或網路層存取控制（如適用）
所有管理員操作均有獨立審計日誌

Skills 安全類

已評估所有已安裝 Skills 的來源與權限請求
僅安裝來自可信來源的 Skills
已設定 Skills 沙箱規則，禁止 Skills 存取模型供應商憑證
定期審查 Skills 更新，確認更新未引入新的權限請求
已訂閱 OpenClaw 安全公告，及時獲知新漏洞資訊

日誌與監控類

已啟用審計日誌功能（audit_log: true）
日誌中確認憑證遮蔽功能正常（log_redaction: true）
已設定異常用量告警並測試告警觸發
日誌保留期限符合合規要求（建議至少 90 天）
日誌儲存位置具備適當的存取控制

10.2 定期安全審計（每季度）

以下項目建議每季度執行一次：

# 執行完整安全審計腳本
openclaw security audit --full --output report-$(date +%Y%Q).json

# 審計包含以下檢查項目：
# 1. 憑證到期時間檢查
# 2. 未使用的 API Key 識別
# 3. 異常用量模式分析
# 4. Skills 權限審查
# 5. RBAC 規則有效性驗證
# 6. 網路設定安全性掃描

# 輸出審計報告
openclaw security audit --format html --output security-report.html

季度審計完成後，應執行的後續動作包括：輪換即將到期的 API Key、撤銷已識別的未使用或可疑金鑰、更新 RBAC 規則以反映人員異動、評估新版本的安全更新是否需要緊急部署。

10.3 安全事件響應程序

當懷疑發生 API Key 洩漏或認證異常時，應按以下優先順序執行響應：

即時（0-15 分鐘）：立即至所有涉及的 AI 供應商控制台撤銷可疑金鑰；暫停 OpenClaw 實例的所有自動化任務；通知安全團隊
短期（15-60 分鐘）：生成新的替代金鑰並更新所有相關服務；調查洩漏根源（日誌分析、Git 歷史掃描）；評估洩漏期間的異常用量
中期（1-24 小時）：完整的事件調查報告；識別並修補洩漏根本原因；更新安全政策與操作程序
長期（後續 30 天）：強化監控機制；員工安全意識培訓；考慮導入更嚴格的憑證管理工具（如 HashiCorp Vault）

10.4 進階防護：HashiCorp Vault 整合

對於安全要求極高的企業環境，建議將 OpenClaw 與 HashiCorp Vault 整合，實現動態憑證管理：

# HashiCorp Vault 整合設定（config.yaml）
credential_backend:
  type: vault
  vault:
    address: "https://vault.internal:8200"
    auth_method: kubernetes  # 或 approle, aws, etc.
    mount_path: "secret"
    paths:
      anthropic_key: "secret/data/openclaw/anthropic"
      openai_key: "secret/data/openclaw/openai"
    # Token 從 Kubernetes Service Account 自動取得
    kubernetes:
      role: "openclaw-app"
      service_account_token_path: "/var/run/secrets/kubernetes.io/serviceaccount/token"

Vault 整合帶來的安全優勢包括：動態生成短期憑證（每次請求都可使用不同 Token）、完整的憑證存取稽核軌跡、集中化的憑證管理（任何服務的金鑰輪換都只需在 Vault 操作一次）、與企業身份系統的深度整合。

OpenClaw 的認證架構設計，在便利性與安全性之間需要持續的平衡與取捨。在 AI 代理能力持續強化的趨勢下，這個平衡點也在不斷移動：代理能做的事情越多，對應的認證安全要求就越高。建議企業技術團隊將 OpenClaw 的認證管理視為一個持續演進的工程課題，而非一次性的設定任務。

本指南涵蓋的範圍從基本 API Key 設定到企業級 SSO 整合，但實際部署中難免遇到特殊情況。如需針對特定企業環境的認證架構設計諮詢，歡迎聯繫超智諮詢的技術顧問團隊，我們可協助評估您的 OpenClaw 部署架構並提供客製化的安全設計建議。

核心重點

一、AI 代理時代的身份驗證挑戰

1.1 自主代理帶來的憑證風險新維度

1.2 OpenClaw 的認證責任邊界

二、OpenClaw 認證架構概覽

2.1 四層架構中的認證層

2.2 支援的認證方式矩陣

2.3 設定檔位置與結構

三、Anthropic Claude OAuth 設定

3.1 OAuth 2.0 授權碼流程解析

3.2 透過 GUI 完成 Claude OAuth 授權

3.3 使用 claude setup-token 命令列設定

3.4 Token 刷新與生命週期管理

四、OpenAI API Key 設定

4.1 在 OpenAI Platform 生成 API Key

4.2 在 OpenClaw 中設定 OpenAI API Key

4.3 API Key 驗證與模型可用性確認

4.4 API Key 輪換流程

五、開源模型認證（DeepSeek、Ollama）

5.1 DeepSeek API Key 設定

5.2 Ollama 本地模型認證設定

5.3 自架模型 API 端點的通用設定

六、多模型切換的認證管理

6.1 認證上下文的隔離原則

6.2 模型路由策略與認證切換

6.3 認證健康檢查與自動容錯

七、Token 安全管理最佳實踐

7.1 憑證儲存的安全分級

7.2 版本控制中的憑證防護

7.3 金鑰輪換時程表

7.4 用量監控與異常告警

八、企業 SSO 與 SAML 整合

8.1 企業認證架構設計原則

8.2 SAML 2.0 整合設定

8.3 Azure Active Directory 整合

8.4 服務帳號與非互動式認證

九、常見錯誤與排除指南

9.1 認證錯誤代碼速查表

9.2 OAuth 流程常見問題

9.3 Skills 相關的認證問題

十、安全審計 Checklist

10.1 初始部署安全審計

10.2 定期安全審計（每季度）

10.3 安全事件響應程序

10.4 進階防護：HashiCorp Vault 整合

訂閱電子報，掌握最新洞見

想深入探討這個議題？

References

相關洞見

從對話到代理：OpenClaw 架構解析與實戰部署全指南

OpenClaw 企業整合實戰：Notion、Microsoft Teams 與 Slack 全通路 AI 助理部署指南

OpenClaw Gateway 模式完整指南：遠端部署、Headless 運行與雲端架構實踐

3.3 使用 `claude setup-token` 命令列設定