---
title: "遷移到 Codex"
description: "說明如何用 Codex import flow 遷移其他 agent 的 instructions、configuration、skills、MCP servers 和 sessions。"
verifiedAt: "2026-05-05"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

Codex 提供 import flow，可以把另一個 agent 的 instructions、configuration、skills、MCP servers、hooks、subagents 和 recent sessions 帶入 Codex。

Codex 會直接遷移它能處理的部分；剩餘內容則可以開啟 follow-up thread，繼續協助遷移。

官方頁面：[https://developers.openai.com/codex/migrate](https://developers.openai.com/codex/migrate)

<Cards>
  <Card title="Migrate to Codex" href="https://developers.openai.com/codex/migrate">
    官方 import flow 和遷移後複核清單。
  </Card>
  <Card title="Config reference" href="https://developers.openai.com/codex/config-reference">
    檢查匯入後的 `config.toml`。
  </Card>
  <Card title="Rules" href="https://developers.openai.com/codex/rules">
    把 instruction files 收斂到 Codex 可讀取的規則體系。
  </Card>
</Cards>

匯入流程截圖：

- light mode：[https://developers.openai.com/images/codex/migrate/import-flow-light.png](https://developers.openai.com/images/codex/migrate/import-flow-light.png)
- dark mode：[https://developers.openai.com/images/codex/migrate/import-flow-dark.png](https://developers.openai.com/images/codex/migrate/import-flow-dark.png)

## Start the Migration

1. 在 Codex app 中開啟 **Settings**。
2. 在 **General** page 中找到 **Import other agent setup**。
3. 選擇 **Import** 或 **Import again**。
4. review Codex 找到的內容，選擇要帶入的 items，然後選擇 **Import**。
5. import 完成後，如果想檢查結果，選擇 **View imported files**。

## How Migration Works

Codex 會同時檢查 user-level setup 和當前 project。

user-level setup 來自你機器上的 files；project-level setup 來自你當前開啟的 repository 中的 files。

`import` 時，Codex 會：

1. 檢測它能找到的 setup。
2. import 已選擇且能直接 migrate 的 items。
3. import 完成後再次檢查。
4. 如果仍有內容需要 follow-up work，則提供在 new thread 中繼續 migration 的選項。

## What Codex Can Import

| Detected setup | Codex destination |
|---|---|
| Instruction files | [`AGENTS.md`](https://developers.openai.com/codex/rules) |
| `settings.json` | [`config.toml`](https://developers.openai.com/codex/config-reference) |
| Skills | [Codex skills](https://developers.openai.com/codex/skills) |
| Recent sessions from the last 30 days | Codex threads and projects |
| MCP server configuration | [Codex MCP configuration](https://developers.openai.com/codex/mcp) |
| Hooks | [Codex hooks](https://developers.openai.com/codex/hooks) |
| Slash commands | [Codex skills](https://developers.openai.com/codex/skills) |
| Subagents | [Codex agents](https://developers.openai.com/codex/subagents) |

## Finish Remaining Setup in a New Thread

有些 detected setup 沒有 clean one-to-one mapping 可以直接進入 Codex。

對於這類 items，Codex 可以開啟 new thread，並使用 [`migrate-to-codex`](https://github.com/openai/skills/tree/main/skills/.curated/migrate-to-codex) skill，協助完成剩餘 migration。

發生這種情況時，Codex 會展示 remaining setup，並提供 **Continue in Codex**。

additional setup 截圖：

- light mode：[https://developers.openai.com/images/codex/migrate/additional-setup-light.png](https://developers.openai.com/images/codex/migrate/additional-setup-light.png)
- dark mode：[https://developers.openai.com/images/codex/migrate/additional-setup-dark.png](https://developers.openai.com/images/codex/migrate/additional-setup-dark.png)

如果繼續，Codex 會開啟 new thread，並把 remaining work 預先填好。

這個 thread 會把 user-level setup 和 project-level setup 分開，讓你看清每個 remaining item 應該放在哪裡。

follow-up migration task 截圖：

- light mode：[https://developers.openai.com/images/codex/migrate/continue-with-codex-light.png](https://developers.openai.com/images/codex/migrate/continue-with-codex-light.png)
- dark mode：[https://developers.openai.com/images/codex/migrate/continue-with-codex-dark.png](https://developers.openai.com/images/codex/migrate/continue-with-codex-dark.png)

## 遷移前先做盤點

不要把 import 當成“點一下就切換完”。商業專案遷移前先列清：

| 專案 | 要確認什麼 |
|---|---|
| Instructions | 哪些是全域性偏好，哪些是專案規則 |
| Config | 模型、審批、沙箱、網路、檔案許可權是否適合 Codex |
| Skills | 哪些只讀，哪些會寫入，哪些依賴外部工具 |
| MCP servers | token、headers、transport、tool allowlist 是否安全 |
| Hooks | 是否會改變 Codex 行為或寫入檔案 |
| Subagents | 是否真的需要遷移為 Codex subagents |
| Sessions | 最近 30 天會話是否有繼續價值 |

匯入流程會區分 user-level setup 和 project-level setup。你要做的是確認遷移目標，而不是把舊工具裡的所有東西照搬到 Codex。

## What to Review After Import

依賴 migrated setup 前，請 review 匯入結果，尤其是：

- imported skills 和 agents 中的 tool restrictions 或 permissions。
- 使用 custom authentication、headers、environment variables 或 transports 的 MCP server settings。
- 在 Codex 中 behavior 可能不同的 hooks。
- plugins、marketplaces，或其他需要 manual follow-up 的 remaining setup。
- 依賴 arguments、shell interpolation 或 file-path 佔位引數的 prompt templates 或 command-style prompts。

## After You Switch

`import` 完成後，開啟一個已 migrated project，從那裡繼續。

如果你剛開始使用 Codex，見 [quickstart](https://developers.openai.com/codex/quickstart)，完成其餘 setup flow。

## 匯入後驗證

遷移完成後，建議用一個低風險專案驗證：

1. 開啟已遷移專案。
2. 讓 Codex 說明它讀取到了哪些規則和配置。
3. 跑一個只讀任務，例如“解釋這個專案結構”。
4. 跑一個小改動任務，並確認審批、沙箱和測試命令是否符合預期。
5. 檢查 MCP server 是否只暴露必要工具。
6. 檢查 imported skills 是否仍然有清楚的使用邊界。

如果行為異常，先修規則和配置，不要馬上投入生產任務。遷移成功的標準不是“檔案匯入了”，而是 Codex 在真實專案裡按預期讀取規則、執行命令、請求審批和生成可審查 diff。

## 官方資料

- [OpenAI Codex migrate guide](https://developers.openai.com/codex/migrate)
- [Codex quickstart](https://developers.openai.com/codex/quickstart)
- [Codex config reference](https://developers.openai.com/codex/config-reference)
- [Codex rules and AGENTS.md](https://developers.openai.com/codex/rules)
- [Codex MCP](https://developers.openai.com/codex/mcp)
