設定 OpenClaw 連接 Anthropic Claude：API 金鑰與快取優化

每次想在專案裡整合 Claude，光是搞定 API key 和不同模型的設定就讓人頭大。OpenClaw 讓這件事變得超簡單，無論你是要用 API 還是直接複用訂閱帳號，這篇指南會幫你快速搞定。

Anthropic (Claude)

Anthropic 開發了 Claude 系列模型，並透過 API 提供存取。在 OpenClaw 中，你可以使用 API key 或 setup-token 進行身分驗證。

選項 A：Anthropic API key

最適合： 標準 API 存取與按量計費。請在 Anthropic Console 建立你的 API key。

CLI 設定

openclaw onboard
# choose: Anthropic API key

# or non-interactive
openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY"

Claude CLI 設定片段

{
  env: { ANTHROPIC_API_KEY: "sk-ant-..." },
  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
}

思考模式預設值 (Claude 4.6)

當沒有明確設定思考層級時，Anthropic Claude 4.6 模型在 OpenClaw 中預設使用 adaptive 思考模式。
你可以針對單一訊息進行覆蓋 (/think:<level>)，或在模型參數中設定： agents.defaults.models["anthropic/<model>"].params.thinking。
相關 Anthropic 文件：
- Adaptive thinking
- Extended thinking

快速模式 (Anthropic API)

OpenClaw 的共享 /fast 開關也支援直接的 Anthropic 公開流量，包括發送到 api.anthropic.com 的 API-key 和 OAuth 驗證請求。

/fast on 對應到 service_tier: "auto"
/fast off 對應到 service_tier: "standard_only"
預設設定：

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-sonnet-4-6": {
          params: { fastMode: true },
        },
      },
    },
  },
}

重要限制：

OpenClaw 僅針對直接發送到 api.anthropic.com 的請求注入 Anthropic 服務層級。如果你透過 proxy 或 Gateway 路由 anthropic/*，/fast 不會更動 service_tier。
當同時設定時，明確的 Anthropic serviceTier 或 service_tier 模型參數會覆蓋 /fast 預設值。
Anthropic 會在回應的 usage.service_tier 中回報生效的層級。在沒有 Priority Tier 容量的帳號上，service_tier: "auto" 可能仍會解析為 standard。

提示詞快取 (Anthropic API)

OpenClaw 支援 Anthropic 的 Prompt Caching 功能。這僅限 API 使用；訂閱制驗證不支援快取設定。

設定方式

在你的模型設定中使用 cacheRetention 參數：

數值	快取持續時間	描述
`none`	不快取	停用提示詞快取
`short`	5 分鐘	API Key 驗證的預設值
`long`	1 小時	延長快取 (需要 beta flag)

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": {
          params: { cacheRetention: "long" },
        },
      },
    },
  },
}

預設值

使用 Anthropic API Key 驗證時，OpenClaw 會自動為所有 Anthropic 模型套用 cacheRetention: "short" (5 分鐘快取)。你可以透過在設定中明確指定 cacheRetention 來覆蓋此設定。

針對個別 Agent 的 cacheRetention 覆蓋

使用模型層級的參數作為基準，然後透過 agents.list[].params 覆蓋特定的 Agent。

{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-opus-4-6" },
      models: {
        "anthropic/claude-opus-4-6": {
          params: { cacheRetention: "long" }, // baseline for most agents
        },
      },
    },
    list: [
      { id: "research", default: true },
      { id: "alerts", params: { cacheRetention: "none" } }, // override for this agent only
    ],
  },
}

快取相關參數的設定合併順序：

agents.defaults.models["provider/model"].params
agents.list[].params (匹配 id，依 key 覆蓋)

這讓一個 Agent 可以保持長效快取，而另一個使用相同模型的 Agent 則可以停用快取，以避免在低重複性的突發流量中產生寫入成本。

Bedrock Claude 注意事項

在 Bedrock 上的 Anthropic Claude 模型 (amazon-bedrock/*anthropic.claude*) 在設定後可接受 cacheRetention 傳遞。
非 Anthropic 的 Bedrock 模型在執行時會被強制設定為 cacheRetention: "none"。
當沒有設定明確數值時，Anthropic API-key 的智慧預設值也會為 Claude-on-Bedrock 模型引用套用 cacheRetention: "short"。

舊版參數

為了回溯相容性，目前仍支援舊的 cacheControlTtl 參數：

"5m" 對應到 short
"1h" 對應到 long

我們建議遷移到新的 cacheRetention 參數。

OpenClaw 在 Anthropic API 請求中包含了 extended-cache-ttl-2025-04-11 beta flag；如果你覆蓋了 provider headers，請保留它 (參見 /gateway/configuration)。

1M 上下文視窗 (Anthropic beta)

Anthropic 的 1M 上下文視窗目前處於 Beta 階段。在 OpenClaw 中，可以針對支援的 Opus/Sonnet 模型透過 params.context1m: true 來啟用。

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": {
          params: { context1m: true },
        },
      },
    },
  },
}

OpenClaw 會在 Anthropic 請求中將此設定對應為 anthropic-beta: context-1m-2025-08-07。

這只有在該模型的 params.context1m 明確設定為 true 時才會啟動。

需求：Anthropic 必須允許該憑證使用長上下文 (通常是 API key 計費帳號，或啟用了 Extra Usage 的訂閱帳號)。否則 Anthropic 會回傳： HTTP 429: rate_limit_error: Extra usage is required for long context requests。

注意：當使用訂閱 setup-tokens (sk-ant-oat-*) 時，Anthropic 目前會拒絕 context-1m-* 的 beta 請求。如果你在訂閱驗證下設定了 context1m: true，OpenClaw 會記錄警告並跳過 context1m beta header，同時保留必要的 OAuth betas，退回到標準上下文視窗。

選項 B：將 Claude CLI 作為訊息提供者

最適合： 已經安裝 Claude CLI 並登入 Claude 訂閱的單使用者 Gateway 主機。

此路徑使用本地的 claude 二進位檔進行模型推論，而不是直接呼叫 Anthropic API。OpenClaw 將其視為 CLI backend provider，模型引用如下：

claude-cli/claude-sonnet-4-6
claude-cli/claude-opus-4-6

運作原理：

OpenClaw 在 Gateway 主機上啟動 claude -p --output-format json ...。
第一輪對話會發送 --session-id <uuid>。
後續對話透過 --resume <sessionId> 複用儲存的 Claude 工作階段。
你的聊天訊息仍會經過正常的 OpenClaw 訊息管線，但實際的模型回覆是由 Claude CLI 產生的。

需求

Gateway 主機上已安裝 Claude CLI 且可在 PATH 中找到，或已設定絕對路徑。
Claude CLI 已在該主機上完成驗證：

claude auth status

當你的設定明確引用 claude-cli/... 或 claude-cli backend 設定時，OpenClaw 會在 Gateway 啟動時自動載入內建的 Anthropic 外掛。

設定片段

{
  agents: {
    defaults: {
      model: {
        primary: "claude-cli/claude-sonnet-4-6",
      },
      models: {
        "claude-cli/claude-sonnet-4-6": {},
      },
      sandbox: { mode: "off" },
    },
  },
}

如果 claude 二進位檔不在 Gateway 主機的 PATH 中：

{
  agents: {
    defaults: {
      cliBackends: {
        "claude-cli": {
          command: "/opt/homebrew/bin/claude",
        },
      },
    },
  },
}

你可以獲得

複用本地 CLI 的 Claude 訂閱驗證
正常的 OpenClaw 訊息/工作階段路由
跨輪對話的 Claude CLI 工作階段連續性

從 Anthropic 驗證遷移到 Claude CLI

如果你目前使用 anthropic/... 搭配 setup-token 或 API key，並想將同一台 Gateway 主機切換到 Claude CLI：

openclaw models auth login --provider anthropic --method cli --set-default

或在 onboarding 過程中：

openclaw onboard --auth-choice anthropic-cli

這會執行以下操作：

驗證 Claude CLI 是否已在 Gateway 主機上登入
將預設模型切換為 claude-cli/...
將 Anthropic 預設模型回退選項 (如 anthropic/claude-opus-4-6) 改寫為 claude-cli/claude-opus-4-6
在 agents.defaults.models 中加入對應的 claude-cli/... 項目

這不會執行以下操作：

刪除你現有的 Anthropic 驗證設定檔
移除主預設模型/允許清單路徑之外的每個舊 anthropic/... 設定引用

這讓還原變得簡單：如果需要，只需將預設模型改回 anthropic/... 即可。

重要限制

這不是 Anthropic API 提供者。它是本地 CLI 執行環境。
CLI backend 執行時，OpenClaw 端的 Tools 會被停用。
純文字輸入，純文字輸出。不支援 OpenClaw 串流接力。
最適合個人 Gateway 主機，不適合共享的多使用者計費設定。

更多細節：/gateway/cli-backends

選項 C：Claude setup-token

最適合： 使用你的 Claude 訂閱。

從哪裡取得 setup-token

Setup-tokens 是由 Claude Code CLI 建立的，而不是 Anthropic Console。你可以在任何機器上執行：

claude setup-token

將 token 貼入 OpenClaw (精靈模式：Anthropic token (paste setup-token))，或在 Gateway 主機上執行：

openclaw models auth setup-token --provider anthropic

如果你是在不同機器上產生的 token，請貼上它：

openclaw models auth paste-token --provider anthropic

CLI 設定 (setup-token)

# Paste a setup-token during setup
openclaw onboard --auth-choice setup-token

設定片段 (setup-token)

{
  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
}

注意事項

使用 claude setup-token 產生 setup-token 並貼上，或在 Gateway 主機上執行 openclaw models auth setup-token。
如果你在 Claude 訂閱上看到「OAuth token refresh failed …」，請使用 setup-token 重新驗證。參見 /gateway/troubleshooting。
驗證細節與複用規則請見 /concepts/oauth。

疑難排解

401 錯誤 / token 突然失效

Claude 訂閱驗證可能會過期或被撤銷。請重新執行 claude setup-token 並將其貼入 Gateway 主機。
如果 Claude CLI 登入資訊在另一台機器上，請在 Gateway 主機上使用 openclaw models auth paste-token --provider anthropic。

找不到 provider “anthropic” 的 API key

驗證是針對每個 Agent 的。新的 Agent 不會繼承主 Agent 的 key。
針對該 Agent 重新執行 onboarding，或在 Gateway 主機上貼上 setup-token / API key，然後使用 openclaw models status 驗證。

找不到 profile anthropic:default 的憑證

執行 openclaw models status 查看哪個驗證設定檔是啟用的。
重新執行 onboarding，或為該設定檔貼上 setup-token / API key。

沒有可用的驗證設定檔 (全部處於冷卻中/不可用)

檢查 openclaw models status --json 中的 auth.unusableProfiles。
新增另一個 Anthropic 設定檔或等待冷卻結束。

更多資訊：/gateway/troubleshooting 與 /help/faq。

下一步：

有任何設定上的問題嗎？試試我們的 AI Setup Assistant！

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。