AI 程式設計教程中文版
官方教程中文版雲端與遠端環境

雲端與遠端環境

基於官方 Codex 教程,幫新手分清 Cloud、聯網許可權和遠端開發環境各自解決什麼問題。

這一組不是在講“怎麼讓 Codex 變強”,而是在講 Codex 到底在哪裡執行、能不能聯網、能不能碰你的真實開發環境。

執行環境決定 Codex 能看到什麼;聯網許可權決定它能訪問什麼外部站點;遠端開發決定命令在哪臺機器上執行。

三種問題

flowchart LR
    Task["Codex task"] --> Runtime["where it runs"]
    Task --> Network["what it can access"]
    Task --> Remote["where commands execute"]

想讓 Codex 在雲端隔離環境裡做長任務,看 Cloud runtime。你要關心依賴安裝、儲存庫準備、環境變數和任務能否復現。

想控制 Codex 能不能訪問外網,看 Network permissions。你要關心 setup 階段和 agent 階段的域名白名單,不要為了省事直接全放開。

想在遠端開發機上使用本地互動體驗,看 Remote development。你要關心程式碼、憑據和命令到底在哪臺機器上執行。

怎麼選

剛開始學 Codex,先用本地 CLI 或 IDE。等你已經知道 Codex 會改哪些檔案、會跑哪些命令,再進入雲端或遠端環境。

任務耗時長、依賴複雜、適合非同步處理,用 Codex Cloud。它適合“交給 Codex 跑一段時間,稍後看結果”的任務。

任務需要訪問公司內網、私有服務、本機金鑰或特定機器環境,用遠端開發機。重點不是“雲”,而是執行環境和許可權邊界。

任務需要下載依賴、查官方文件或訪問 API,單獨配置聯網許可權。聯網不是預設越大越好,應該按任務需要逐步放開。

三者邊界表

能力解決的問題預設風險
Cloud runtime在隔離容器裡 clone repo、安裝依賴、執行長任務併產出 diff環境不可復現、setup script 缺依賴、secrets 誤用。
Network permissions控制 agent 階段是否能訪問外部網路、哪些域名和 HTTP method 可用prompt injection、程式碼或 secrets 外洩、下載不可信依賴。
Remote development透過 SSH 把 Codex app/本地體驗連線到遠端主機專案遠端賬號許可權過大、PATH 不一致、誤把生產環境當開發環境。

官方 Cloud environments 文件裡,雲端任務的順序是:建立 container、checkout repo、執行 setup script、應用 internet access 設定、agent 迴圈執行命令和編輯檔案、最後展示 answer 和 diff。這個順序決定了排障方法:先查 repo/branch,再查 setup,再查聯網,再查 agent 階段日誌。

環境變數和 secrets 的區別

Cloud environments 裡有兩個容易混淆的配置:

  • Environment variables:整個 task 期間可用,包括 setup scripts 和 agent phase。
  • Secrets:加密儲存,只在 setup scripts 中解密可用;出於安全原因,agent phase 開始前會移除。

如果某個 token 只用於安裝私有依賴,應該放 secrets,而不是讓 agent phase 長期持有。需要 agent 執行期間訪問的變數才放 environment variables,並且要確認任務確實需要。

聯網許可權最小化

Agent phase 預設不聯網。需要開啟時先選最小許可權:

  1. 優先 off。
  2. 必須下載或查資料時,選擇 allowlist。
  3. HTTP method 優先限制到 GETHEADOPTIONS
  4. 只有非常明確的隔離任務才考慮 unrestricted。

不要把“setup 能聯網”和“agent 能聯網”混為一談。setup 階段聯網是為了安裝依賴;agent 階段聯網會讓模型讀到外部內容,也會引入 prompt injection 和資料外洩風險。

常見坑

  • 以為 Cloud 就等於能聯網。
  • 以為遠端開發只是換個終端。
  • 把安裝依賴和 agent 自主聯網混在一起。
  • 沒有記錄環境變數和 secrets。
  • 直接開放所有域名。
  • 任務失敗時不知道查本地、Cloud 還是遠端主機。

學習順序

  1. 讀 Cloud runtime,理解雲端任務為什麼需要可復現環境。
  2. 讀 Network permissions,理解“讓 Codex 聯網”是在做許可權設計。
  3. 讀 Remote development,理解程式碼和憑據在遠端機器上時,執行邊界在遠端主機。

讀完後應能回答

  • 任務應該在本地、Cloud,還是遠端開發機上跑?
  • Codex 需要哪些依賴、環境變數和憑據?
  • 哪些外部域名必須開放,哪些不該開放?
  • 命令失敗時該查本地機器、Cloud 環境,還是遠端主機?
  • 任務完成後,如何確認改動、日誌和敏感資訊沒有越界?
  • 如果 Cloud setup 成功但 agent 失敗,下一步該查 agent phase 網路、許可權還是儲存庫說明?
  • 如果遠端連線失敗,是否已經在遠端 login shell 下確認 codexPATH

配套閱讀

官方資料

本頁目錄