設定 OpenClaw 連接 OpenAI：API Key 與 Codex 訂閱指南

身為開發者，你可能常在 OpenAI 的 API key 和 ChatGPT 訂閱之間猶豫不決。有時候你想要穩定的按量計費，有時候又想直接用現有的訂閱方案來跑自動化流程。設定這些環境通常很瑣碎，尤其當你得處理不同的傳輸協議或模型版本時。

OpenClaw 讓你能在這兩種模式間無縫切換。OpenAI 提供 GPT 模型的開發者 API，而 Codex 支援 ChatGPT 登入（訂閱制）或 API key 登入（按量計費）。Codex 雲端版需要 ChatGPT 登入。OpenAI 明確支援在 OpenClaw 等外部工具中使用訂閱制的 OAuth 流程。

選項 A：OpenAI API key (OpenAI Platform)

最適合： 直接存取 API 並使用按量計費。你可以從 OpenAI dashboard 取得你的 API key。

CLI 設定

openclaw onboard --auth-choice openai-api-key
# or non-interactive
openclaw onboard --openai-api-key "$OPENAI_API_KEY"

設定檔片段

{
  env: { OPENAI_API_KEY: "sk-..." },
  agents: { defaults: { model: { primary: "openai/gpt-5.4" } } },
}

OpenAI 目前的 API 模型文件列出了 gpt-5.4 和 gpt-5.4-pro 供直接使用。OpenClaw 會透過 openai/* Responses 路徑轉發這兩者。OpenClaw 刻意隱藏了過時的 openai/gpt-5.3-codex-spark 項目，因為直接呼叫 OpenAI API 會在實際流量中拒絕它。

OpenClaw 不會在直接的 OpenAI API 路徑上公開 openai/gpt-5.3-codex-spark。雖然 pi-ai 仍內建該模型的項目，但目前的 OpenAI API 請求會拒絕它。在 OpenClaw 中，Spark 被視為 Codex 專用。

選項 B：OpenAI Code (Codex) 訂閱

最適合： 使用 ChatGPT/Codex 訂閱權限而非 API key。 Codex 雲端版需要 ChatGPT 登入，而 Codex CLI 則支援 ChatGPT 或 API key 登入。

CLI 設定 (Codex OAuth)

# Run Codex OAuth in the wizard
openclaw onboard --auth-choice openai-codex

# Or run OAuth directly
openclaw models auth login --provider openai-codex

設定檔片段 (Codex 訂閱)

{
  agents: { defaults: { model: { primary: "openai-codex/gpt-5.4" } } },
}

OpenAI 目前的 Codex 文件將 gpt-5.4 列為目前的 Codex 模型。OpenClaw 會將其對應到 openai-codex/gpt-5.4 以供 ChatGPT/Codex OAuth 使用。

如果你的 Codex 帳號擁有 Codex Spark 權限，OpenClaw 也支援：

openai-codex/gpt-5.3-codex-spark

OpenClaw 將 Codex Spark 視為 Codex 專用，不會提供直接的 openai/gpt-5.3-codex-spark API-key 路徑。

當 pi-ai 偵測到 openai-codex/gpt-5.3-codex-spark 時，OpenClaw 也會保留它。請將其視為依賴權限且實驗性質的功能：Codex Spark 與 GPT-5.4 /fast 是分開的，可用性取決於登入的 Codex / ChatGPT 帳號。

傳輸預設值

OpenClaw 使用 pi-ai 進行模型串流。對於 openai/* 和 openai-codex/*，預設傳輸方式為 "auto"（優先使用 WebSocket，失敗則退回 SSE）。

你可以設定 agents.defaults.models.<provider/model>.params.transport：

"sse"：強制使用 SSE
"websocket"：強制使用 WebSocket
"auto"：嘗試 WebSocket，失敗則退回 SSE

對於 openai/* (Responses API)，當使用 WebSocket 傳輸時，OpenClaw 預設會啟用 WebSocket 預熱 (openaiWsWarmup: true)。

相關 OpenAI 文件：

{
  agents: {
    defaults: {
      model: { primary: "openai-codex/gpt-5.4" },
      models: {
        "openai-codex/gpt-5.4": {
          params: {
            transport: "auto",
          },
        },
      },
    },
  },
}

OpenAI WebSocket 預熱

OpenAI 文件提到預熱是選用的。OpenClaw 預設為 openai/* 啟用它，以減少使用 WebSocket 傳輸時的首輪延遲。

停用預熱

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: {
            openaiWsWarmup: false,
          },
        },
      },
    },
  },
}

明確啟用預熱

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: {
            openaiWsWarmup: true,
          },
        },
      },
    },
  },
}

OpenAI 與 Codex 優先處理

OpenAI 的 API 透過 service_tier=priority 提供優先處理功能。在 OpenClaw 中，設定 agents.defaults.models["<provider>/<model>"].params.serviceTier 即可在原生的 OpenAI/Codex Responses 端點傳遞該欄位。

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: {
            serviceTier: "priority",
          },
        },
        "openai-codex/gpt-5.4": {
          params: {
            serviceTier: "priority",
          },
        },
      },
    },
  },
}

支援的值包括 auto, default, flex, 和 priority。

當模型指向原生 OpenAI/Codex 端點時，OpenClaw 會將 params.serviceTier 轉發給直接的 openai/* Responses 請求和 openai-codex/* Codex Responses 請求。

重要行為：

直接的 openai/* 必須指向 api.openai.com
openai-codex/* 必須指向 chatgpt.com/backend-api
如果你透過其他基礎 URL 或代理伺服器路由，OpenClaw 會保持 service_tier 不變

OpenAI 快速模式

OpenClaw 為 openai/* 和 openai-codex/* 會話提供了一個共用的快速模式開關：

聊天/介面：/fast status|on|off
設定：agents.defaults.models["<provider>/<model>"].params.fastMode

啟用快速模式時，OpenClaw 會將其對應到 OpenAI 的優先處理：

指向 api.openai.com 的直接 openai/* Responses 呼叫會發送 service_tier = "priority"
指向 chatgpt.com/backend-api 的 openai-codex/* Responses 呼叫也會發送 service_tier = "priority"
現有的 payload service_tier 值會被保留
快速模式不會重寫 reasoning 或 text.verbosity

範例：

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: {
            fastMode: true,
          },
        },
        "openai-codex/gpt-5.4": {
          params: {
            fastMode: true,
          },
        },
      },
    },
  },
}

會話覆寫 (Session overrides) 的優先級高於設定檔。在會話 UI 中清除覆寫後，會話將恢復為設定的預設值。

OpenAI Responses 伺服器端壓縮

對於直接的 OpenAI Responses 模型（使用 api: "openai-responses" 且 baseUrl 為 api.openai.com 的 openai/*），OpenClaw 現在會自動啟用 OpenAI 伺服器端壓縮 payload 提示：

強制 store: true（除非模型相容性設定為 supportsStore: false）
注入 context_management: [{ type: "compaction", compact_threshold: ... }]

預設情況下，compact_threshold 為模型 contextWindow 的 70%（若無法取得則為 80000）。

明確啟用伺服器端壓縮

當你想在相容的 Responses 模型（例如 Azure OpenAI Responses）上強制注入 context_management 時，請使用此設定：

{
  agents: {
    defaults: {
      models: {
        "azure-openai-responses/gpt-5.4": {
          params: {
            responsesServerCompaction: true,
          },
        },
      },
    },
  },
}

使用自定義閾值啟用

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: {
            responsesServerCompaction: true,
            responsesCompactThreshold: 120000,
          },
        },
      },
    },
  },
}

停用伺服器端壓縮

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: {
            responsesServerCompaction: false,
          },
        },
      },
    },
  },
}

responsesServerCompaction 僅控制 context_management 的注入。直接的 OpenAI Responses 模型仍會強制 store: true，除非相容性設定為 supportsStore: false。

注意事項

模型引用一律使用 provider/model 格式（請參閱 /concepts/models）。
認證細節與重複使用規則請見 /concepts/oauth。

下一步：

了解模型概念
探索 OAuth 認證機制

需要協助設定嗎？試試我們的 AI Setup Assistant！

OpenClaw Expert

還是卡住了？

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