---
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)
