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 安装方式。

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

如果本机还没有 ~/.codex，最简单的方式是直接把仓库克隆到 Codex 的用户配置目录：

git clone https://github.com/feiskyer/codex-settings.git ~/.codex

这样根目录的 config.toml 会成为默认配置，skills/ 下的内容也会被 Codex 自动发现。

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 的安装和启动脚本。

配置说明

默认配置

根目录的 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/.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 帮我把这个产品想法整理成可执行的设计
$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 Git 标签；当前版本为 Plugin 1.1.0 / Git v1.1.0。本地反复安装同一版本时使用单一 +codex. 后缀，避免命中旧缓存。

安全提醒

• 不要提交 API Key、访问令牌、Cookie、真实 Authorization Header 或包含隐私信息的日志。
• 不要在不可信项目中直接使用 danger-full-access、approval_policy = "never" 或过于宽泛的 allow 规则。
• 安装 Skill、MCP 服务或第三方依赖前，先阅读源码并确认网络访问范围。
• 使用第三方模型提供商时，确认代码和提示词的保存、处理和合规政策。
• 如需报告安全问题，优先使用 GitHub 的私密漏洞报告功能；如果仓库没有启用，请先通过维护者的 GitHub 主页联系，不要在公开 Issue 中披露细节或凭据。

常见问题

贡献

欢迎通过 Issues 和 Pull Requests 提交改进。

完整流程见 CONTRIBUTING.md，安全问题请按 SECURITY.md 私下报告，版本与兼容性边界见 COMPATIBILITY.md。

提交前请确认：

1. 没有包含真实密钥、个人配置或敏感日志。
2. 新配置使用清晰的占位符，并说明前置条件。
3. 新 Skill 使用 kebab-case 目录名，且 SKILL.md 包含准确的 name 和 description。
4. 新脚本说明依赖、输入、输出和失败行为。
5. README、命令示例和实际目录结构保持一致。
6. 已完成与改动相匹配的本地检查，并在 PR 中记录结果。

参考资料

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

---

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

许可证

本项目采用 MIT License。