Codex CLI Skills & Profiles
给 Codex CLI 加上深度调研、图片生成、浏览器调试等能力，配好多模型切换，开箱即用。
仓库采用面向个人开发效率的默认配置；你可以整套使用，也可以按需选取 Profiles 或 Skills。使用前请确认模型提供商、权限和外部依赖，并避免提交真实密钥。
为什么用这套配置
如果你想少花时间调配置，多花时间完成真正的开发工作，这个仓库提供了一套可以直接运行、也可以自由组合的 Codex CLI 工作台。
- 灵活切换模型：预置 copilot-gateway、ChatGPT、Azure OpenAI、OpenRouter 和 LiteLLM/GitHub Copilot Profiles。
- 复用成熟工作流：通过 Skills 完成需求梳理、深度调研、图像生成、字幕提取和任务交接。
- 连接真实开发环境：通过 Chrome DevTools MCP 调试网页、检查性能并执行浏览器自动化。
- 整套或按需使用：既可以作为完整的 Codex Home，也可以只复制需要的 Profile 或 Skill。
本项目面向 Codex CLI；Claude Code 的配置、Skills 与 Agents 请查看 Claude Code Settings。
快速开始
1. 安装 Codex CLI
使用 npm 安装：
npm install -g @openai/codex
也可以参考 Codex CLI 官方文档 选择其他安装方式。
2. 推荐：使用 Codex Plugin 安装 Skills
如果你已经有自己的 Codex 配置，只想安装本仓库提供的 Skills，可以把仓库作为 Plugin Marketplace 添加：
codex plugin marketplace add feiskyer/codex-settings
codex plugin list --marketplace codex-settings --available --json
codex plugin add codex-settings@codex-settings
安装完成后启动一个新的 Codex 会话，让 Codex 重新发现 Plugin 中的 Skills。未指定 --ref 时，Marketplace 使用仓库默认分支，因此首次安装会获取当时的最新版本。仓库中的 Plugin 版本为 1.5.0；发布时使用匹配的 Git 标签 v1.5.0。
仓库发布新版并更新 Plugin 版本后，刷新 Marketplace 快照并重新安装：
codex plugin marketplace upgrade codex-settings
codex plugin add codex-settings@codex-settings
如果使用本仓库 clone，也可以运行更新脚本。它会刷新所有已配置的 Git Marketplace，同时在刷新前冻结当前已安装且启用的 Plugin 列表，随后只更新这份列表中的 Plugin；不会安装 Marketplace 中其他未安装的 Plugin：
# 更新所有已配置的 Git Marketplace 及其中已安装的 Plugin
scripts/update-codex-plugins.sh
# 只更新指定 Marketplace 中已安装的 Plugin
scripts/update-codex-plugins.sh --marketplace codex-settings
# 仅查看将要执行的命令
scripts/update-codex-plugins.sh --dry-run
为避免改变启用状态，已安装但被禁用的 Plugin 会被跳过；本地或系统管理的 Marketplace 也不会由该脚本刷新。更新完成后请启动新的 Codex 会话。
需要卸载时运行：
codex plugin remove codex-settings@codex-settings
codex plugin marketplace remove codex-settings
也可以从本地干净 clone 测试或开发 Plugin：
git clone https://github.com/feiskyer/codex-settings.git ~/codex-settings
codex plugin marketplace add ~/codex-settings
codex plugin add codex-settings@codex-settings
Plugin 直接复用根目录 skills/，不会生成第二份 Skills。安装后只会把这些 Skills 作为工作流提供给 Codex，不会应用或替换你的 config.toml，也不会启用本仓库的 Profiles、模型 Provider、LiteLLM 配置或根目录 MCP 设置。如果需要完整配置，请使用下一节的 Codex Home 安装方式。
备选：使用 npx skills 安装（版本可能滞后）
也可以使用第三方 skills CLI 从仓库安装 Skills：
npx skills add feiskyer/codex-settings
按照交互提示选择 Codex 和安装范围。当前 npx skills add 没有提供 Git tag/ref 选择参数，其索引、缓存或发布快照也可能滞后，因此不能保证与仓库默认分支的最新内容同步；需要优先获取仓库最新 Plugin 快照时，使用上面的 Codex Plugin 安装方式。
3. 完整安装：直接克隆到 ~/.codex
如果本机还没有 ~/.codex，最简单的方式是直接把仓库克隆到 Codex 的用户配置目录：
git clone https://github.com/feiskyer/codex-settings.git ~/.codex
这样根目录的 config.toml 会成为默认配置，skills/ 下的内容也会被 Codex 自动发现。
如果 ~/.codex 已经存在：保留原目录并手动合并
先把仓库克隆到其他目录。下面使用 ~/codex-settings，你也可以换成其他位置：
git clone https://github.com/feiskyer/codex-settings.git ~/codex-settings
复制配置前，先备份现有文件：
test ! -f ~/.codex/config.toml || \
cp ~/.codex/config.toml ~/.codex/config.toml.bak
# 使用仓库默认配置
cp ~/codex-settings/config.toml ~/.codex/config.toml
如需保留其他模型提供商的 Profiles 和 LiteLLM 示例，一并复制：
cp ~/codex-settings/*.config.toml ~/.codex/
cp ~/codex-settings/litellm_config.yaml ~/.codex/litellm_config.yaml
然后安装仓库中的 Skills：
mkdir -p ~/.codex/skills
cp -R ~/codex-settings/skills/. ~/.codex/skills/
完成合并后，继续按照下方说明选择一种认证方式。
4. 选择认证方式
下面三种方式任选其一。仓库默认使用 copilot-gateway，因为根目录的 config.toml 已经按该方式配置。
copilot-gateway（默认）
根目录的 config.toml 已指向：
http://localhost:4141
先在一个终端中启动 copilot-gateway：
npx copilot-gateway@latest start --proxy-env
保持网关进程运行。确认它已经监听 localhost:4141 后，在另一个终端中启动 Codex：
codex doctor --summary
codex mcp list
codex
这种方式由 copilot-gateway 负责上游认证，不需要运行 codex login。仓库只提供 Codex 配置，不包含 copilot-gateway 的安装和启动脚本。
使用 LiteLLM
LiteLLM 使用 litellm_config.yaml，默认监听 http://localhost:4000。先安装 LiteLLM：
python3 -m pip install -U 'litellm[proxy]'
在一个终端中启动 LiteLLM：
litellm --config ~/.codex/litellm_config.yaml
确认 LiteLLM 使用的 GitHub Copilot 提供商已经完成认证，然后在另一个终端中启动 Codex：
codex doctor --summary
codex mcp list
codex --profile github-copilot
这种方式由 LiteLLM 和它所连接的 GitHub Copilot 提供商处理上游认证，不需要运行 codex login。
使用 ChatGPT
登录 ChatGPT 账号并启动 Codex：
codex login
codex doctor --summary
codex mcp list
codex --profile chatgpt
这种方式直接使用 Codex 的 ChatGPT 登录状态，不需要启动本地代理或网关。
配置说明
默认配置
根目录的 config.toml 当前使用：
- 模型：
gpt-5.6-sol
- 模型提供商：
github
- 本地网关：
http://localhost:4141
- Web Search：
live
- MCP：Chrome DevTools MCP
- 审批策略：
never
- 沙箱模式：
danger-full-access
如果不需要完全开放的本地权限，建议至少改成：
approval_policy = "on-request"
sandbox_mode = "workspace-write"
[sandbox_workspace_write]
network_access = false
其他配置
各 Profile 当前默认使用 gpt-5.6-sol，实际可用性取决于模型提供商和账号权限。如遇模型不可用，请替换为对应提供商支持的模型标识符。遇到无法识别的配置项时，可以运行：
codex features list
codex doctor --summary
Profiles
当前 Codex 通过独立文件加载 Profile：
~/.codex/<name>.config.toml
例如，codex --profile chatgpt 会在基础配置之上叠加 ~/.codex/chatgpt.config.toml。本仓库的 Profile 文件只覆盖模型、模型提供商和认证信息；权限、Features、MCP、TUI 等共享设置继续由 config.toml 提供。
LiteLLM
当前 Codex 自定义模型提供商只接受 wire_api = "responses"。LiteLLM 可以作为兼容层，将 GitHub Copilot 等第三方模型提供商的 Chat Completions 等接口封装为 Responses API，从而供 Codex 使用。
litellm_config.yaml 与 github-copilot.config.toml 配套，默认监听 http://localhost:4000。它和根目录配置使用的 localhost:4141 不是同一个网关。
python3 -m pip install -U 'litellm[proxy]'
litellm --config ~/.codex/litellm_config.yaml
MCP
默认配置通过 npx 启动最新版 Chrome DevTools MCP，并自动连接本机 Chrome。所有 Profiles 共享该 MCP 配置。
Skills（技能）
| 名称 |
用途 |
依赖或注意事项 |
| brainstorming |
澄清未决需求和关键取舍，形成足以实现的设计 |
保留设计评审要求，不重复审批已授权的明确方案；浏览器伴侣需同意后启动 |
| claude-skill |
把任务交给 Claude Code CLI 执行 |
需要安装并登录 claude CLI |
| code-simplifier |
在保持行为不变的前提下简化代码、提升可读性 |
默认聚焦最近修改的代码，遵循目标项目约定 |
| deep-research |
并行执行深度调研并汇总为完整报告 |
仅显式调用 $deep-research 时使用；需要 Codex CLI；联网和 MCP 权限按任务配置 |
| gpt-image-skill |
使用 OpenAI Image API 生成或编辑图片 |
需要 Python、OPENAI_API_KEY 和对应依赖；仅在点名 OpenAI/GPT Image 时触发 |
| grill-me |
逐问逐答检验方案的关键假设与取舍 |
默认在对话中交付；仅按要求维护术语表和 ADR |
| minimax-image-skill |
使用 MiniMax Image API 生成图片 |
需要 Python 3.9+ 和 MINIMAX_API_KEY；仅在点名 MiniMax 时触发 |
| handoff |
把当前会话整理成下一位 Agent 可直接接手的交接文档 |
交接文件写入系统临时目录 |
| github-fix-issue |
调查 GitHub Issue，或完成已授权的本地修复与验证 |
调查请求保持只读；默认不 push 或创建 PR |
| github-review-pr |
按变更风险调查并核验 GitHub PR 的具体缺陷 |
需要 gh CLI；不强制六路并行，默认不发布评论或批准 |
| nanobanana-skill |
使用 Gemini 图像模型生成或编辑图片；未点名厂商时的默认图像技能 |
需要 Python、GEMINI_API_KEY 和对应依赖 |
| youtube-transcribe-skill |
提取 YouTube 字幕或转录文本 |
需要 yt-dlp，或使用 Chrome DevTools MCP 作为备用方案 |
显式调用示例：
$brainstorming 帮我把这个产品想法整理成可执行的设计
$code-simplifier 简化最近修改的代码，保持行为不变
$github-fix-issue 修复当前仓库的 issue #123，但先不要 push
$github-review-pr 审查 PR #456，只把结果报告给我
$grill-me 逐项挑战一下这份技术方案
$handoff 把当前进度整理成交接文档
$gpt-image-skill 生成一张产品发布海报
图像技能依赖
建议使用独立虚拟环境安装 Python 依赖：
python3 -m venv ~/.codex/.venv
source ~/.codex/.venv/bin/activate
python -m pip install -r ~/.codex/skills/gpt-image-skill/requirements.txt
python -m pip install -r ~/.codex/skills/nanobanana-skill/requirements.txt
API Key 应保存在本地环境变量或 Skill 指定的私有环境文件中，不要写进仓库。
开发和检查
在仓库根目录开发时，可以把当前 clone 目录临时设为 CODEX_HOME：
cd /path/to/codex-settings
export CODEX_HOME="$(pwd)"
该设置只对当前终端会话生效。此后根目录的 config.toml、*.config.toml 和 skills/ 会作为当前 Codex Home 使用。
修改后按 CONTRIBUTING.md 的验证说明 选择与改动对应的检查。
发布新的 Plugin 内容时，更新 .codex-plugin/plugin.json 的语义化版本，并创建匹配的 v<version> Git 标签；当前 Plugin 版本为 1.5.2，发布时应使用 v1.5.2。本地反复安装同一版本时使用单一 +codex.<cachebuster> 后缀，避免命中旧缓存。
安全提醒
- 不要提交 API Key、访问令牌、Cookie、真实 Authorization Header 或包含隐私信息的日志。
- 不要在不可信项目中直接使用
danger-full-access、approval_policy = "never" 或过于宽泛的 allow 规则。
- 安装 Skill、MCP 服务或第三方依赖前，先阅读源码并确认网络访问范围。
- 使用第三方模型提供商时，确认代码和提示词的保存、处理和合规政策。
- 如需报告安全问题，优先使用 GitHub 的私密漏洞报告功能；如果仓库没有启用，请先通过维护者的 GitHub 主页联系，不要在公开 Issue 中披露细节或凭据。
常见问题
Codex CLI 应该如何安装？
优先按照 Codex CLI 官方文档 选择当前平台支持的安装方式；也可以使用 npm install -g @openai/codex。本仓库不提供 Codex 或 Windows 安装包。安装后运行 codex --version 和 codex doctor --summary 检查是否完整，不要把 ChatGPT 应用和 Codex CLI 当成同一个安装包。
为什么 Codex 会连接 localhost:4141？需要执行 codex login 吗？
本仓库默认使用 copilot-gateway，请求会发送到 http://localhost:4141，因此需要先运行：
npx copilot-gateway@latest start --proxy-env
该模式由网关处理上游认证，不需要执行 codex login，也不是 OpenAI 官方的 GitHub Copilot 登录方式。
ChatGPT 登录、API Key 和第三方 Provider 有什么区别？
codex login 使用 ChatGPT 登录，并消耗 ChatGPT 工作区或订阅提供的 Codex 用量；API Key 使用 OpenAI Platform 的独立 API 计费。第三方 Provider 使用自己的端点、凭据和计费规则，不会自动继承 ChatGPT 订阅或 OpenAI API 权限。本仓库默认 copilot-gateway 的上游认证由网关负责。
如何切换 Profile 或模型？
使用 --profile 切换仓库提供的模型配置，使用 --model 临时指定模型：
codex --profile chatgpt
codex --profile azure
codex --profile openrouter
codex --model <MODEL>
模型必须被当前 Provider、部署和账号权限支持；可用 codex debug models 查看 Codex 当前识别的模型。本仓库填写的默认模型不保证在所有 Provider 中都可用。
Reconnecting、请求错误或一直思考怎么排查？
先运行：
codex --version
codex login status
codex doctor --summary
默认配置还应确认 copilot-gateway 正在监听 localhost:4141；LiteLLM Profile 则检查 localhost:4000。如果只有 MCP 异常，再运行 codex mcp list --json。
Skills 如何安装和调用？为什么没有显示？
将仓库克隆到 ~/.codex 时，仓库中的 Skills 会位于 ~/.codex/skills；也可以按照前面的步骤单独复制。可通过 /skills 或 $skill-name 显式调用。未识别时，请检查 Skill 目录中是否包含有效的 SKILL.md，并确认当前 Codex 版本支持 Skills。
Chrome DevTools MCP 会自动连接吗？
默认配置会通过 npx 启动最新版 Chrome DevTools MCP，并请求自动连接本机 Chrome，但是否成功仍取决于 Chrome 和本机调试环境。可以运行：
codex mcp list --json
codex mcp get chrome --json
所有 Profiles 都会继承基础配置中的 Chrome DevTools MCP。
为什么额度很快用完？ChatGPT 和 API Key 共用额度吗？
ChatGPT 登录使用计划包含的 Codex 用量及可能购买的 ChatGPT credits；API Key 使用 OpenAI Platform 的独立 API 计费，两者不共用额度。消耗速度会受模型、推理强度、上下文长度和任务类型影响，本仓库不承诺固定可用时长。第三方 Provider 的额度和重置规则以对应服务为准。
可以切换到 Kimi、MiniMax、DeepSeek 或 GLM-5.2 吗？
可以。本仓库在 litellm_config.yaml 末尾提供了默认注释的 Kimi K3、MiniMax-M3、DeepSeek-V4-Pro 和 GLM-5.2 配置示例。设置对应的 MOONSHOT_API_KEY、MINIMAX_API_KEY、DEEPSEEK_API_KEY 或 ZAI_API_KEY，取消所需模型段落的注释，启动 LiteLLM 后运行：
codex --profile github-copilot --model <MODEL>
这里继续复用 github-copilot Profile 指向的 localhost:4000 LiteLLM 网关；Profile 名称不会限制实际使用的上游模型。LiteLLM 会把 Codex 的 Responses API 请求桥接到对应 Provider，但不同模型的工具调用、推理和多模态能力可能不同，启用后应先执行最小任务验证。
本仓库的默认权限是什么？
默认配置使用 approval_policy = "never" 和 sandbox_mode = "danger-full-access"，这是本仓库有意采用的效率优先设置：Codex 可以不经命令批准、在无沙箱限制下执行操作。请只在信任的代码仓库和本机环境中使用；安装第三方 Provider、Skill 或 MCP 前，应检查其网络访问、凭据处理和数据政策。如需更严格的权限，可以参考后面的"默认配置"章节调整。
贡献
欢迎通过 Issues 和 Pull Requests 提交改进。
完整流程见 CONTRIBUTING.md，安全问题请按 SECURITY.md 私下报告，版本与兼容性边界见 COMPATIBILITY.md。
提交前请确认：
- 没有包含真实密钥、个人配置或敏感日志。
- 新配置使用清晰的占位符，并说明前置条件。
- 新 Skill 使用 kebab-case 目录名，且
SKILL.md 包含准确的 name 和 description。
- 新脚本说明依赖、输入、输出和失败行为。
- README、命令示例和实际目录结构保持一致。
- 已完成与改动相匹配的本地检查，并在 PR 中记录结果。
参考资料
如果这个项目对你有帮助，欢迎点个 ⭐ 支持一下！
许可证
本项目采用 MIT License。
评论