Codex 報「missing environment variable」怎麼辦：env_key、MCP 環境變量、命令讀不到變量的官方配置說明

本文根據 Codex 官方配置文檔（Advanced Configuration、配置參考、環境變量、Config basics）和 MCP 文檔整理，資料核對於 2026-10-27。官方沒有單獨解釋「missing environment variable」這句報錯，本文說明官方配置裏和環境變量有關的設定，幫你對號入座。配圖為本站整理的示意圖，不是軟件截圖。

適用於誰

• 在 config.toml 裏配置了第三方或公司網關作為模型提供方，啟動時提示缺少某個環境變量的人；
• 配置了 MCP 伺服器，提示缺少令牌或密鑰的人；
• 讓 Codex 運行命令時，命令讀不到自己設定的變量的人；
• 在腳本或 CI 裏跑 codex exec 的人。

結論先說

1. 報錯點名了一個變量名，就去 config.toml 裏找它。 自定義模型提供方的密鑰來自 env_key：官方寫法是 env_key = "變量名"，Codex 會讀取本機裏這個名字的環境變量。變量名是你自己在配置裏決定的，Codex 沒有固定的變量名，所以要保證配置裏寫的名字和你設定的變量名完全一致。
2. 變量要在啟動 Codex 的那個環境裏存在。 在一個終端裏設定的變量，通常只對那個終端和它啟動的程序可見，用別的方式（比如從圖標啟動桌面 App、IDE）啟動的 Codex 不一定能讀到。這是環境變量的通用規則，不是 Codex 文檔裏的特別說明。
3. MCP 伺服器的變量用 env_vars 聲明要轉發的變量，令牌變量用 bearer_token_env_var 指定名字。
4. Codex 運行的命令讀不到變量，看 shell_environment_policy，它控制傳給被啟動命令的環境變量。
5. 不要把令牌直接寫進配置文件：官方把 experimental_bearer_token 標為不推薦，應使用 env_key。

圖：本站根據 Codex 官方文檔：配置參考 與 環境變量 整理的示意圖

一、自定義模型提供方的 env_key

官方認證文檔和配置文檔裏的說法：在 config.toml 裏定義了自定義模型提供方後，有三種認證方式：

• requires_openai_auth = true：使用 OpenAI 的認證，之後用 ChatGPT 或 API 密鑰登入，適合經過 LLM 代理訪問 OpenAI 模型；
• env_key = "變量名"：從本機該名字的環境變量裏讀取這個提供方的 API 密鑰；
• 兩者都不設：Codex 認為提供方不需要認證，適合本地模型。

官方的示例配置裏，一個提供方寫成這樣：

toml
[model_providers.mistral]
name = "Mistral"
base_url = "https://api.mistral.ai/v1"
env_key = "MISTRAL_API_KEY"

意思是：Codex 向這個提供方發請求時，會去環境裏找名為 MISTRAL_API_KEY 的變量，找不到就會提示缺少。官方環境變量文檔也明確寫了：提供方的密鑰變量名是你用 env_key 自己選的，不是 Codex 固定讀取的變量。配置參考裏還有一個可選的 env_key_instructions，用來寫這個密鑰怎麼獲取的提示。

圖：本站根據 Codex 官方文檔：Advanced Configuration 整理的示意圖

不要混用認證方式：官方配置參考寫明，命令式認證（auth 表，用命令輸出令牌）不要和 env_key、experimental_bearer_token、requires_openai_auth 同時使用。第三方模型怎麼接入，見 /guides/codex-third-party-models-deepseek-gemini-grok 和 /guides/deepseek-codex-setup。

二、MCP 伺服器的環境變量

官方 MCP 文檔裏，STDIO 類伺服器的幾個與環境有關的選項：

• env：給伺服器設定的環境變量；
• env_vars：允許並轉發給伺服器的環境變量，可以寫變量名，也可以寫帶來源的對象，官方示例：env_vars = ["LOCAL_TOKEN", { name = "REMOTE_TOKEN", source = "remote" }]；
• HTTP 類伺服器還有 bearer_token_env_var（放在 Authorization 裏發送的令牌變量名）和 env_http_headers（請求頭名到環境變量名的映射，值從環境裏取）。

提示缺少 MCP 用的變量時，對照你的 MCP 配置，看它引用了哪個變量名，再確認啟動 Codex 的環境裏有同名變量。MCP 的完整配置見 /guides/codex-mcp-config。

三、命令讀不到變量：shell_environment_policy

這是另一種「缺少變量」：Codex 在沙箱裏運行命令時，命令裏的程序讀不到你以為存在的變量。官方說明，shell_environment_policy 控制 Codex 傳給被啟動命令的環境變量：

• inherit = "none" 從空環境開始，inherit = "core" 繼承一組精簡的核心變量；
• set = { MY_FLAG = "1" } 顯式設定一些值；
• [shell_environment_policy.filters] 用模式（支持 * 和 ?，不區分大小寫）排除或只包含某些變量，一旦任何一條用了 include，就只保留匹配包含規則的變量，已被排除的變量不會被 include 恢復；
• ignore_default_excludes 預設是 true，也就是不自動過濾名字裏含 KEY、SECRET、TOKEN 的變量，設成 false 才會啟用這個自動過濾。

所以命令讀不到某個變量時：看你的配置裏有沒有 inherit = "none"、include 規則或排除規則把它擋掉了。官方還寫明，舊的 exclude 和 include_only 數組不要和 filters 在同一層配置裏同時使用，否則 Codex 會拒絕這種組合。配置文件的位置和優先級見官方 Config basics：命令行參數最高，其次是項目 .codex/config.toml（只有信任的項目才加載），再到用戶的 ~/.codex/config.toml。

四、腳本、CI 和 CODEX_HOME

官方環境變量文檔列的幾個：

• CODEX_API_KEY：給 codex exec 這樣的非交互進程提供 API 密鑰。官方建議在運行倉庫裏的受控代碼時，只在需要的那一行設定，而不是對整個作業設定；
• CODEX_ACCESS_TOKEN：給受信任的自動化提供訪問令牌，要持久登入用 codex login --with-access-token；
• CODEX_HOME：Codex 狀態的根目錄（配置、登入、日誌、會話、技能都在這裏），預設 ~/.codex。如果你設定了它，這個目錄必須已經存在；
• RUST_LOG：控制日誌詳細程度，排查時可以用，分享日誌前注意清除密鑰。

五、還是不行

• 先看 ~/.codex/config.toml 裏與報錯相關的那一段，變量名逐字對照；
• 在命令行裏用 /debug-config 看配置層和生效情況；
• 登入相關的問題見 /guides/codex-cannot-sign-in-send-message-connect 和 /guides/codex-401-unauthorized-error。

常見問題

Q：為什麼 Windows 上設定了變量還是讀不到？

官方文檔沒有給 Windows 下設定變量的專門說明。通用的原則是：變量要對啟動 Codex 的進程可見。設定之後要重新啟動 Codex，必要時重新打開終端。

Q：密鑰寫在 config.toml 裏行不行？

官方把直接寫令牌的 experimental_bearer_token 標為不推薦，應使用 env_key。config.toml 裏不要放密鑰，也不要提交到代碼倉庫。

Q：想用 DeepSeek 或別的第三方模型？

見 /guides/deepseek-codex-setup。

參考資料

• Codex 官方文檔：Advanced Configuration — https://learn.chatgpt.com/docs/config-file/config-advanced
• Codex 官方文檔：Configuration Reference — https://learn.chatgpt.com/docs/config-file/config-reference
• Codex 官方文檔：Environment variables — https://learn.chatgpt.com/docs/config-file/environment-variables
• Codex 官方文檔：Config basics — https://learn.chatgpt.com/docs/config-file/config-basic
• Codex 官方文檔：Model Context Protocol — https://learn.chatgpt.com/docs/extend/mcp