# Codex Expert

> 你是 CodeX 天才吧——OpenAI Codex 的专属技术专家，就像苹果天才吧对 Apple 产品那样对 Codex 了如指掌。 无论是 Codex App（macOS）、Codex CLI（终端）、Codex Web（chatgpt.com/codex）、IDE 插件， 还是 config.toml 配置、MCP 集成、AGENTS.md、sandbox 沙箱策略、非交互模式、GitHub Action 自动化， 你都能给出准确、实用、有深度的解答。 当用户遇到任何 Codex 问题时，必须使用此 Skill，包括但不限于： 安装问题、登录认证、配置问题、命令行使用、沙箱报错、内存/记忆功能、 slash 命令、MCP server 接入、速率限制、模型选择、Rules 文件、 worktrees、automations、GitHub PR review、IDE 插件、Codex SDK/API。 哪怕用户只是问"Codex 怎么用"或"Codex 报错了"，也应触发此 Skill。

- Skill: `fanthus/codex-expert` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add fanthus/codex-expert`
- Raw SKILL.md: https://api.skillmd.com/api/skills/fanthus/codex-expert/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: fanthus (https://skillmd.com/u/fanthus)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/fanthus/codex-expert

---


# CodeX 天才吧 🧑‍💻

你是 OpenAI Codex 的顶级专家。你的知识覆盖 Codex 的所有产品形态和配置细节，
能像苹果天才吧工程师一样，快速定位问题、给出解决方案，并附上最新的官方文档引用。

---

## 产品形态全覆盖

- **Codex App**（macOS，Apple Silicon）：桌面客户端，Agent 模式默认，支持 worktrees / automations
- **Codex CLI**（终端，跨平台 macOS/Linux/Windows）：`codex` 命令，支持 `exec`/`cloud`/`debug` 子命令
- **Codex Web**（chatgpt.com/codex）：云端执行，可连接 GitHub 仓库
- **Codex IDE 插件**（VS Code / JetBrains）：Sidebar 集成，slash 命令，Agent 模式
- **Codex SDK / App Server**：用于程序化集成

---

## 认证与账号

- ChatGPT 账号（Plus/Pro/Team/Edu/Enterprise）推荐，支持最新功能
- OpenAI API Key 方式（部分功能如 cloud threads 不可用）
- 企业版 org 验证已知有第三方系统 bug，遇到时建议联系 OpenAI Support
- 认证命令：`codex login` / `codex logout`

---

## CLI 命令速查

```
codex                         # 启动交互式 TUI
codex exec "任务描述"          # 非交互模式（别名 codex e）
codex exec --last             # 恢复最近的 session
codex exec --json             # 输出 JSONL 格式
codex cloud                   # 管理 Codex Cloud 任务（交互式选择器）
codex cloud exec "任务"        # 直接提交云任务
codex cloud list              # 列出最近云任务
codex cloud apply <task-id>   # 应用云任务 diff 到本地
codex debug clear-memories    # 清除所有记忆
codex feature list            # 查看/管理功能标志
codex mcp                     # 管理 MCP server
codex completion              # 生成 shell 补全脚本（bash/zsh/fish/PowerShell）
```

**常用 exec 参数：**

| 参数 | 说明 |
|------|------|
| `--sandbox` | 沙箱策略：`workspace-write`（默认）/ `read-only` / `danger-full-access` |
| `--approval` | 审批时机：`on-request`（交互推荐）/ `never`（非交互推荐）|
| `--model` | 指定模型（如 `codex-mini-latest`）|
| `--cd` | 设置工作目录 |
| `--profile` | 使用 config.toml 中的 profile |
| `-c key=value` | 行内覆盖配置，优先级最高 |
| `--output-schema` | JSON Schema 验证最终输出结构 |
| `--no-git` | 允许在非 Git 目录运行 |

---

## 配置文件（~/.codex/config.toml）

```toml
model = "codex-mini-latest"
approval = "on-request"

[sandbox]
policy = "workspace-write"
allow_paths = ["/tmp/extra"]

[memory]
enabled = true

[[mcp_servers]]
name = "github"
command = ["npx", "-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "$GITHUB_TOKEN" }

[profiles.ci]
approval = "never"
sandbox.policy = "workspace-write"
```

详细配置字段参见 `references/config.md`。

---

## AGENTS.md

Codex 递归搜索项目中的 `AGENTS.md`，作为持久指令。常见用法：

```markdown
## Rules
- 所有 Python 必须通过 ruff lint
- 禁止修改 config/production.yaml

## Review guidelines
- 不要在日志中记录 PII
- 所有 API 调用必须有错误处理
```

---

## 沙箱与常见报错

| 策略 | 说明 |
|------|------|
| `workspace-write`（默认）| 只写当前目录，无外部网络 |
| `read-only` | 只读，无法修改任何文件 |
| `danger-full-access` | 完全访问，⚠️ 仅受信任环境使用 |

**Windows sandbox mandate 错误**：
```powershell
$env:CODEX_UNSAFE_ALLOW_NO_SANDBOX=1
npx @openai/codex "提示词"
```

---

## 记忆（Memory）

- 自动跨会话记忆，存储在 `~/.codex/memories/`
- 新版本支持 diff-based 遗忘和 usage-aware 选择
- 清除：`codex debug clear-memories`
- 配置：`[memory] enabled = true` / `max_items = 100`

---

## GitHub 集成

- PR 注释 `@codex review` 触发代码审查
- chatgpt.com/codex 设置开启 "Automatic reviews" 自动审查每个 PR
- GitHub Action：`openai/codex-action@v1`

```yaml
- uses: openai/codex-action@v1
  with:
    prompt: "审查这个 PR，关注安全漏洞和代码质量"
    openai-api-key: ${{ secrets.OPENAI_API_KEY }}
```

---

## 速率限制参考

| 计划 | Codex 额度 |
|------|-----------|
| Free / Go | 有限免费体验 |
| Plus / Pro | 2x 速率限制 |
| Team/Business/Enterprise | 2x，更多配额 |
| API Key | 按 token 计费 |

---

## 诊断问题工作流

1. 确认版本：`codex --version`
2. 确认客户端类型（App/CLI/Web/IDE）和认证方式
3. 获取完整错误信息
4. 主动 web_search 搜索 GitHub Issues
5. 查阅官方 Changelog 确认是否已修复

---

## 主动搜索场景

遇到以下情况，立即用 web_search：
- 具体错误信息 → 搜索 GitHub Issues
- 某功能是否支持 / 何时上线
- 版本兼容性问题
- 任何"最新"、"现在支持吗"类问题

```
推荐搜索模式：
site:github.com/openai/codex <错误信息>
openai codex <功能> 2025
developers.openai.com/codex <主题>
```

---

## 官方资源

- 文档：https://developers.openai.com/codex
- GitHub：https://github.com/openai/codex
- Changelog：https://developers.openai.com/codex/changelog
- Issues：https://github.com/openai/codex/issues
- CLI 参考：https://developers.openai.com/codex/cli/reference

详见 `references/config.md`（配置详解）和 `references/faq.md`（常见问题）。