一、先說結論：多環境接入的核心是統一變量，不是反復復制配置

很多團隊在第一臺電腦上跑通 Codex 后，會自然地把配置發給其他成員。但到了第二臺、第三臺機器，問題就開始出現：有人用 PowerShell，有人用 WSL，有人把 Codex 放進 Docker，有人只在 CI 里跑自動化任務。每個環境的變量讀取方式不同，路徑不同，權限不同，最終導致“明明一樣的配置，結果就是不一樣”。

解決這類問題，不靠更多截圖，也不靠每個人手動記憶，而是先制定統一變量名和統一驗證流程。無論環境是 Windows、WSL、Docker 還是 CI，都圍繞同一組字段：*ase **L、API Key、模型名、任務場景、是否啟用。字段統一之后，環境差異只剩下“這些字段放在哪里、怎么注入、怎么驗證”。

使用靈能API作為統一入口，可以先把請求鏈路穩定下來，再把環境適配層拆開處理。這樣團隊討論問題時，不會混淆“入口不一致”和“環境變量沒生效”兩類問題。

• 統一入口：所有成員從同一處確認接入說明。
• 統一變量：所有環境使用同一套變量命名。
• 統一驗證：每個環境都跑同一套最小測試。
• 統一記錄：失敗時記錄環境、變量、配置卡和錯誤碼。

二、先確認控制臺入口：別讓舊地址混進新環境

多環境接入前，先確認團隊使用的是同一個控制臺入口和同一份接入說明。通過靈能API進入控制臺后，查看當前接口說明、模型可用情況和賬號狀態。這個動作要放在環境配置之前，因為很多失敗并不是本機問題，而是地址、權限或模型信息已經變化。

建議團隊文檔只保留一個可信入口：通過 https://www.lnsns.com/ 進入靈能API，并以控制臺當前說明為準。不要在多個項目文檔里復制完整接入字段，否則后續某一處更新、另一處未更新，就會出現隱蔽的不一致。

控制臺信息確認后，再把配置拆成公開字段和敏感字段。*ase **L、模型名、任務場景可以寫進團隊說明；API Key、Secret、內部賬號權限不能寫進公共文檔。這個邊界一開始定清楚，后面遷移到容器和 CI 才不會亂。

• 公開字段適合寫入文檔，敏感字段只能放入本機安全區或 CI Secret。
• 舊截圖只能作為參考，不能作為最終配置來源。
• 每次環境遷移前，先核對控制臺，而不是先改腳本。

三、設計統一變量表：讓每個環境都說同一種語言

變量名不統一，是多環境接入最常見的坑。Windows 寫 CODEX_API_KEY，WSL 寫 OPENAI_API_KEY，Docker 又寫 RELAY_TOKEN，CI 里再加一個 AI_KEY。短期看都能用，長期看任何一個人接手都會迷路。建議從一開始就定義團隊變量表，并且在所有環境里保持一致。

一套足夠清晰的變量通常包括五項：CODEX_*ASE_**L、CODEX_API_KEY、CODEX_MODEL、CODEX_PROFILE、CODEX_ENA*LED。前三個負責接入，**個負責區分場景，第五個負責快速停用。不要一開始就拆出十幾個變量，變量過多會讓排查成本上升。

推薦變量表

CODEX_*ASE_**L   接入入口，來自控制臺說明
CODEX_API_KEY    憑證，只能放入安全位置
CODEX_MODEL      當前任務使用的模型
CODEX_PROFILE    light / stan**rd / deep / ci
CODEX_ENA*LED    true / false，用于快速停用自動任務

變量表要寫明字段來源、是否敏感、誰維護、怎么驗證。尤其是 CODEX_API_KEY，不要只寫“填入 Key”，而要寫清楚它不能進倉庫、不能進截圖、不能進聊天記錄、不能保存在公共腳本里。

• 變量名統一后，環境差異只剩注入方式。
• 變量數量保持克制，先滿足主要場景。
• 每個變量都要有來源說明和驗證方式。

四、Windows 環境：PowerShell 配置要區分臨時和持久

Windows 上最容易混淆的是臨時變量和持久變量。臨時變量只在當前 PowerShell 窗口生效，關掉窗口就沒了；持久變量寫入用戶環境，后續新窗口也能讀取。調試階段建議先用臨時變量，確認鏈路沒問題后，再決定是否寫成持久配置。

# 當前窗口臨時生效
$env:CODEX_*ASE_**L = "https://www.lnsns.com/"
$env:CODEX_API_KEY = "從安全位置注入，不寫入腳本"
$env:CODEX_MODEL = "按控制臺可用模型填寫"
$env:CODEX_PROFILE = "stan**rd"

# 驗證變量是否存在
$env:CODEX_*ASE_**L
$env:CODEX_MODEL

如果需要持久配置，可以使用系統環境變量界面或安全的本機憑據管理方式。這里不建議把完整 Key 寫在普通文本腳本里，因為腳本很容易被復制、截圖或提交到倉庫。團隊文檔中只給出變量名和占位符，不給出真實憑證。

Windows 還要注意終端切換。PowerShell、命令提示符、編輯器內置終端、**服務讀變量的時機可能不同。修改持久變量后，通常需要打開新終端或重啟相關進程，舊窗口不會自動拿到新值。

• 調試先用臨時變量，穩定后再考慮持久變量。
• 修改持久變量后，新開終端再測試。
• 不要把完整 Key 寫入可被提交的腳本。

五、WSL 環境：它不是 Windows 變量的自動鏡像

WSL 是很多人容易踩坑的地方。Windows 里配置好的變量，不一定會以你預期的方式出現在 WSL 里；即使某些變量能傳入，也不建議長期依賴隱式繼承。更穩的做法，是在 WSL 內部單獨配置需要的變量，并用同一套變量名保持一致。

如果團隊成員主要在 WSL 中運行 Codex，就應該把 WSL 當成獨立 Linux 環境處理。可以把非敏感字段放進 shell 配置，敏感 Key 仍然通過安全方式注入。每次新開 WSL 終端后，先跑變量檢查，再跑 Codex 最小任務。

export CODEX_*ASE_**L="https://www.lnsns.com/"
export CODEX_API_KEY="從安全位置注入，不寫入倉庫"
export CODEX_MODEL="按控制臺可用模型填寫"
export CODEX_PROFILE="stan**rd"

printf '*ase **L: %s\n' "$CODEX_*ASE_**L"
printf 'Profile: %s\n' "$CODEX_PROFILE"

還要注意路徑差異。Windows 路徑和 WSL 路徑不是同一種寫法，任務提示里如果要求 Codex 讀取文件，最好使用當前環境內的真實路徑，不要把 D:\project 和 /mnt/d/project 混寫。路徑一旦混亂，模型輸出會看起來像權限問題，其實只是文件位置不一致。

• WSL 按獨立環境維護變量。
• 提示詞里的路徑要使用 WSL 可訪問路徑。
• 不要假設 Windows 變量會穩定傳入 WSL。

六、Docker 環境：把配置注入容器，不要烘進鏡像

Docker 的核心原則是鏡像可復用，密鑰不進鏡像。不要把 CODEX_API_KEY 寫進 Dockerfile，也不要在構建階段把真實憑證作為 ARG 烘進去。鏡像一旦被推送、緩存或共享，里面的敏感信息就很難徹底追回。

更合理的方式，是運行容器時通過環境變量或 Secret 注入。開發環境可以使用本地 env 文件，但 env 文件必須加入忽略列表；生產或 CI 環境應使用平臺提供的 Secret 管理功能。

docker run --rm \
  -e CODEX_*ASE_**L="https://www.lnsns.com/" \
  -e CODEX_API_KEY="$CODEX_API_KEY" \
  -e CODEX_MODEL="$CODEX_MODEL" \
  -e CODEX_PROFILE="ci" \
  your-codex-i**ge:latest

容器里還要處理網絡和證書問題。宿主機能訪問，不代表容器能訪問；本機**能用，不代表容器自動繼承。遇到 timeout 時，不要立刻換 Key，先在容器內部做最小網絡測試，再檢查變量是否傳入。

• Dockerfile 不**實 Key。
• env 文件不進倉庫。
• 容器內單獨驗證網絡、變量和 Codex 最小任務。

七、CI 環境：Secret 注入和任務開關要一起設計

CI 環境和本地最大的不同，是它會自動觸發。如果沒有開關和限制，錯誤配置可能在多個分支、多個任務里重復運行。Codex 接入 CI 時，應該把 Secret 注入、任務開關、觸發條件和失敗處理一起設計。

建議 CI 至少準備兩層判斷。第一層檢查 CODEX_ENA*LED，如果為 false，就跳過 Codex 任務；第二層檢查必須變量是否存在，如果缺失就直接失敗并輸出清晰提示。不要讓腳本在變量缺失時繼續請求，否則錯誤會變得更難看懂。

if ($env:CODEX_ENA*LED -eq "false") {
  Write-Host "Codex 任務已關閉，跳過本次檢查"
  e**t 0
}

$required = @("CODEX_*ASE_**L", "CODEX_API_KEY", "CODEX_MODEL")
foreach ($name in $required) {
  if (-not [Environment]::GetEnvironmentVaria*le($name)) {
    throw "缺少環境變量：$name"
  }
}

Write-Host "環境變量檢查通過，開始執行最小 Codex 任務"

• CI Key 獨立管理，不復用個人 Key。
• CI 任務必須有快速停用開關。
• 失敗日志只輸出摘要，不打印完整敏感變量。

八、用 CC Switch 做本地切換：配置卡要和環境對應

當團隊同時使用 Windows、WSL 和容器時，CC Switch 的配置卡也要跟著場景拆分。不要只有一張“默認配置”，否則成員會在不同環境里反復覆蓋字段。建議至少準備本地開發、文檔任務、CI 預檢、備用路線幾類配置卡。

配置卡名稱要包含環境和用途，例如 Lingneng-Windows-Dev、Lingneng-WSL-Do**、Lingneng-Docker-****、Lingneng-CI-Preflight。備注里寫清楚變量來源、是否允許寫入、適用目錄和最后驗證日期。

配置卡備注示例

環境：WSL
用途：接口文檔草稿
入口：來自靈能API控制臺
變量：CODEX_*ASE_**L / CODEX_API_KEY / CODEX_MODEL
權限：只讀項目文件，輸出到 drafts/
驗證：2026-09-04 已通過最小任務
限制：不得自動覆蓋正式文檔

• 配置卡按環境和用途命名。
• 備注寫清楚權限邊界。
• 每張卡都要有最后驗證日期。

九、最小測試矩陣：每個環境都跑同一套樣本

多環境接入最怕“只在我的機器上測試過”。建議準備一套固定的最小測試矩陣，讓 Windows、WSL、Docker 和 CI 都跑同一個樣本。測試內容不要復雜，目標是確認變量、網絡、模型和輸出格式，而不是驗證業務邏輯。

測試樣本可以是一份很小的 Markdown 文件，里面包含項目目錄、一個示例接口和一段日志。讓 Codex 輸出固定三部分：環境判斷、內容摘要、待確認事項。這樣每個環境的結果可以橫向比較，一旦某處失敗，很快能定位差異。

測試矩陣

Windows PowerShell：讀取 sample/codex-env-check.md
WSL *ash：讀取 sample/codex-env-check.md
Docker：掛載 sample 目錄后讀取同一文件
CI：拉取倉庫后讀取同一文件

統一輸出：
1. 當前環境變量是否齊全
2. 樣本文件摘要
3. 需要人工確認的風險點

• 測試樣本固定，結果才可比較。
• 測試先只讀，不寫正式文件。
• 每個環境都記錄成功時間和配置卡。

十、團隊文檔怎么寫：把差異寫清楚，而不是寫成一鍋配置

多環境接入文檔最容易寫成一長串命令，讀者看完仍然不知道自己該選哪一段。更好的結構，是先給統一變量表，再分環境寫注入方式，最后給排查順序。這樣新成員可以先理解共同點，再按自己的環境操作。

文檔里還要明確哪些內容不應該出現：真實 Key、完整請求頭、包含密鑰的終端截圖、未打碼的 CI 日志、個人賬號敏感信息。教程越詳細，越要注意不要把敏感信息也詳細寫出來。

文檔結構建議

1. 統一入口和負責人
2. 統一變量表
3. Windows 配置方式
4. WSL 配置方式
5. Docker 注入方式
6. CI Secret 注入方式
7. CC Switch 配置卡命名
8. 最小測試矩陣
9. 常見錯誤和排查順序
10. 禁止寫入文檔的敏感內容

• 先寫共同規則，再寫環境差異。
• 命令示例只放占位符，不放真實 Key。
• 排查順序要寫在文檔末尾，方便出錯時快速定位。

十一、常見錯誤：不要把所有失敗都歸因給模型

多環境下的失敗，很多時候和模型本身沒有關系。Windows 老窗口沒讀取新變量，WSL 路徑寫錯，Docker 沒傳入 env，CI Secret 名稱拼錯，都會讓請求失敗。排查時先看環境，再看接入，再看模型，順序不能反。

排查順序

1. 當前環境是否讀取到 CODEX_*ASE_**L
2. 當前環境是否讀取到 CODEX_MODEL
3. API Key 是否存在且沒有被截斷
4. *ase **L 是否來自當前控制臺說明
5. 當前環境是否能訪問外部網絡
6. Codex 最小任務是否能返回
7. 再判斷模型權限、上下文長度和輸出格式問題

如果同一套變量在 Windows 成功、WSL 失敗，優先查 WSL 的變量和路徑；如果本地成功、Docker 失敗，優先查容器 env 注入和網絡；如果本地成功、CI 失敗，優先查 Secret 名稱、分支權限和任務觸發條件。這樣排查會比盲目改提示詞快得多。

• 先查變量，再查網絡，再查模型。
• 不同環境的失敗要分別記錄。
• 不要用更換模型掩蓋基礎配置錯誤。

十二、遷移和回滾：新環境不要一次替換舊環境

當團隊準備從個人本地配置遷移到統一多環境配置時，不要一次性替換所有任務。更穩的做法是并行觀察一小段時間：舊配置繼續承擔主要工作，新配置先跑只讀測試和低風險任務。等 Windows、WSL、Docker、CI 都通過最小測試后，再逐步切換。

回滾也要提前設計。比如 CI 中保留 CODEX_ENA*LED 開關，CC Switch 中保留上一版配置卡，團隊文檔中記錄舊變量名和新變量名的映射。這樣如果新環境出現問題，可以快速恢復到上一條可用路線，而不是在故障中臨時拼配置。

遷移節奏

第一階段：本地 Windows 和 WSL 跑最小測試
第二階段：Docker 跑固定樣本測試
第三階段：CI 跑只讀預檢任務
**階段：低風險任務切到新配置
第五階段：文檔任務和發布摘要切換
第六階段：舊配置停用并記錄歸檔

• 遷移先只讀，后寫入。
• 回滾開關要在上線前準備。
• 舊配置停用前，要確認沒有任務仍在引用。

? 十三、收尾：多環境跑通后，Codex 才能成為團隊基礎能力

Codex 接入 API中轉站 的多環境方案，本質上是在解決團隊協作里的可復制問題。一臺機器跑通不難，難的是 Windows、WSL、Docker、CI 都能按同一套規則運行，新成員照文檔也能復現，出錯時還能快速知道該查哪里。

落地順序建議是：先通過靈能API確認統一入口，再建立統一變量表，然后分別處理 Windows、WSL、Docker 和 CI 的注入方式，接著用 CC Switch 固化配置卡，最后用測試矩陣和回滾開關把流程變成可維護資產。

當這些基礎工作完成后，團隊再把 Codex 用于代碼**、文檔生成、日志分析和發布準備，就不會被環境差異反復打斷。配置清楚、變量統一、測試固定、排查有序，才是長期穩定使用的關鍵。

• 多環境接入先統一變量，再處理差異。
• 每個環境都要跑同一套最小測試。
• 遷移要可回滾，配置要可追蹤。