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.1.0 / Git v1.1.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

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

其他配置

文件	适用场景	使用前需要做什么
chatgpt.config.toml	使用 OpenAI/ChatGPT 账号	运行 `codex login`，再使用 `codex --profile chatgpt`
azure.config.toml	Azure OpenAI	填写项目地址，设置 `AZURE_OPENAI_API_KEY`，再使用 `codex --profile azure`
github-copilot.config.toml	通过 LiteLLM 使用 GitHub Copilot	先启动 `litellm_config.yaml`，再使用 `codex --profile github-copilot`
openrouter.config.toml	OpenRouter	设置 `OPENROUTER_API_KEY`，再使用 `codex --profile openrouter`

各 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	实现前梳理需求、比较方案并形成设计文档	可视化伴侣需要 Node.js、浏览器和本机端口权限
claude-skill	把任务交给 Claude Code CLI 执行	需要安装并登录 `claude` CLI
deep-research	并行执行深度调研并汇总为完整报告	需要 Codex CLI；联网和 MCP 权限按任务配置
gpt-image-skill	使用 OpenAI Image API 生成或编辑图片	需要 Python、`OPENAI_API_KEY` 和对应依赖
grill-me	逐项追问方案，并维护术语表和 ADR	会在项目中写入设计与决策文档
handoff	把当前会话整理成下一位 Agent 可直接接手的交接文档	交接文件写入系统临时目录
github-fix-issue	分析并修复 GitHub Issue，可按明确授权提交分支和 PR	需要已登录的 `gh` CLI；默认不 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 帮我把这个产品想法整理成可执行的设计
$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 使用。

修改配置或 Skill 后，建议运行：

# 检查 TOML 语法
python3 -c 'import pathlib, tomllib; [tomllib.loads(p.read_text()) for p in pathlib.Path(".").glob("**/*.toml")]'

# 检查 Codex Plugin 包
python3 -m json.tool .codex-plugin/plugin.json >/dev/null
python3 -m json.tool .agents/plugins/marketplace.json >/dev/null
python3 ~/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py .
bash scripts/test-plugin-install.sh

# 检查 Codex 配置、认证、MCP 和网络状态
codex doctor --summary

# 查看当前版本支持的功能开关
codex features list

# 查看 MCP 配置
codex mcp list

新增或修改脚本时，还要检查 --help、最小可用示例和常见失败路径。测试外部 API 时使用最小权限凭据，并清理日志中的敏感信息。

发布新的 Plugin 内容时，更新 .codex-plugin/plugin.json 的语义化版本，并创建匹配的 v<version> Git 标签；当前版本为 Plugin 1.1.0 / Git v1.1.0。本地反复安装同一版本时使用单一 +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 中记录结果。

参考资料

Codex CLI 官方文档 — 入门必读，涵盖安装、命令和核心概念
Codex 配置说明 — 配置文件格式和基础选项
Codex 配置参考 — 所有配置项的完整参考手册
Codex Skills — 官方 Skills 规范，编写自定义 Skill 时参考
Codex GitHub 仓库 — 源码、Issue 追踪和版本发布
LiteLLM 文档 — 多模型网关，用于接入第三方模型提供商

如果这个项目对你有帮助，欢迎点个 ⭐ 支持一下！

许可证

本项目采用 MIT License。

codex-settings

安装

快速入门

安全报告

README.md

Codex CLI Skills & Profiles

为什么用这套配置

快速开始

1. 安装 Codex CLI

2. 推荐：使用 Codex Plugin 安装 Skills

3. 完整安装：直接克隆到 ~/.codex

4. 选择认证方式

copilot-gateway（默认）

配置说明

默认配置

其他配置

Profiles

LiteLLM

MCP

Skills（技能）

图像技能依赖

开发和检查

安全提醒

常见问题

贡献

参考资料

许可证

常见问题

评论 (0)

相关 Skills

开发者还喜欢

3. 完整安装：直接克隆到 `~/.codex`