🆙 Codex 0.46.0 高级入门教程

核心概念深度解析

1. Approval Policy：信任的艺术

Codex 不是野生 AI，它懂得问你要权限。配置文件里有四种策略：

approval_policy = "untrusted" # 默认，只在运行"不受信任"的命令时询问


策略	含义	适用场景
`untrusted`	只在运行危险命令时询问	日常开发（推荐）
`on-failure`	命令失败后询问是否要解除沙箱重试	调试阶段
`on-request`	让模型决定什么时候需要升级权限	你很懒的时候
`never`	全自动，绝不打扰	CI/CD 或你胆子够大的时候

> 幽默一刻：never 模式就像给 AI 发了张信用卡，它会很高兴，你的服务器可能会哭。

2. Sandbox：沙箱不是猫砂盆

Codex 用操作系统级别的沙箱来执行命令，防止它”不小心”把你的硬盘格式化了。

sandbox_mode = "read-only" # 默认：只读模式

三种模式对比：


模式	读文件	写文件	访问网络	适用场景
`read-only`	:check_mark_button:	:cross_mark:	:cross_mark:	阅读和分析代码
`workspace-write`	:check_mark_button:	:check_mark_button:（当前目录）	:cross_mark:*	正常开发
`danger-full-access`	:check_mark_button:	:check_mark_button:（整个文件系统）	:check_mark_button:	Docker 容器里随便浪

*可以通过配置开启网络访问

高级沙箱配置：

sandbox_mode = "workspace-write"

[sandbox_workspace_write]
# 允许写入额外的目录（比如 Python 虚拟环境）
writable_roots = ["/Users/你/.pyenv/shims"]
# 开启网络访问（慎用！）
network_access = true
# 排除 /tmp 目录（默认是可写的）
exclude_slash_tmp = false

> 安全提示：macOS 和 Linux 上，.git/ 文件夹默认是只读的，防止 AI 搞乱你的 Git 历史。

3. Model：选择你的战斗伙伴

model = "gpt-5-codex" # 默认模型

常用模型推荐：

o3 - 推理能力超强，适合复杂任务（但慢）
gpt-5-codex - 专为编程优化，速度和质量平衡
gpt-5 - 通用大杀器
gpt-4o - 老而弥坚

调整推理深度：

model = "o3"
model_reasoning_effort = "high" # minimal | low | medium | high
model_reasoning_summary = "detailed" # auto | concise | detailed | none

> 彩蛋：model_reasoning_effort = "high" 就像让 AI 喝了三杯浓缩咖啡，它会想得更深，但也更费钱。

MCP：让 Codex 连接万物

MCP（Model Context Protocol） 是 Codex 0.46.0 的杀手级特性，它能让 AI 访问外部工具、服务和数据源。

MCP 是什么？

把 MCP 想象成”AI 的 USB 接口”：

Codex = 电脑主机
MCP Server = 外接硬盘、打印机、摄像头…

配置 MCP 服务器：两种方式

方式 1：STDIO（本地进程）

[mcp_servers.docs]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/docs"]
env = { API_KEY = "sk-xxxxx" }

实战示例：连接 Context7（开发文档神器）

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7"]
env = { UPSTASH_API_KEY = "your_key_here" }

方式 2：Streamable HTTP（0.46.0 新特性！）

这是 0.46.0 的重大更新，可以连接远程 MCP 服务器。

# 首先启用实验性 RMCP 客户端
experimental_use_rmcp_client = true

[mcp_servers.figma]
url = "http://127.0.0.1:3845/mcp"
# 可选：用环境变量提供 Bearer Token
bearer_token_env_var = "FIGMA_TOKEN"

OAuth 登录支持：

# 登录到支持 OAuth 的 MCP 服务器
codex mcp login figma

# 登出
codex mcp logout figma


服务器	用途	配置示例
Context7	访问最新开发文档	`npx @upstash/context7`
Figma	读取和操作 Figma 设计文件	Streamable HTTP + OAuth
Playwright	自动化浏览器测试	`npx @playwright/mcp`
Chrome DevTools	调试 Chrome 浏览器	STDIO 启动
GitHub	管理 PR、Issues（比 git 强大）	`npx @github/github-mcp-server`
Sentry	访问错误日志	Streamable HTTP

MCP CLI 命令速查

# 添加 MCP 服务器
codex mcp add docs -- npx -y docs-server --port 4000

# 列出所有服务器
codex mcp list

# 查看单个服务器详情（JSON 格式）
codex mcp get docs --json

# 移除服务器
codex mcp remove docs

# OAuth 登录/登出
codex mcp login figma
codex mcp logout figma

高级 MCP 配置

[mcp_servers.my_server]
command = "my-server"
args = ["--verbose"]
# 可选：覆盖默认超时时间
startup_timeout_sec = 20 # 默认 10 秒
tool_timeout_sec = 120 # 默认 60 秒
# 可选：临时禁用而不删除配置
enabled = false

> 调试技巧：如果 MCP 服务器启动失败，看看 ~/.codex/log/codex-tui.log 的日志。

0.46.0 新特性：Streamable HTTP

为什么这是大事？

以前 MCP 只能连接本地进程（STDIO），现在可以连接任何 HTTP 服务器了！这意味着：

:check_mark_button: 可以连接公司内网的 API
:check_mark_button: 可以连接云端服务（如 Linear、Figma）
:check_mark_button: 支持 OAuth 2.0 登录
:check_mark_button: 可以用 Bearer Token 认证

配置示例

1. 最简单的 HTTP MCP

experimental_use_rmcp_client = true

[mcp_servers.linear]
url = "https://mcp.linear.app/mcp"

2. 带 Bearer Token 认证

experimental_use_rmcp_client = true

[mcp_servers.internal_api]
url = "https://api.mycompany.com/mcp"
bearer_token_env_var = "INTERNAL_API_TOKEN"

在 shell 中设置环境变量：

export INTERNAL_API_TOKEN="your_secret_token"
codex

3. OAuth 2.0 登录

experimental_use_rmcp_client = true

[mcp_servers.figma]
url = "https://mcp.figma.com"
# 注意：不需要 bearer_token_env_var

然后运行：

codex mcp login figma
# 会打开浏览器完成 OAuth 登录

排查 Streamable HTTP 问题

如果遇到问题，试试这些步骤：

检查标志是否启用

grep experimental_use_rmcp_client ~/.codex/config.toml
# 应该看到：experimental_use_rmcp_client = true

测试连接性

curl -v https://mcp.linear.app/mcp
# 确保服务器可达

查看详细日志

RUST_LOG=debug codex
tail -f ~/.codex/log/codex-tui.log

> 已知问题（见 #4707）：Windows 上某些 MCP 服务器可能报 missing field command 错误，团队正在修复中。

高级配置技巧

1. Profiles：一键切换配置

# 默认配置
model = "gpt-5-codex"
approval_policy = "untrusted"

# Profile 1：专注模式（用 o3，高推理）
[profiles.focus]
model = "o3"
model_reasoning_effort = "high"
approval_policy = "never"
sandbox_mode = "workspace-write"

# Profile 2：安全模式（只读 + 必须审批）
[profiles.safe]
model = "gpt-4o"
approval_policy = "untrusted"
sandbox_mode = "read-only"

# Profile 3：快速原型（全自动）
[profiles.prototype]
model = "gpt-5-codex"
approval_policy = "never"
sandbox_mode = "workspace-write"

使用方式：

codex --profile focus "优化这个算法"
codex --profile safe "帮我审查安全漏洞"
codex --profile prototype "创建一个 TODO 应用"

2. 自定义模型提供商

示例 1：用本地 Ollama

model = "mistral"
model_provider = "ollama"

[model_providers.ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"
wire_api = "chat"

示例 2：Azure OpenAI

model = "gpt-4o"
model_provider = "azure"

[model_providers.azure]
name = "Azure"
base_url = "https://YOUR_PROJECT.openai.azure.com/openai"
env_key = "AZURE_OPENAI_API_KEY"
query_params = { api-version = "2025-04-01-preview" }
wire_api = "responses"

示例 3：第三方 API（如 Mistral AI）

model = "mistral-large"
model_provider = "mistral"

[model_providers.mistral]
name = "Mistral"
base_url = "https://api.mistral.ai/v1"
env_key = "MISTRAL_API_KEY"
wire_api = "chat"
# 自定义 HTTP 头
http_headers = { "X-Custom-Header" = "value" }
# 从环境变量读取的头
env_http_headers = { "X-User-ID" = "MY_USER_ID" }

3. 网络调优（重要！）

每个模型提供商都可以单独配置网络参数：

[model_providers.openai]
name = "OpenAI"
base_url = "https://api.4allapi.com/v1"
env_key = "OPENAI_API_KEY"
# 网络调优
request_max_retries = 4 # 重试次数（默认 4）
stream_max_retries = 10 # 流断开重连次数（默认 5）
stream_idle_timeout_ms = 600000 # 空闲超时 10 分钟（默认 5 分钟）

> 使用场景：在网络不稳定的环境（如咖啡店 Wi-Fi），加大重试次数和超时时间。

4. Shell 环境变量管理

Codex 默认会继承你的完整环境变量，但有时候你想控制它：

[shell_environment_policy]
# 继承策略：all（全部） | core（核心变量） | none（清空）
inherit = "core" # 只继承 HOME, PATH, USER 等
# 排除敏感变量（支持通配符）
exclude = ["AWS_*", "AZURE_*", "*_SECRET"]
# 强制设置
set = { CI = "1", NODE_ENV = "test" }
# 白名单模式（如果设置了，只保留这些）
include_only = ["PATH", "HOME", "USER"]

实战案例：CI/CD 环境

[shell_environment_policy]
inherit = "none"
set = {
 PATH = "/usr/bin:/bin",
 CI = "true",
 NODE_ENV = "production"
}

5. AGENTS.md：给 AI 的小纸条

Codex 会自动读取三个地方的 AGENTS.md（按优先级合并）：

~/.codex/AGENTS.md - 全局个人偏好
项目根目录 AGENTS.md - 项目规范
当前目录 AGENTS.md - 局部指令

示例：~/.codex/AGENTS.md（个人风格）

# 我的编码风格

## 通用规则
- 使用 TypeScript 而不是 JavaScript
- 函数名用驼峰命名法
- 测试用 Jest，不要用其他框架

## Python 项目
- 用 Black 格式化
- 用 pytest 写测试
- 类型注解必须写全

## 禁止事项
- 不要自动安装依赖，先问我
- 不要修改 package.json 的版本号

示例：项目根目录 AGENTS.md（团队规范）

# 本项目指南

## 架构
- 后端：Django + PostgreSQL
- 前端：React + TailwindCSS
- API：RESTful，版本前缀 /api/v1/

## 代码审查检查点
- [ ] 所有 API 都有单元测试
- [ ] 数据库迁移文件已生成
- [ ] README 已更新

## 特殊约定
- 日期格式统一用 ISO 8601
- 错误码范围：4000-4999 客户端错误，5000-5999 服务器错误

> Pro Tip：可以配置 fallback 文件名，比如你公司用 CLAUDE.md： > > TOML > project_doc_fallback_filenames = ["CLAUDE.md", ".agentrules"] >

6. 通知系统：让 Codex 告诉你它干完了

方式 1：TUI 内置通知（简单）

[tui]
# 开启所有通知
notifications = true

# 或只开启特定类型
notifications = ["agent-turn-complete", "approval-requested"]

支持的终端：iTerm2、Ghostty、WezTerm（macOS Terminal 和 VS Code 终端不支持）。

方式 2：外部脚本通知（高级）

notify = ["python3", "/Users/你/.codex/notify.py"]

创建 notify.py：

#!/usr/bin/env python3
import json
import sys
import subprocess

notification = json.loads(sys.argv[1])

if notification["type"] == "agent-turn-complete":
 message = notification.get("last-assistant-message", "Task completed!")
 # macOS 通知
 subprocess.run([
 "osascript", "-e",
 f'display notification "{message}" with title "Codex"'
 ])
 # 或用 terminal-notifier
 # subprocess.run(["terminal-notifier", "-title", "Codex", "-message", message])

7. OpenTelemetry：记录一切

[otel]
environment = "production"
exporter = { otlp-http = {
 endpoint = "https://otel.mycompany.com/v1/logs",
 protocol = "binary",
 headers = { "x-api-key" = "${OTEL_TOKEN}" }
}}
log_user_prompt = false # 不记录用户输入（隐私保护）

会记录的事件：

codex.conversation_starts - 会话开始
codex.api_request - API 请求（含耗时）
codex.tool_decision - 工具使用决策（批准/拒绝）
codex.tool_result - 工具执行结果

自定义 API 配置深度指南

Codex 的强大之处在于它不仅支持 OpenAI，还可以连接几乎任何兼容的 API 提供商。本章节深入探讨各种自定义 API 场景。

1. 兼容 OpenAI API 的服务商

只要 API 遵循 OpenAI 的接口规范，就可以直接配置。

1.1 4All API（超低价格！）

Codex接入4All API

1.2 LM Studio（图形化本地模型）

model = "lmstudio-community/Meta-Llama-3-8B-Instruct-GGUF"
model_provider = "lmstudio"

[model_providers.lmstudio]
name = "LM Studio"
base_url = "http://localhost:1234/v1"
wire_api = "chat"

> 提示：在 LM Studio 中启用 API Server（Settings → Developer → Enable API Server）。

1.3 Anthropic Claude（通过代理）

Codex 默认不直接支持 Anthropic API，但可以通过转换代理：

model = "claude-3-5-sonnet-20241022"
model_provider = "anthropic-proxy"

[model_providers.anthropic-proxy]
name = "Anthropic Claude (via Proxy)"
base_url = "https://localhost:8080/v1" # 运行转换代理
env_key = "ANTHROPIC_API_KEY"
wire_api = "chat"

设置转换代理（使用 LiteLLM）：

pip install litellm[proxy]

# 启动代理
litellm --model claude-3-5-sonnet-20241022 --port 8080

2. 企业自建 API

2.1 内网 API（带自定义认证）

model = "company-gpt-4"
model_provider = "internal"

[model_providers.internal]
name = "Company Internal API"
base_url = "https://ai.company.internal/v1"
env_key = "COMPANY_API_KEY"
wire_api = "chat"

# 自定义 HTTP 头
http_headers = {
 "X-Department" = "engineering",
 "X-Cost-Center" = "ai-research"
}

# 从环境变量读取的头
env_http_headers = {
 "X-User-ID" = "EMPLOYEE_ID",
 "X-Session-Token" = "SSO_TOKEN"
}

# 网络调优（内网可能更稳定）
request_max_retries = 2
stream_idle_timeout_ms = 180000 # 3 分钟

设置环境变量：

export COMPANY_API_KEY="your_internal_key"
export EMPLOYEE_ID="E12345"
export SSO_TOKEN="sso_token_from_login"
codex

2.2 需要额外查询参数的 API

[model_providers.custom_with_params]
name = "Custom API with Query Params"
base_url = "https://api.example.com/inference"
env_key = "CUSTOM_API_KEY"
wire_api = "chat"

# 添加查询参数
query_params = {
 version = "2024-01",
 region = "us-east-1",
 tier = "premium"
}

生成的 URL：completions?version=2024-01&region=us-east-1&tier=premium

2.3 Azure OpenAI（完整配置）

model = "gpt-4o"
model_provider = "azure"

[model_providers.azure]
name = "Azure OpenAI Service"
base_url = "https://your-resource.openai.azure.com/openai"
env_key = "AZURE_OPENAI_API_KEY"
wire_api = "responses" # 或 "chat"

# Azure 必需的查询参数
query_params = { api-version = "2025-04-01-preview" }

# 可选：自定义部署名称映射
# Azure 中的部署名可能与模型名不同
http_headers = {
 "api-deployment-id" = "my-gpt4-deployment"
}

# 网络调优（Azure 在某些区域可能较慢）
request_max_retries = 5
stream_max_retries = 10
stream_idle_timeout_ms = 600000 # 10 分钟

环境变量设置：

export AZURE_OPENAI_API_KEY="your_azure_key"
codex --profile azure "任务描述"

3. 高级 API 调优

3.1 网络不稳定环境

[model_providers.unstable_network]
name = "API for Unstable Networks"
base_url = "https://api.example.com/v1"
env_key = "API_KEY"
wire_api = "chat"

# 激进的重试策略
request_max_retries = 10 # 最多重试 10 次
stream_max_retries = 15 # SSE 流重试 15 次
stream_idle_timeout_ms = 900000 # 15 分钟超时

# 可以配合 Profile 使用
[profiles.unstable]
model_provider = "unstable_network"
approval_policy = "never" # 避免超时时需要手动确认

3.2 代理配置

Codex 遵循系统代理设置，但也可以通过环境变量指定：

# HTTP 代理
export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="http://proxy.company.com:8080"

# SOCKS5 代理
export ALL_PROXY="socks5://localhost:1080"

# 不走代理的域名
export NO_PROXY="localhost,127.0.0.1,.internal.company.com"

codex

为特定 Profile 设置代理（通过 shell 脚本）：

#!/bin/bash
export HTTP_PROXY="http://corporate-proxy:8080"
export HTTPS_PROXY="http://corporate-proxy:8080"
exec codex --profile corporate "$@"

chmod +x ~/bin/codex-with-proxy.sh
codex-with-proxy.sh "任务描述"

4. 多提供商组合策略

4.1 成本优化配置

# 默认用便宜的模型
model = "gpt-4o-mini"
model_provider = "openai"

# Profile 1：日常任务（便宜快速）
[profiles.daily]
model = "gpt-4o-mini"
model_provider = "openai"

# Profile 2：复杂任务（贵但强大）
[profiles.complex]
model = "o3"
model_provider = "openai"
model_reasoning_effort = "high"

# Profile 3：本地免费（隐私敏感）
[profiles.local]
model = "llama3"
model_provider = "ollama"

# Profile 4：超快速（适合迭代）
[profiles.fast]
model = "llama3-70b-8192"
model_provider = "groq"

[model_providers.openai]
name = "OpenAI"
base_url = "https://api.4allapi.com/v1"
env_key = "OPENAI_API_KEY"

[model_providers.ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"

[model_providers.groq]
name = "Groq"
base_url = "https://api.groq.com/openai/v1"
env_key = "GROQ_API_KEY"

使用策略：

# 日常重构
codex --profile daily "重构这个函数"

# 复杂架构设计
codex --profile complex "设计一个高并发的消息队列系统"

# 隐私敏感代码审查
codex --profile local "审查这段包含密钥的代码"

# 快速原型迭代
codex --profile fast "快速生成 10 个测试用例"

4.2 故障转移配置

如果主 API 失败，手动切换到备用 API：

# 主 API
[profiles.main]
model = "gpt-5-codex"
model_provider = "openai-primary"

# 备用 API 1
[profiles.backup1]
model = "gpt-4o"
model_provider = "azure"

# 备用 API 2（本地）
[profiles.backup2]
model = "llama3"
model_provider = "ollama"

[model_providers.openai-primary]
name = "OpenAI Primary"
base_url = "https://api.4allapi.com/v1"
env_key = "OPENAI_API_KEY"
request_max_retries = 3

[model_providers.azure]
name = "Azure Backup"
base_url = "https://backup.openai.azure.com/openai"
env_key = "AZURE_OPENAI_API_KEY"
query_params = { api-version = "2025-04-01-preview" }

[model_providers.ollama]
name = "Local Ollama"
base_url = "http://localhost:11434/v1"

Shell 函数自动切换：

# 添加到 ~/.bashrc 或 ~/.zshrc
codex_with_fallback() {
 codex --profile main "$@" || \
 codex --profile backup1 "$@" || \
 codex --profile backup2 "$@"
}

5. 完整企业级配置示例

# 企业多云环境配置

# 默认配置
model = "gpt-5-codex"
model_provider = "openai"
approval_policy = "on-failure"
sandbox_mode = "workspace-write"

# ===== 模型提供商配置 =====

[model_providers.openai]
name = "OpenAI Production"
base_url = "https://api.4allapi.com/v1"
env_key = "OPENAI_API_KEY"
request_max_retries = 5
stream_max_retries = 10
stream_idle_timeout_ms = 300000

[model_providers.azure]
name = "Azure OpenAI"
base_url = "https://company.openai.azure.com/openai"
env_key = "AZURE_OPENAI_API_KEY"
query_params = { api-version = "2025-04-01-preview" }
wire_api = "responses"
request_max_retries = 5
stream_idle_timeout_ms = 600000

[model_providers.internal]
name = "Company Internal AI"
base_url = "https://ai-api.company.internal/v1"
env_key = "COMPANY_AI_KEY"
wire_api = "chat"
http_headers = {
 "X-Department" = "engineering",
 "X-Environment" = "production"
}
env_http_headers = {
 "X-Employee-ID" = "EMPLOYEE_ID"
}

[model_providers.ollama]
name = "Local Ollama (Offline)"
base_url = "http://localhost:11434/v1"
wire_api = "chat"

# ===== Profile 配置 =====

[profiles.prod]
model = "gpt-5-codex"
model_provider = "openai"
approval_policy = "untrusted"
sandbox_mode = "read-only"

[profiles.dev]
model = "gpt-4o"
model_provider = "azure"
approval_policy = "on-failure"
sandbox_mode = "workspace-write"

[profiles.review]
model = "o3"
model_provider = "openai"
model_reasoning_effort = "high"
approval_policy = "never"
sandbox_mode = "read-only"

[profiles.internal]
model = "company-gpt-4"
model_provider = "internal"
approval_policy = "never"
sandbox_mode = "workspace-write"

[profiles.offline]
model = "llama3"
model_provider = "ollama"
approval_policy = "never"
sandbox_mode = "workspace-write"

# ===== 安全配置 =====

[shell_environment_policy]
inherit = "core"
exclude = ["*_KEY", "*_TOKEN", "*_SECRET", "AWS_*", "AZURE_*"]
set = { CI = "false" }

# ===== MCP 服务器 =====

experimental_use_rmcp_client = true

[mcp_servers.company_docs]
url = "https://docs.company.internal/mcp"
bearer_token_env_var = "COMPANY_DOCS_TOKEN"
startup_timeout_sec = 20

[mcp_servers.sentry]
url = "https://sentry.io/api/mcp"
bearer_token_env_var = "SENTRY_TOKEN"

# ===== 其他配置 =====

[history]
persistence = "save-all"

[tui]
notifications = ["agent-turn-complete", "approval-requested"]

hide_agent_reasoning = false
show_raw_agent_reasoning = false

6. API 配置调试工具

6.1 测试 API 连接

# 测试 OpenAI API
curl https://api.4allapi.com/v1/models \
 -H "Authorization: Bearer $OPENAI_API_KEY"

# 测试 Azure OpenAI
curl "https://YOUR_RESOURCE.openai.azure.com/openai/deployments?api-version=2025-04-01-preview" \
 -H "api-key: $AZURE_OPENAI_API_KEY"

# 测试 Ollama
curl http://localhost:11434/api/tags

# 测试 Groq
curl https://api.groq.com/openai/v1/models \
 -H "Authorization: Bearer $GROQ_API_KEY"

6.2 验证 Codex 配置

# 查看当前配置
cat ~/.codex/config.toml

# 测试特定 profile
codex --profile test -c model=gpt-4o "echo hello" --sandbox read-only

# 查看详细日志
RUST_LOG=debug codex --profile test "测试任务" 2&gt;&amp;1 | tee debug.log

6.3 配置验证 Shell 脚本

#!/bin/bash
echo "🔍 Validating Codex Configuration..."

# 检查配置文件是否存在
if [ ! -f ~/.codex/config.toml ]; then
 echo "❌ config.toml not found"
 exit 1
fi

# 检查 OpenAI API Key
if [ -n "$OPENAI_API_KEY" ]; then
 echo "✅ OPENAI_API_KEY is set"
else
 echo "⚠️ OPENAI_API_KEY not set"
fi

# 检查 Ollama 是否运行
if curl -s http://localhost:11434/api/tags &gt; /dev/null; then
 echo "✅ Ollama is running"
else
 echo "⚠️ Ollama is not running"
fi

# 检查网络代理
if [ -n "$HTTP_PROXY" ]; then
 echo "✅ HTTP_PROXY: $HTTP_PROXY"
fi

echo "✅ Configuration validation complete"

7. 常见 API 配置错误排查


错误信息	可能原因	解决方法
`Connection refused`	API 服务未启动	检查 `base_url`，确认服务运行
`401 Unauthorized`	API Key 错误或过期	验证 `env_key` 对应的环境变量
`404 Not Found`	URL 路径错误	检查 `base_url`，某些 API 不需要 `/v1`
`Timeout`	网络慢或 API 响应慢	增大 `stream_idle_timeout_ms`
`Model not found`	模型名称错误	查看 API 文档确认正确的模型 ID
`Invalid API version`	Azure 缺少 `query_params`	添加 `query_params = { api-version = "..." }`
`SSL certificate verify failed`	自签名证书	使用代理或配置系统信任该证书
`Rate limit exceeded`	调用太频繁	增加 `request_max_retries`，或等待重置

自定义 Prompts 完全指南

Codex 提供两种主要的自定义方式来提升工作效率：

自定义斜杠命令（Custom Slash Commands）：快速可复用的提示词模板，存储在 ~/.codex/prompts/ 目录
AGENTS.md 配置文件：持久化的项目/目录级别的上下文和规范指南

本章将详细介绍这两种方式的使用方法和最佳实践。

第一部分：自定义斜杠命令（Custom Slash Commands）

什么是自定义斜杠命令？

自定义斜杠命令是 Codex 0.46.0 提供的强大功能，让你可以将常用的提示词保存为 Markdown 文件，然后通过斜杠菜单快速调用。

基本原理

存储位置：$CODEX_HOME/prompts/（默认为 ~/.codex/prompts/）
文件格式：只识别 .md 扩展名的 Markdown 文件
命令名称：文件名（去掉 .md）即为斜杠命令名
例如：review-pr.md → 使用 /review-pr 调用
参数支持：
$1 到 $9：位置参数（第 1-9 个参数）
$ARGUMENTS：所有参数用空格连接
$$：字面上的 $ 符号
引号支持：/cmd "arg with spaces" 将整个字符串作为一个参数

使用方法

在新会话中，Codex 会自动加载所有自定义命令
在输入框输入 / 打开斜杠菜单
输入命令名，用 ↑↓ 选择，按 Tab 自动补全或 Enter 直接提交
命令会将文件内容作为消息发送给 Codex

实用案例库

1. 代码审查命令（review-code.md）

文件路径：~/.codex/prompts/review-code.md`

请对以下文件进行详细的代码审查：$1

审查维度：
1. **代码质量**：命名、结构、可读性
2. **潜在bug**：边界条件、错误处理、并发问题
3. **性能**：算法复杂度、不必要的计算、内存泄漏
4. **安全性**：输入验证、SQL注入、XSS等
5. **可维护性**：注释、文档、测试覆盖率

输出格式：
- 🟢 优点（2-3条）
- 🟡 改进建议（3-5条，标注严重程度 Critical/Major/Minor）
- 🔴 必须修复的问题（如有）

请给出具体的代码片段建议。

使用示例：

codex
# 在输入框输入：
/review-code src/utils/auth.ts

效果：Codex 会收到完整的提示词，并对 auth.ts 进行多维度审查。

2. 生成单元测试（gen-tests.md）

文件路径：~/.codex/prompts/gen-tests.md`

为以下文件/函数生成完整的单元测试：$1

测试要求：
- 测试框架：自动检测项目使用的框架（Jest/Vitest/pytest/Go testing 等）
- 覆盖场景：
 - ✅ 正常情况（happy path）
 - ❌ 边界条件（空值、极限值、边界值）
 - 💥 异常情况（错误输入、网络失败、超时等）
- Mock 外部依赖（API 调用、数据库、文件系统）
- 测试数据：使用真实但匿名化的样本数据
- 断言：清晰且具体
- 测试名称：描述性强（用 "should..." 或 "when... then..." 格式）

额外要求：
- 如果是异步函数，正确处理 Promise/async-await
- 如果涉及时间，使用 fake timers
- 生成后自动运行测试验证可通过

使用示例：

/gen-tests src/services/payment.ts
/gen-tests calculateDiscount # 只测试特定函数

3. 解释复杂代码（explain.md）

文件路径：~/.codex/prompts/explain.md`

请详细解释以下代码的工作原理：

$ARGUMENTS

解释要求：
1. **高层概述**（1-2句话）：这段代码做什么？
2. **逐行分析**：
 - 关键变量的含义
 - 每个重要步骤的作用
 - 控制流程（if/loop/异常处理）
3. **使用的技术/模式**：设计模式、算法、数据结构
4. **潜在陷阱**：需要注意的边界情况、性能考虑
5. **改进建议**（如果有明显问题）

请用通俗易懂的语言解释，避免专业术语堆砌。适合给新手看。

使用示例：

/explain "这个正则表达式：^(?=.*[A-Z])(?=.*[a-z])(?=.*\d).{8,}$"
/explain src/core/scheduler.rs

4. 重构建议（refactor.md）

文件路径：~/.codex/prompts/refactor.md`

分析以下代码并提供重构建议：$1

分析维度：
1. **代码异味（Code Smells）**：
 - 过长函数/类
 - 重复代码
 - 过多参数
 - 复杂的条件逻辑
 - 魔法数字/字符串

2. **设计模式应用**：
 - 是否可以应用设计模式简化？
 - 职责是否单一（SRP）？
 - 是否易于扩展（OCP）？

3. **现代语法**：
 - 是否可以使用新版本语言特性（如 Optional Chaining、Pattern Matching 等）？

输出格式：
### 当前问题
- [列出 3-5 个主要问题]

### 重构方案
#### 方案 1: [名称]
- 优点：...
- 缺点：...
- 代码示例：
\`\`\`language
[重构后的代码]
\`\`\`

### 推荐方案
[选择最佳方案并说明理由]

使用示例：

/refactor src/legacy/user-service.js

5. 生成 API 文档（api-docs.md）

文件路径：~/.codex/prompts/api-docs.md`

为以下 API 端点/函数生成完整文档：$1

文档格式：OpenAPI 3.0 风格（即使不是 REST API）

包含内容：
1. **端点信息**：
 - HTTP 方法和路径（如果是 REST）
 - 功能描述（1-2句话）

2. **请求参数**：
 | 参数名 | 类型 | 必需 | 描述 | 默认值 | 示例 |
 |--------|------|------|------|--------|------|

3. **请求体**（如果有）：
 - JSON Schema
 - 示例请求

4. **响应**：
 - 成功响应（200/201）：格式 + 示例
 - 错误响应（400/401/404/500）：错误码 + 消息

5. **使用示例**：
 - cURL 命令
 - JavaScript/Python 客户端代码

6. **注意事项**：
 - 速率限制
 - 认证要求
 - 特殊行为

使用示例：

/api-docs src/api/users.ts
/api-docs "POST /api/v1/orders"

6. Bug 诊断助手（debug.md）

文件路径：~/.codex/prompts/debug.md`

帮我诊断以下问题：

$ARGUMENTS

诊断流程：
1. **问题复现**：
 - 你能稳定复现这个问题吗？
 - 复现步骤是什么？

2. **日志分析**：
 - 检查相关日志文件
 - 分析错误堆栈（如果有）

3. **可能原因**（列出 3-5 个假设）：
 - 按概率排序
 - 每个假设给出验证方法

4. **调试建议**：
 - 添加哪些日志/断点？
 - 需要检查哪些系统状态？

5. **临时解决方案**：
 - 如果暂时无法根治，提供 workaround

输出调试命令（如果适用）。

使用示例：

/debug "React 组件更新后没有重新渲染"
/debug "Docker 容器启动后立即退出，exit code 137"

7. 性能优化分析（optimize.md）

文件路径：~/.codex/prompts/optimize.md`

分析以下代码的性能并提供优化建议：$1

分析维度：
1. **算法复杂度**：
 - 当前时间复杂度：O(?)
 - 当前空间复杂度：O(?)
 - 是否有更优算法？

2. **常见性能问题**：
 - 不必要的循环/递归
 - 重复计算
 - 内存泄漏
 - 阻塞操作
 - N+1 查询问题

3. **语言/框架特定优化**：
 - JavaScript: 避免大量 DOM 操作、使用 Web Workers
 - Python: 用 NumPy/Pandas 替代纯 Python 循环
 - SQL: 索引、查询计划分析
 - Rust: 避免不必要的 clone、使用迭代器

4. **Benchmark**：
 - 生成性能测试代码
 - 对比优化前后的性能数据

输出格式：
### 当前性能问题
[描述问题]

### 优化方案
#### 1. [方案名称]
- 预期提升：X倍
- 实现难度：低/中/高
- 代码示例：
\`\`\`
[优化后的代码]
\`\`\`

### Benchmark 代码
\`\`\`
[性能测试代码]
\`\`\`

使用示例：

/optimize src/analytics/calculate-metrics.py
/optimize "SELECT * FROM orders WHERE user_id = ?"

8. 数据库 Schema 设计（db-schema.md）

文件路径：~/.codex/prompts/db-schema.md`

为以下需求设计数据库 Schema：

$ARGUMENTS

设计要求：
1. **表结构**：
 - 字段名、类型、约束（NOT NULL、UNIQUE 等）
 - 主键、外键
 - 索引建议

2. **关系**：
 - 一对一、一对多、多对多
 - 使用 Mermaid 绘制 ER 图

3. **最佳实践**：
 - 遵循第三范式（或合理的反范式化）
 - 软删除 vs 硬删除
 - 创建时间/更新时间字段
 - 版本控制字段（如需乐观锁）

4. **生成迁移脚本**：
 - 自动检测项目使用的 ORM/迁移工具
 - 生成 SQL 或 ORM 迁移代码

5. **示例数据**：
 - 生成 3-5 条示例 INSERT 语句

使用示例：

/db-schema "电商系统：用户、商品、订单、购物车"
/db-schema "博客平台：文章、评论、标签、分类、用户关注"

9. Git Commit 消息生成（commit-msg.md）

文件路径：~/.codex/prompts/commit-msg.md`

根据当前的 Git 变更生成符合 Conventional Commits 规范的提交消息。

步骤：
1. 运行 `git diff --staged` 查看暂存的变更
2. 分析变更类型：
 - `feat`: 新功能
 - `fix`: Bug 修复
 - `docs`: 文档变更
 - `style`: 代码格式（不影响功能）
 - `refactor`: 重构
 - `perf`: 性能优化
 - `test`: 测试相关
 - `chore`: 构建/工具链变更

3. 生成消息格式：
\`\`\`
&lt;type&gt;(&lt;scope&gt;): &lt;subject&gt;

&lt;body&gt;

&lt;footer&gt;
\`\`\`

示例：
\`\`\`
feat(auth): add OAuth2 login support

- Implement Google and GitHub OAuth providers
- Add token refresh mechanism
- Update user model to store OAuth tokens

Closes #123
\`\`\`

请生成 3 个候选消息，按推荐度排序。

使用示例：

# 先暂存变更
git add src/auth/
# 然后在 Codex 中运行
/commit-msg

10. 环境配置检查（check-env.md）

文件路径：~/.codex/prompts/check-env.md`

检查项目的环境配置是否完整且正确：$1

检查内容：
1. **依赖项**：
 - 读取 `package.json`/`requirements.txt`/`Cargo.toml` 等
 - 检查是否有过时的依赖（有安全漏洞）
 - 检查版本冲突

2. **环境变量**：
 - 读取 `.env.example` 或代码中引用的环境变量
 - 检查当前环境是否缺少必需的变量
 - 敏感信息是否正确加密/隐藏

3. **配置文件**：
 - `tsconfig.json`/`babel.config.js` 等是否合理
 - 是否启用了必要的编译选项（如 TypeScript strict mode）

4. **开发工具**：
 - Linter/Formatter 配置是否存在
 - Git hooks 是否配置
 - CI/CD 配置是否完整

输出格式：
### ✅ 已正确配置
- [列表]

### ⚠️ 需要注意
- [列表]

### ❌ 缺少配置
- [列表 + 修复建议]

使用示例：

/check-env .
/check-env package.json

高级技巧

组合使用参数

# 使用引号包裹多个单词
/explain "React 的 useEffect 和 useLayoutEffect 区别"

# 多个参数
/gen-tests src/utils.ts src/helpers.ts

# 使用 $ARGUMENTS 接收所有参数

嵌套命令（通过 AGENTS.md）

在项目的 AGENTS.md 中配置默认行为，然后用斜杠命令微调：

&lt;!-- AGENTS.md --&gt;
当使用 /review-code 命令时，额外检查：
- 是否符合本项目的命名规范（见 docs/style-guide.md）
- 是否正确使用了项目的自定义 hooks

创建命令别名

# 在 ~/.codex/prompts/ 中创建多个文件指向相同内容
ln -s review-code.md rc.md # 现在可以用 /rc 快速调用

命令管理最佳实践

版本控制：

cd ~/.codex/prompts
git init
git remote add origin &lt;你的仓库地址&gt;
# 团队共享提示词库

分类组织（用前缀）：

~/.codex/prompts/
├── code-review-*.md
├── gen-*.md
├── debug-*.md
└── doc-*.md

文档化：创建 ~/.codex/prompts/README.md 列出所有命令的用途。
定期更新：根据实际使用情况迭代改进提示词。

第二部分：AGENTS.md 配置模板

AGENTS.md 是 Codex 的持久化上下文配置文件，与斜杠命令不同，它会在每次会话中自动加载，用于提供项目级别的规范和指南。

AGENTS.md 的加载顺序

Codex 会按以下顺序合并 AGENTS.md 文件：

~/.codex/AGENTS.md - 全局个人配置
<项目根目录>/AGENTS.md - 项目共享配置
<当前工作目录>/AGENTS.md - 子目录/功能特定配置

与斜杠命令的区别


特性	斜杠命令	AGENTS.md
触发方式	手动调用 `/command`	自动加载（每次会话）
适用场景	一次性任务、快速操作	持久化规范、项目上下文
参数支持	支持 `$1..$9`	无参数
作用域	全局（`~/.codex/prompts/`）	全局/项目/目录
示例用途	代码审查、生成测试	编码规范、技术栈说明

1. 编程语言特定 AGENTS.md 模板

1.1 Python 项目（Django + REST）

# Python/Django 项目指南

## 技术栈
- Python 3.11+
- Django 4.2 + Django REST Framework
- PostgreSQL 14
- Celery + Redis（异步任务）
- pytest（测试）

## 编码规范
- **格式化**：使用 Black（行长 88）
- **Linting**：Ruff + mypy（类型检查必须通过）
- **Import 顺序**：标准库 → 第三方 → Django → 本地（用 isort）
- **文档字符串**：所有 public 函数/类必须有 Google 风格的 docstring

## Django 特定规则
- **Models**：
 - 所有模型必须有 `__str__` 方法
 - 用 `models.TextChoices` 而不是 tuple choices
 - 避免循环导入，用字符串引用外键（如 `'app.Model'`）
- **Views**：
 - API 视图统一用 DRF 的 `APIView` 或 `ViewSet`
 - 权限检查在 view 层，不要在 serializer 里做业务逻辑
- **Serializers**：
 - 只读字段用 `read_only=True`
 - 嵌套序列化最多 2 层
- **URLs**：
 - 用 `app_name` 设置命名空间
 - 路径用 `path()` 不用 `re_path()`（除非必需正则）

## 测试要求
- 所有 API 端点必须有测试
- 用 `pytest-django` + `factory_boy` 生成测试数据
- 测试覆盖率 &gt; 80%

## 数据库迁移
- 每次修改 model 后立即运行 `makemigrations`
- 迁移文件必须有描述性名称（用 `--name`）
- 数据迁移和 schema 迁移分开

## 异步任务
- 长时间运行的任务（&gt;5秒）必须用 Celery
- 任务函数用 `@shared_task` 装饰器
- 任务必须是幂等的（可重复执行）

## 安全
- 敏感数据用环境变量（`.env` 文件）
- 生产环境必须设置 `DEBUG = False`
- API 端点默认需要认证（除非明确标记 `permission_classes = [AllowAny]`）

## 示例代码结构
\`\`\`python
# models.py
class Article(models.Model):
 class Status(models.TextChoices):
 DRAFT = 'draft', 'Draft'
 PUBLISHED = 'published', 'Published'

 title = models.CharField(max_length=200)
 status = models.CharField(max_length=20, choices=Status.choices)

 def __str__(self):
 return self.title

# serializers.py
class ArticleSerializer(serializers.ModelSerializer):
 author_name = serializers.CharField(source='author.username', read_only=True)

 class Meta:
 model = Article
 fields = ['id', 'title', 'status', 'author_name']
 read_only_fields = ['id', 'author_name']

# views.py
class ArticleViewSet(viewsets.ModelViewSet):
 queryset = Article.objects.select_related('author')
 serializer_class = ArticleSerializer
 permission_classes = [IsAuthenticated]
\`\`\`

## 当遇到问题时
1. 先运行 `python manage.py check` 检查配置
2. 查看 `celery -A project worker -l info` 日志
3. 使用 `./manage.py shell_plus` 调试

使用方式：

cd ~/projects/django-project
# 将上述内容保存到 AGENTS.md
codex "给 Article 模型添加全文搜索功能"

1.2 React/TypeScript 前端项目

# React/TypeScript 前端项目规范

## 技术栈
- React 18+ (Hooks only, no class components)
- TypeScript 5+ (strict mode)
- Vite (build tool)
- TailwindCSS (styling)
- React Query (data fetching)
- Zustand (state management)
- React Router v6 (routing)

## TypeScript 规范
- **严格模式**：`strict: true` in tsconfig.json
- **类型定义**：
 - Props 用 `interface` (可扩展)
 - 其他用 `type` (联合类型、工具类型)
 - 避免 `any`，实在不行用 `unknown`
- **命名**：
 - 组件：PascalCase (e.g., `UserProfile.tsx`)
 - Hooks：camelCase with "use" prefix (e.g., `useUserData.ts`)
 - Utils/Constants：camelCase (e.g., `formatDate.ts`)

## 组件结构
\`\`\`typescript
// UserProfile.tsx
import { FC } from 'react';

interface UserProfileProps {
 userId: string;
 onUpdate?: (data: User) =&gt; void;
}

export const UserProfile: FC&lt;UserProfileProps&gt; = ({ userId, onUpdate }) =&gt; {
 // 1. Hooks
 const { data, isLoading } = useUser(userId);
 const [isEditing, setIsEditing] = useState(false);

 // 2. Effects
 useEffect(() =&gt; {
 // side effects
 }, []);

 // 3. Handlers
 const handleSave = () =&gt; {
 // ...
 };

 // 4. Early returns
 if (isLoading) return &lt;Spinner /&gt;;
 if (!data) return &lt;ErrorMessage /&gt;;

 // 5. Render
 return (
 &lt;div className="max-w-2xl mx-auto"&gt;
 {/* JSX */}
 &lt;/div&gt;
 );
};
\`\`\`

## Hooks 规则
- **useState**：初始值类型明确
- **useEffect**：依赖数组必须完整
- **Custom Hooks**：
 - 返回对象而不是数组（除非只有 2 个值）
 - 处理 loading/error 状态

\`\`\`typescript
// ✅ 好
export function useUser(id: string) {
 return {
 user,
 isLoading,
 error,
 refetch
 };
}

// ❌ 避免（超过 2 个返回值）
export function useUser(id: string) {
 return [user, isLoading, error, refetch];
}
\`\`\`

## TailwindCSS 规范
- **响应式**：移动优先（默认样式 → `sm:` → `md:` → `lg:`）
- **避免**：自定义 CSS（除非 Tailwind 无法实现）
- **复用**：提取常用样式到组件
\`\`\`typescript
const buttonStyles = "px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600";
\`\`\`

## 数据获取（React Query）
\`\`\`typescript
// hooks/useUser.ts
export function useUser(id: string) {
 return useQuery({
 queryKey: ['user', id],
 queryFn: () =&gt; api.getUser(id),
 staleTime: 5 * 60 * 1000, // 5 min
 });
}

// 使用
const { data: user, isLoading, error } = useUser(userId);
\`\`\`

## 状态管理（Zustand）
\`\`\`typescript
// stores/authStore.ts
interface AuthState {
 user: User | null;
 login: (credentials: Credentials) =&gt; Promise&lt;void&gt;;
 logout: () =&gt; void;
}

export const useAuthStore = create&lt;AuthState&gt;((set) =&gt; ({
 user: null,
 login: async (creds) =&gt; {
 const user = await api.login(creds);
 set({ user });
 },
 logout: () =&gt; set({ user: null }),
}));
\`\`\`

## 测试
- 用 Vitest + Testing Library
- 测试用户行为，不测试实现细节
- Mock API 调用
\`\`\`typescript
test('shows user name after loading', async () =&gt; {
 render(&lt;UserProfile userId="123" /&gt;);
 expect(screen.getByText(/loading/i)).toBeInTheDocument();

 const name = await screen.findByText('John Doe');
 expect(name).toBeInTheDocument();
});
\`\`\`

## 文件组织
\`\`\`
src/
├── components/
│ ├── common/ # 通用组件 (Button, Input)
│ └── features/ # 功能组件 (UserProfile, ArticleList)
├── hooks/ # Custom hooks
├── stores/ # Zustand stores
├── api/ # API 调用封装
├── types/ # TypeScript 类型定义
├── utils/ # 工具函数
└── pages/ # 路由页面
\`\`\`

## 性能优化
- 用 `React.memo` 包裹纯组件
- 用 `useMemo`/`useCallback` 优化昂贵计算
- 懒加载路由：`const Page = lazy(() =&gt; import('./Page'))`
- 图片用 `&lt;img loading="lazy"&gt;`

## 禁止事项
- ❌ 不要在 useEffect 里直接调用 setState 而不检查依赖
- ❌ 不要用 index 作为 key（除非列表永不重排）
- ❌ 不要在循环/条件里调用 Hooks
- ❌ 不要直接修改 state（用 immutable 方式更新）

1.3 Rust 系统编程项目

# Rust 系统编程项目规范

## 项目信息
- Edition: 2021
- MSRV (Minimum Supported Rust Version): 1.70
- Linter: Clippy (pedantic mode)
- Formatter: rustfmt

## 代码风格
- **命名**：
 - Types/Traits: `PascalCase`
 - Functions/variables: `snake_case`
 - Constants: `SCREAMING_SNAKE_CASE`
 - Lifetimes: 短且描述性 (`'a`, `'input`)

- **错误处理**：
 - 库代码：返回 `Result&lt;T, E&gt;`
 - 应用代码：用 `anyhow::Result`
 - 不要 `unwrap()`/`expect()` 在生产代码中（测试除外）

- **文档**：
 - Public API 必须有文档注释 (`///`)
 - 提供示例代码：
 \`\`\`rust
 /// Fetches user by ID.
 ///
 /// # Example
 /// \`\`\`
 /// let user = fetch_user(123).await?;
 /// \`\`\`
 pub async fn fetch_user(id: u64) -&gt; Result&lt;User&gt; { ... }
 \`\`\`

## 性能最佳实践
- **Clone vs Borrow**：
 - 优先 borrow (`&amp;T`)
 - 只在必需时 clone
 - 考虑 `Cow&lt;T&gt;` (Copy-on-Write)

- **Collections**：
 - 预分配容量：`Vec::with_capacity(n)`
 - 用 `BTreeMap` 需要排序，`HashMap` 更快

- **并发**：
 - 用 `tokio` 处理 async I/O
 - CPU 密集任务用 `rayon`
 - 避免 `Arc&lt;Mutex&lt;T&gt;&gt;`，考虑 channels

## 安全规范
- **Unsafe**：
 - 必须有详细注释说明为什么安全
 - 最小化 unsafe 块范围
 - 考虑用 `# Safety` 文档注释

\`\`\`rust
/// # Safety
/// Caller must ensure pointer is valid and aligned.
unsafe fn read_raw(ptr: *const u8) -&gt; u8 {
 ptr.read()
}
\`\`\`

- **FFI**：
 - 所有 C 函数调用必须检查返回值
 - 用 `CString`/`CStr` 处理 C 字符串

## 测试
- 单元测试放在同文件 `#[cfg(test)]` 模块
- 集成测试放在 `tests/` 目录
- 用 `proptest` 做属性测试
- 用 `cargo-nextest` 加速测试

\`\`\`rust
#[cfg(test)]
mod tests {
 use super::*;

 #[test]
 fn test_parse_valid_input() {
 let result = parse("valid");
 assert!(result.is_ok());
 }
}
\`\`\`

## 依赖管理
- 用 `cargo-deny` 检查许可证和安全漏洞
- 固定版本：`serde = "=1.0.195"` (生产环境)
- 用 features 减少编译体积：
 \`\`\`toml
 [dependencies]
 tokio = { version = "1", features = ["rt-multi-thread", "macros"] }
 \`\`\`

## Clippy 配置
\`\`\`toml
# clippy.toml
too-many-arguments-threshold = 5
type-complexity-threshold = 200
\`\`\`

## 常见模式

### Builder Pattern
\`\`\`rust
pub struct Config {
 host: String,
 port: u16,
}

impl Config {
 pub fn builder() -&gt; ConfigBuilder {
 ConfigBuilder::default()
 }
}

pub struct ConfigBuilder {
 host: Option&lt;String&gt;,
 port: Option&lt;u16&gt;,
}

impl ConfigBuilder {
 pub fn host(mut self, host: impl Into&lt;String&gt;) -&gt; Self {
 self.host = Some(host.into());
 self
 }

 pub fn build(self) -&gt; Result&lt;Config&gt; {
 Ok(Config {
 host: self.host.ok_or("host required")?,,
 port: self.port.unwrap_or(8080),
 })
 }
}
\`\`\`

### Newtype Pattern
\`\`\`rust
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct UserId(pub u64);

impl UserId {
 pub fn new(id: u64) -&gt; Self {
 Self(id)
 }
}
\`\`\`

## 优化编译时间
- 用 `sccache` 或 `mold` 链接器
- 增量编译：`CARGO_INCREMENTAL=1`
- 并行编译：`CARGO_BUILD_JOBS=8`

## 禁止事项
- ❌ 不要 `panic!` 在库代码中（用 `Result`）
- ❌ 不要过度使用泛型（增加编译时间）
- ❌ 不要忽略 `#[must_use]` 警告
- ❌ 不要在 async 函数中阻塞线程（用 `tokio::task::spawn_blocking`）

2. 领域特定 Prompts

2.1 DevOps/Infrastructure

# DevOps &amp; Infrastructure 项目规范

## 技术栈
- Terraform (IaC)
- Kubernetes + Helm
- Ansible (配置管理)
- GitHub Actions (CI/CD)
- Prometheus + Grafana (监控)

## Terraform 规范
- **模块化**：每个资源类型一个模块
- **变量**：
 - 所有变量必须有 `description`
 - 敏感变量标记 `sensitive = true`
 - 提供默认值（除非必须由用户提供）

\`\`\`hcl
variable "instance_type" {
 description = "EC2 instance type"
 type = string
 default = "t3.micro"
}

variable "db_password" {
 description = "Database password"
 type = string
 sensitive = true
}
\`\`\`

- **State 管理**：
 - 远程 backend (S3 + DynamoDB lock)
 - 环境隔离（dev/staging/prod 不同 state 文件）

- **命名**：
 - 资源：`&lt;env&gt;-&lt;app&gt;-&lt;resource&gt;` (e.g., `prod-api-ec2`)
 - 标签：必须包含 `Environment`, `Project`, `ManagedBy`

## Kubernetes 规范
- **命名空间**：按环境/团队隔离
- **资源限制**：所有 Pod 必须设置 `requests` 和 `limits`
 \`\`\`yaml
 resources:
 requests:
 memory: "128Mi"
 cpu: "100m"
 limits:
 memory: "256Mi"
 cpu: "200m"
 \`\`\`

- **健康检查**：
 - `livenessProbe`：检测死锁
 - `readinessProbe`：检测是否就绪

- **ConfigMap vs Secret**：
 - 非敏感配置 → ConfigMap
 - 密码/密钥 → Secret (用 sealed-secrets 加密)

## Helm Charts
- **结构**：
 \`\`\`
 my-app/
 ├── Chart.yaml
 ├── values.yaml # 默认值
 ├── values-prod.yaml # 生产环境覆盖
 └── templates/
 ├── deployment.yaml
 ├── service.yaml
 └── ingress.yaml
 \`\`\`

- **版本**：Chart 版本遵循 SemVer

## CI/CD (GitHub Actions)
- **Workflow 结构**：
 - `test` → `build` → `deploy` (不同 job)
 - 用 matrix 并行测试多版本
 - 生产部署需要 manual approval

\`\`\`yaml
name: Deploy
on:
 push:
 branches: [main]
jobs:
 deploy:
 runs-on: ubuntu-latest
 environment: production # Manual approval
 steps:
 - uses: actions/checkout@v3
 - name: Deploy to K8s
 run: kubectl apply -f k8s/
\`\`\`

## 监控告警
- **Golden Signals**：
 - Latency: P50/P95/P99
 - Traffic: RPS
 - Errors: Error rate %
 - Saturation: CPU/Memory usage

- **告警规则**：
 \`\`\`yaml
 - alert: HighErrorRate
 expr: rate(http_requests_total{status=~"5.."}[5m]) &gt; 0.05
 for: 5m
 annotations:
 summary: "High error rate on {{ $labels.instance }}"
 \`\`\`

## 安全
- **密钥管理**：
 - 用 AWS Secrets Manager / HashiCorp Vault
 - 不要 commit 到 Git

- **网络**：
 - 最小权限原则（Security Groups / Network Policies）
 - 生产环境不允许直接 SSH（用 bastion host）

- **镜像扫描**：
 - 用 Trivy 扫描 Docker 镜像漏洞
 - 禁止 `latest` tag（用语义化版本）

## 文档要求
- **README**：
 - 架构图
 - 部署步骤
 - 回滚步骤
 - 常见问题排查

- **Runbook**：
 - 告警处理流程
 - 灾难恢复计划

2.2 数据科学/机器学习

# 数据科学与机器学习项目规范

## 技术栈
- Python 3.10+
- PyTorch / TensorFlow
- Pandas / Polars (数据处理)
- Scikit-learn (传统 ML)
- MLflow (实验跟踪)
- DVC (数据版本控制)

## 项目结构
\`\`\`
project/
├── data/
│ ├── raw/ # 原始数据（不修改）
│ ├── processed/ # 清洗后数据
│ └── features/ # 特征工程后数据
├── notebooks/ # Jupyter notebooks（探索性分析）
├── src/
│ ├── data/ # 数据加载/处理
│ ├── features/ # 特征工程
│ ├── models/ # 模型定义
│ └── train.py # 训练脚本
├── models/ # 保存的模型文件
├── tests/
└── requirements.txt
\`\`\`

## 数据处理规范
- **原则**：数据管道可复现
- **版本控制**：
 - 用 DVC 跟踪大文件
 - 数据集命名：`&lt;name&gt;_&lt;version&gt;.csv` (e.g., `train_v1.csv`)

- **数据清洗**：
 \`\`\`python
 def clean_data(df: pd.DataFrame) -&gt; pd.DataFrame:
 """Clean raw data.

 Steps:
 1. Remove duplicates
 2. Handle missing values
 3. Normalize column names
 """
 df = df.drop_duplicates()
 df = df.fillna(df.median())
 df.columns = df.columns.str.lower().str.replace(' ', '_')
 return df
 \`\`\`

## 特征工程
- **文档化**：每个特征的含义和计算方法
- **特征重要性**：记录 top-N 特征
- **特征存储**：保存为 `.parquet`（比 CSV 快且小）

\`\`\`python
# features/user_features.py
def create_user_features(df: pd.DataFrame) -&gt; pd.DataFrame:
 """Create user-level features.

 Features:
 - user_age_days: Days since user registration
 - user_activity_score: Total actions / days_active
 """
 df['user_age_days'] = (datetime.now() - df['registered_at']).dt.days
 df['user_activity_score'] = df['total_actions'] / df['days_active']
 return df
\`\`\`

## 模型开发
- **实验跟踪**：所有实验记录到 MLflow
 \`\`\`python
 with mlflow.start_run():
 mlflow.log_params({"lr": 0.01, "epochs": 100})
 # training code
 mlflow.log_metrics({"accuracy": 0.95, "f1": 0.93})
 mlflow.pytorch.log_model(model, "model")
 \`\`\`

- **超参数搜索**：
 - 用 Optuna 或 Ray Tune
 - 记录所有尝试过的配置

- **评估指标**：
 - 分类：Accuracy, Precision, Recall, F1, AUC-ROC
 - 回归：MAE, MSE, RMSE, R²
 - 排序：NDCG, MRR
 - 必须在验证集和测试集上报告

## 训练最佳实践
- **可复现性**：
 \`\`\`python
 import random
 import numpy as np
 import torch

 def set_seed(seed=42):
 random.seed(seed)
 np.random.seed(seed)
 torch.manual_seed(seed)
 torch.cuda.manual_seed_all(seed)
 torch.backends.cudnn.deterministic = True
 \`\`\`

- **Checkpoint**：保存最佳模型和最后模型
- **Early Stopping**：防止过拟合
- **学习率调度**：用 Cosine Annealing 或 ReduceLROnPlateau

## 模型部署
- **模型格式**：
 - PyTorch: `.pt` (state_dict) 或 TorchScript
 - TensorFlow: SavedModel
 - ONNX（跨框架）

- **版本管理**：
 \`\`\`
 models/
 ├── v1/
 │ ├── model.pt
 │ ├── config.json
 │ └── metrics.json
 └── v2/
 ├── model.pt
 ├── config.json
 └── metrics.json
 \`\`\`

- **推理优化**：
 - 批处理推理
 - 模型量化（INT8）
 - TorchScript / ONNX Runtime

## Notebook 规范
- **命名**：`&lt;date&gt;_&lt;author&gt;_&lt;purpose&gt;.ipynb` (e.g., `2024-01-15_john_eda.ipynb`)
- **结构**：
 1. 简介（目的、数据源）
 2. 数据加载
 3. EDA（探索性数据分析）
 4. 结论

- **清理**：
 - Restart &amp; Run All 确保可复现
 - 清除敏感信息（密钥、个人数据）

## 测试
- **数据测试**（用 Great Expectations）：
 \`\`\`python
 def test_data_schema(df):
 assert 'user_id' in df.columns
 assert df['age'].between(0, 120).all()
 assert df['user_id'].nunique() == len(df)
 \`\`\`

- **模型测试**：
 - 输入/输出 shape 正确
 - 模型可以过拟合小数据集（sanity check）
 - 推理时间 &lt; 阈值

## 文档
- **模型卡**（Model Card）：
 - 用途、局限性
 - 训练数据
 - 性能指标
 - 公平性评估

## 禁止事项
- ❌ 不要在 notebook 里训练最终模型（用脚本）
- ❌ 不要硬编码路径（用配置文件或环境变量）
- ❌ 不要泄漏测试集到训练中（data leakage）
- ❌ 不要忽略数据不平衡（用 SMOTE / 类权重）

3. 代码审查 Prompts

# 代码审查 Checklist

当你帮我审查代码时，请检查以下方面：

## 1. 功能正确性 ✅
- [ ] 代码实现了需求
- [ ] 边界条件处理（空输入、极大值、null）
- [ ] 错误处理完整

## 2. 代码质量 📐
- [ ] 命名清晰（变量、函数、类名）
- [ ] 函数职责单一（&lt; 50 行）
- [ ] 避免重复代码（DRY 原则）
- [ ] 魔法数字提取为常量

## 3. 性能 ⚡
- [ ] 算法时间复杂度合理
- [ ] 避免不必要的循环/嵌套
- [ ] 数据库查询优化（N+1 问题）
- [ ] 大文件流式处理

## 4. 安全 🔒
- [ ] 输入验证（防止注入攻击）
- [ ] 敏感数据不暴露（日志/错误信息）
- [ ] 权限检查
- [ ] 密码/密钥不硬编码

## 5. 测试 🧪
- [ ] 有单元测试
- [ ] 测试覆盖关键路径
- [ ] 测试命名清晰

## 6. 文档 📚
- [ ] 复杂逻辑有注释
- [ ] Public API 有文档
- [ ] README 已更新

## 输出格式
请以以下格式输出审查结果：

\`\`\`markdown
### ✅ 优点
- ...

### ⚠️ 需要改进
- **文件**: `path/to/file:line`
 - **问题**: ...
 - **建议**: ...

### 🔴 严重问题
- ...

### 📝 建议
- ...
\`\`\`

4. Bug 修复 Prompts

# Bug 修复指南

当修复 bug 时，请遵循以下流程：

## 1. 理解问题 🔍
- 阅读错误日志/堆栈跟踪
- 确认复现步骤
- 识别影响范围（有多少用户受影响？）

## 2. 定位根因 🎯
- 用二分法缩小范围
- 添加日志/调试输出
- 检查相关的最近变更（git blame）

## 3. 修复方案 🔧
- 优先考虑最小改动
- 如果是设计问题，说明并提出重构建议
- 添加测试防止回归

## 4. 验证 ✅
- 在本地复现并修复
- 运行现有测试
- 添加新测试覆盖此 bug

## 5. 文档 📖
- 更新 CHANGELOG
- 如果是已知问题，更新 FAQ
- Commit message 格式：
 \`\`\`
 fix: &lt;简短描述&gt;

 - Root cause: ...
 - Solution: ...
 - Fixes #&lt;issue-number&gt;
 \`\`\`

## 示例

**Bug 报告**：
\`\`\`
用户登录后偶尔被重定向到 404 页面
Steps: 1. 登录 2. 刷新页面
Error: "Cannot GET /undefined"
\`\`\`

**修复流程**：
1. **定位**：检查日志，发现 `redirect_url` 为 `undefined`
2. **根因**：`req.session.returnTo` 未初始化
3. **修复**：
 \`\`\`javascript
 const redirectUrl = req.session.returnTo || '/dashboard';
 delete req.session.returnTo;
 res.redirect(redirectUrl);
 \`\`\`
4. **测试**：添加测试覆盖 `returnTo` 为空的情况

5. 性能优化 Prompts

# 性能优化指南

优化前必须先 **测量**，不要凭感觉优化！

## 1. 性能分析工具 📊
- **Web 前端**：Chrome DevTools (Performance/Network)
- **Node.js**：`clinic.js`, `0x`
- **Python**：`cProfile`, `line_profiler`
- **Rust**：`cargo flamegraph`
- **数据库**：`EXPLAIN ANALYZE`

## 2. 常见性能问题

### 前端
- **大 Bundle**：代码分割（lazy load）
- **重复渲染**：React.memo, useMemo
- **未压缩资源**：gzip/brotli
- **未缓存**：设置 Cache-Control 头

### 后端
- **N+1 查询**：用 JOIN 或 DataLoader
- **阻塞 I/O**：改为异步
- **未用索引**：检查 `EXPLAIN` 输出
- **过度序列化**：减少 JSON 嵌套层级

### 数据库
- **缺少索引**：为 WHERE/ORDER BY 字段建索引
- **慢查询**：优化 JOIN，避免子查询
- **锁竞争**：减小事务粒度

## 3. 优化优先级 🎯
1. **算法优化**：O(n²) → O(n log n)
2. **I/O 优化**：批量操作、缓存
3. **并行化**：多线程/协程
4. **微优化**：内联、循环展开（通常不必要）

## 4. 优化目标 📏
明确目标指标：
- **延迟**: P50/P95/P99 &lt; X ms
- **吞吐**: &gt; Y RPS
- **资源**: CPU &lt; 70%, Memory &lt; 80%

## 5. 优化示例

**Before (慢)**：
\`\`\`python
# N+1 query
for user in users:
 profile = db.query(Profile).filter_by(user_id=user.id).first()
 print(f"{user.name}: {profile.bio}")
\`\`\`

**After (快)**：
\`\`\`python
# Single query with JOIN
users_with_profiles = db.query(User).join(Profile).all()
for user in users_with_profiles:
 print(f"{user.name}: {user.profile.bio}")
\`\`\`

## 6. 报告格式
优化后请提供：
- **Before**: &lt;metric&gt; (e.g., P95 = 500ms)
- **After**: &lt;metric&gt; (e.g., P95 = 120ms)
- **Improvement**: 76% faster
- **Method**: &lt;描述优化方法&gt;

实战场景扩展

本章节补充更多真实世界的Codex应用案例。

场景 1：重构老代码

codex -m gpt-5-codex "把 src/legacy/ 目录下的 ES5 代码重构成 TypeScript"

Codex 会：

读取所有文件
一个个转换成 TypeScript
运行 tsc 检查类型
如果报错，自动修复

场景 2：自动化测试

codex --profile prototype "给 utils/date.ts 写完整的单元测试"

场景 3：多文件重命名

codex "用 git mv 把所有 .jpeg 文件重命名为 .jpg，并更新所有引用"

> 原理：Codex 会用 grep 搜索引用，然后逐个更新。

场景 4：连接 Figma + 开发

experimental_use_rmcp_client = true

[mcp_servers.figma]
url = "https://mcp.figma.com"

codex mcp login figma
codex "根据 Figma 设计稿 [Design ID] 生成 React 组件"

场景 5：安全审计

codex --profile safe "扫描整个项目，生成安全漏洞报告（Markdown 格式）"

场景 6：CI/CD 集成

name: Codex Code Review
on: [pull_request]

jobs:
 review:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v3
 - name: Install Codex
 run: npm install -g @openai/codex
 - name: Run Codex
 env:
 OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
 run: |
 codex exec "审查这个 PR 的代码变更，输出 review.md" \
 --sandbox read-only \
 --ask-for-approval never
 - name: Comment PR
 uses: actions/github-script@v6
 with:
 script: |
 const fs = require('fs');
 const review = fs.readFileSync('review.md', 'utf8');
 github.rest.issues.createComment({
 issue_number: context.issue.number,
 owner: context.repo.owner,
 repo: context.repo.repo,
 body: review
 });

场景 7：数据库迁移生成

codex "根据 models.py 的变更，生成 Django 数据库迁移并检查是否有数据丢失风险"

Codex 会：

对比当前代码和 Git 历史
识别 model 字段变化
生成迁移文件
警告潜在的数据丢失（如删除字段）
建议数据迁移策略

场景 8：API 文档自动生成

codex "扫描 src/api/ 下的所有路由，生成 OpenAPI 3.0 规范文档"

配合 MCP 使用（连接 Postman）：

[mcp_servers.postman]
url = "https://api.postman.com/mcp"
bearer_token_env_var = "POSTMAN_API_KEY"

codex "生成 API 文档并同步到 Postman 工作区"

场景 9：日志分析和错误排查

codex --profile fast "分析最近 100 行的 application.log，找出所有错误并提供修复建议"

配合 Sentry MCP：

[mcp_servers.sentry]
url = "https://sentry.io/api/mcp"
bearer_token_env_var = "SENTRY_AUTH_TOKEN"

codex "连接 Sentry，分析最近 1 小时的错误趋势，找出最高优先级的 3 个 bug"

场景 10：跨语言代码迁移

codex -m o3 --profile complex "把 legacy/calculator.py (Python 2) 迁移到 Rust，保持完全相同的API"

Codex 会：

理解 Python 2 代码逻辑
生成等价的 Rust 代码
添加单元测试验证行为一致性
处理数据类型差异（如 Python 的无限精度整数）

场景 11：Dockerfile 优化

codex "优化这个 Dockerfile，减小镜像体积，提升构建速度，增强安全性"

典型优化：

多阶段构建
缓存层排序
移除不必要的依赖
使用 alpine 基础镜像
添加安全扫描

场景 12：正则表达式编写和测试

codex "写一个正则表达式匹配中国手机号（包括 +86），并生成 10 个测试用例（5 个有效，5 个无效）"

输出示例：

const phoneRegex = /^(\+86)?1[3-9]\d{9}$/;

// 测试用例
const valid = ['13812345678', '+8613912345678', '15888888888'];
const invalid = ['12345678901', '+8512345678901', '138123456'];

场景 13：环境变量管理和 .env 文件生成

codex "扫描所有代码中使用的环境变量，生成 .env.example 文件，并检查是否有硬编码的密钥"

高级场景（连接 HashiCorp Vault）：

codex "从 Vault 拉取生产环境密钥，生成 Kubernetes Secret 清单"

场景 14：GraphQL Schema 设计

codex "基于现有的 REST API 设计 GraphQL schema，支持分页、过滤和排序"

输入：REST endpoints

GET /users
GET /users/:id/posts
POST /users/:id/follow

输出：GraphQL schema

type User {
 id: ID!
 name: String!
 posts(first: Int, after: String): PostConnection!
 followers: [User!]!
}

type Query {
 users(filter: UserFilter, sort: UserSort, page: PageInput): UserConnection!
 user(id: ID!): User
}

type Mutation {
 followUser(userId: ID!): User!
}

场景 15：依赖更新和兼容性检查

codex "升级 package.json 中的所有依赖到最新版本，检查破坏性变更，更新代码以兼容"

Codex 会：

读取 package.json
检查每个包的 changelog
识别破坏性变更
更新受影响的代码
运行测试验证

带回滚策略：

codex "升级依赖，如果测试失败则回滚到之前版本并记录失败原因"

场景 16：代码覆盖率分析和测试补充

codex "运行 pytest --cov，找出覆盖率低于 80% 的模块，为它们补充测试"

实际操作：

cd python-project
pytest --cov=src --cov-report=json
codex "分析 coverage.json，为 src/utils/parser.py 补充测试用例，覆盖所有分支"

场景 17：国际化（i18n）实现

codex "提取代码中所有硬编码的中文字符串，转换为 i18n 函数调用，并生成 en.json 和 zh.json"

Before:

alert("用户名不能为空");

After:

import { t } from './i18n';
alert(t('errors.usernameRequired'));

生成的 JSON:

{
 "errors": {
 "usernameRequired": "用户名不能为空"
 }
}

// en.json
{
 "errors": {
 "usernameRequired": "Username is required"
 }
}

场景 18：Git 冲突解决

codex "帮我解决 feature/new-ui 分支与 main 的合并冲突，保留两边的功能"

Codex 会：

读取 git diff --conflict=diff3
理解冲突的上下文
智能合并两边的变更
运行测试验证

场景 19：SQL 查询优化

codex "这个 SQL 查询很慢，帮我优化并添加必要的索引"

示例输入：

SELECT u.*, COUNT(p.id) as post_count
FROM users u
LEFT JOIN posts p ON p.user_id = u.id
WHERE u.created_at &gt; '2024-01-01'
GROUP BY u.id
ORDER BY post_count DESC
LIMIT 10;

Codex 输出：

-- 优化后的查询
SELECT u.*, COALESCE(p.post_count, 0) as post_count
FROM users u
LEFT JOIN (
 SELECT user_id, COUNT(*) as post_count
 FROM posts
 GROUP BY user_id
) p ON p.user_id = u.id
WHERE u.created_at &gt; '2024-01-01'
ORDER BY post_count DESC
LIMIT 10;

-- 建议添加索引
CREATE INDEX idx_users_created_at ON users(created_at);
CREATE INDEX idx_posts_user_id ON posts(user_id);

场景 20：生成测试数据和 Faker 脚本

codex "生成 100 条符合真实分布的用户测试数据（JSON 格式），包括中国姓名、手机号、邮箱"

输出（示例）：

[
 {
 "id": 1,
 "name": "张伟",
 "phone": "+8613812345678",
 "email": "[email protected]",
 "age": 28,
 "city": "北京",
 "registered_at": "2023-05-12T08:30:00Z"
 },
 // ... 99 more
]

或生成 Python Faker 脚本：

codex "写一个 Python 脚本用 Faker 生成 1000 条测试用户数据并插入数据库"

场景 21：Kubernetes 问题排查

# 配置 kubectl 使用当前集群
codex "帮我排查为什么 my-app 的 pod 一直 CrashLoopBackOff"

Codex 会执行：

kubectl describe pod &lt;pod-name&gt;
kubectl logs &lt;pod-name&gt; --previous
kubectl get events --field-selector involvedObject.name=&lt;pod-name&gt;

然后分析原因并提供修复建议。

场景 22：代码安全审计

codex --profile review "审计这个项目的安全漏洞（SQL 注入、XSS、CSRF、硬编码密钥）"

AGENTS.md 配置：

# 安全审计 Checklist

## 检查项
- [ ] SQL 注入：是否使用参数化查询
- [ ] XSS：是否转义用户输入
- [ ] CSRF：是否有 token 验证
- [ ] 密钥硬编码：grep 搜索 API_KEY, PASSWORD
- [ ] 依赖漏洞：检查 npm audit / pip-audit
- [ ] 敏感数据日志：是否记录密码/token

场景 23：配置文件格式转换

codex "把 config.yaml 转换为等价的 config.toml，保留所有注释"

实战示例：

codex "把 docker-compose.yml 转换为 Kubernetes manifests（Deployment + Service + ConfigMap）"

场景 24：Shell 脚本现代化

codex "把这个 Bash 脚本重写为 Python，增加错误处理和日志，并添加 CLI 参数"

示例输入（deploy.sh）：

#!/bin/bash
git pull
npm install
npm run build
pm2 restart app

Codex 输出（deploy.py）：

#!/usr/bin/env python3
import subprocess
import logging
import argparse

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

def run_command(cmd):
 logger.info(f"Running: {cmd}")
 result = subprocess.run(cmd, shell=True, capture_output=True, text=True)
 if result.returncode != 0:
 logger.error(f"Command failed: {result.stderr}")
 raise Exception(f"Command failed with code {result.returncode}")
 return result.stdout

def deploy(skip_install=False):
 try:
 run_command("git pull")
 if not skip_install:
 run_command("npm install")
 run_command("npm run build")
 run_command("pm2 restart app")
 logger.info("Deployment successful!")
 except Exception as e:
 logger.error(f"Deployment failed: {e}")
 raise

if __name__ == "__main__":
 parser = argparse.ArgumentParser(description="Deploy application")
 parser.add_argument("--skip-install", action="store_true", help="Skip npm install")
 args = parser.parse_args()
 deploy(skip_install=args.skip_install)

场景 25：代码风格统一

codex "统一整个项目的代码风格：用单引号、分号、2 空格缩进，并设置 ESLint/Prettier 配置"

Codex 会：

创建 .eslintrc.js 和 .prettierrc
运行 eslint --fix 和 prettier --write
更新 CI 配置添加 lint 检查

最佳实践

1. 分层配置策略

~/.codex/config.toml # 个人偏好（模型、密钥）
~/.codex/AGENTS.md # 个人编码风格
项目/.codex/config.toml # 项目特定配置（可选）
项目/AGENTS.md # 项目规范
项目/子目录/AGENTS.md # 模块特定规则

2. Profile 命名规范

[profiles.dev] # 开发环境
[profiles.prod] # 生产环境
[profiles.test] # 测试环境
[profiles.ci] # CI/CD 专用
[profiles.review] # 代码审查

3. Sandbox 安全等级


任务类型	推荐配置
阅读代码	`read-only` + `untrusted`
编写功能	`workspace-write` + `on-failure`
重构	`workspace-write` + `untrusted`
原型开发	`workspace-write` + `never` + `network_access`
CI/CD	`read-only` 或 `workspace-write` + `never`
Docker 内运行	`danger-full-access` + `never`

4. 日志调试速查

# 查看实时日志
tail -f ~/.codex/log/codex-tui.log

# 开启详细日志
RUST_LOG=debug codex

# 只看核心模块日志
RUST_LOG=codex_core=debug,codex_tui=info codex

5. 性能优化

减少 Token 消耗：

# 限制 AGENTS.md 大小（默认 32KB）
project_doc_max_bytes = 16384

# 隐藏推理过程（减少输出）
hide_agent_reasoning = true

# 降低详细程度（仅 GPT-5 系列）
model_verbosity = "low"

加快响应速度：

# 用更快的模型
model = "gpt-5-codex" # 比 o3 快很多

# 降低推理强度
model_reasoning_effort = "low"

6. 团队协作

提交到 Git 的文件：

项目根目录/
├── AGENTS.md # ✅ 提交（团队共享）
├── .codex/
│ └── config.toml # ✅ 提交（项目特定配置）
└── .gitignore # 添加以下内容：
 ~/.codex/ # ❌ 不提交（个人配置）
 *.log # ❌ 不提交（日志）

统一团队配置：

# 项目/.codex/config.toml
model = "gpt-5-codex"
approval_policy = "on-failure"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = false # 强制所有人关闭网络

[mcp_servers.company_docs]
url = "https://docs.company.com/mcp"
bearer_token_env_var = "COMPANY_DOCS_TOKEN"

7. 常见错误排查


错误	原因	解决方法
`Login interrupted`	浏览器授权未完成	重新运行 `codex`，完成浏览器登录
`missing field command`	Streamable HTTP 配置错误	确保启用了 `experimental_use_rmcp_client`
`Permission denied`	Sandbox 阻止了操作	放宽 `sandbox_mode` 或使用 `--sandbox`
`MCP server timeout`	服务器启动慢	增加 `startup_timeout_sec`
`Rate limit exceeded`	API 调用太频繁	等待或切换 profile 用不同的模型
`.git/ is read-only`	沙箱保护 Git 仓库	用 `approval_policy = "on-failure"` 手动批准

快捷命令速查表

# 基本使用
codex # 启动 TUI
codex "任务描述" # 带初始提示启动
codex exec "任务" # 非交互模式
codex resume # 恢复会话选择器
codex resume --last # 恢复最后一个会话

# 配置与模型
codex -m o3 "任务" # 指定模型
codex --profile focus "任务" # 使用 profile
codex -c model=o3 "任务" # 单次覆盖配置
codex --cd /path/to/project "任务" # 指定工作目录

# Sandbox 与审批
codex --sandbox read-only "任务" # 只读模式
codex -a never "任务" # 全自动（危险！）
codex --full-auto "任务" # 等同于 -a never + workspace-write

# MCP 管理
codex mcp add NAME -- COMMAND # 添加 MCP 服务器
codex mcp list # 列出所有服务器
codex mcp get NAME --json # 查看服务器详情
codex mcp remove NAME # 移除服务器
codex mcp login NAME # OAuth 登录
codex mcp logout NAME # OAuth 登出

# 图片输入
codex -i screenshot.png "解释这个错误"
codex --image a.png,b.jpg "对比这两张图"

# Shell 补全
codex completion bash &gt; ~/.codex-completion.bash
codex completion zsh &gt; ~/.zsh/completions/_codex

# 调试与日志
RUST_LOG=debug codex # 详细日志
tail -f ~/.codex/log/codex-tui.log # 实时查看日志

彩蛋：高级玩法

1. 把 Codex 变成 MCP 服务器

# 启动 Codex MCP 服务器
npx @modelcontextprotocol/inspector codex mcp-server

然后在其他 AI 工具（如 OpenAI Agents SDK）里调用 codex 工具：

{
 "tool": "codex",
 "arguments": {
 "prompt": "创建一个 Flask API",
 "sandbox": "workspace-write",
 "approval-policy": "never"
 }
}

> 脑洞：套娃式 AI 协作！外层 AI 调用 Codex，Codex 再调用 MCP 服务器。

2. 自定义工具超时

[mcp_servers.slow_api]
url = "https://slow.api.com/mcp"
tool_timeout_sec = 300 # 5 分钟超时

3. 隐藏敏感配置

# 不要硬编码密钥！
[model_providers.custom]
env_key = "MY_API_KEY" # 从环境变量读取

[mcp_servers.internal]
bearer_token_env_var = "INTERNAL_TOKEN"

在 shell 中：

export MY_API_KEY="sk-xxxxx"
export INTERNAL_TOKEN="secret123"
codex

4. 多项目快速切换

# 在 ~/.bashrc 或 ~/.zshrc 添加别名
alias codex-proj1="codex --cd ~/projects/proj1 --profile proj1"
alias codex-proj2="codex --cd ~/projects/proj2 --profile proj2"

5. 记录所有历史（但不给模型看）

[history]
persistence = "save-all" # 保存到 ~/.codex/history.jsonl
# 注意：这个历史是给你看的，不会自动加载到上下文

总结：Codex 哲学

安全第一：默认 read-only + untrusted，慢慢放开权限。
分层配置：全局 → Profile → 命令行，按需覆盖。
MCP 扩展：用 MCP 连接外部世界，而不是让 AI 瞎猜。
AGENTS.md：把领域知识写下来，AI 会感谢你。
日志为王：遇到问题先看 ~/.codex/log/。

资源链接

官方文档：codex
GitHub 仓库：codex
MCP 协议：modelcontextprotocol.io
AGENTS.md 规范：agents.md
问题反馈：issues

最后的最后：如果你觉得 AI 配置太复杂，记住这句话：

> “任何足够先进的技术都与魔法无异。” —— 阿瑟·克拉克

现在，去用 Codex 创造你的魔法吧！:magic_wand::sparkles:

本教程基于 Codex 0.46.0（2025-10-09 发布）编写。如有更新，请参考官方文档。

🆙 Codex 0.46.0 高级入门教程

🆙 Codex 0.46.0 高级入门教程

核心概念深度解析

1. Approval Policy：信任的艺术

2. Sandbox：沙箱不是猫砂盆

3. Model：选择你的战斗伙伴

MCP：让 Codex 连接万物

MCP 是什么？

配置 MCP 服务器：两种方式

方式 1：STDIO（本地进程）

方式 2：Streamable HTTP（0.46.0 新特性！）

热门 MCP 服务器推荐

MCP CLI 命令速查

高级 MCP 配置

0.46.0 新特性：Streamable HTTP

为什么这是大事？

配置示例

排查 Streamable HTTP 问题

高级配置技巧

1. Profiles：一键切换配置

2. 自定义模型提供商

3. 网络调优（重要！）

4. Shell 环境变量管理

5. AGENTS.md：给 AI 的小纸条

6. 通知系统：让 Codex 告诉你它干完了

7. OpenTelemetry：记录一切

自定义 API 配置深度指南

1. 兼容 OpenAI API 的服务商

1.1 4All API（超低价格！）

1.2 LM Studio（图形化本地模型）

1.3 Anthropic Claude（通过代理）

2. 企业自建 API

2.1 内网 API（带自定义认证）

2.2 需要额外查询参数的 API

2.3 Azure OpenAI（完整配置）

3. 高级 API 调优

3.1 网络不稳定环境

3.2 代理配置

4. 多提供商组合策略

4.1 成本优化配置

4.2 故障转移配置

5. 完整企业级配置示例

6. API 配置调试工具

6.1 测试 API 连接

6.2 验证 Codex 配置

6.3 配置验证 Shell 脚本

7. 常见 API 配置错误排查

自定义 Prompts 完全指南

第一部分：自定义斜杠命令（Custom Slash Commands）

什么是自定义斜杠命令？

基本原理

使用方法

实用案例库

1. 代码审查命令（review-code.md）

2. 生成单元测试（gen-tests.md）

3. 解释复杂代码（explain.md）

4. 重构建议（refactor.md）

5. 生成 API 文档（api-docs.md）

6. Bug 诊断助手（debug.md）

7. 性能优化分析（optimize.md）

8. 数据库 Schema 设计（db-schema.md）

9. Git Commit 消息生成（commit-msg.md）

10. 环境配置检查（check-env.md）

高级技巧

组合使用参数

嵌套命令（通过 AGENTS.md）

创建命令别名

命令管理最佳实践

第二部分：AGENTS.md 配置模板

与斜杠命令的区别

1. 编程语言特定 AGENTS.md 模板

1.1 Python 项目（Django + REST）

1.2 React/TypeScript 前端项目

1.3 Rust 系统编程项目

2. 领域特定 Prompts

2.1 DevOps/Infrastructure

2.2 数据科学/机器学习

3. 代码审查 Prompts

4. Bug 修复 Prompts

5. 性能优化 Prompts