配置模板

config.toml 完整模板

来自「Codex CLI 深度指南」与多篇教程整合,可直接复制作为起点:

# ========== 基础配置 ==========

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

# 审批策略:on-request 表示关键操作前人工确认,其余自动推进
approval_policy = "on-request"

# 沙箱模式:workspace-write 表示只能在工作区写入
sandbox_mode = "workspace-write"

# 推理强度
model_reasoning_effort = "medium"

# ========== 功能开关 ==========

[features]
# 开启 hooks 钩子
hooks = true

# ========== 沙箱(块状写法,等价于顶层 sandbox_mode)==========
# [sandbox]
# mode = "workspace-write"

# ========== Hooks 示例 ==========

# [[hooks.Event.hooks]]
# event = "task-complete"
# command = ["/absolute/path/to/ring.sh"]

CI Profile 模板

model = "gpt-5.4-mini"
approval_policy = "never"
hide_agent_reasoning = true

OSS 本地模型配置

[model_providers.oss]
name = "oss"
base_url = "http://localhost:11434/v1"
env_key = "OSS_API_KEY"

model = "qwen3-coder"
model_provider = "oss"
model_reasoning_effort = "medium"
approval_policy = "never"

自定义模型提供方

[model_providers.custom]
name = "custom-provider"
base_url = "https://your-proxy.example.com/v1"
env_key = "OPENAI_API_KEY"

AGENTS.md 模板

> 本文件是给 Codex 等 AI Agent 看的项目说明,自动加载进上下文。

## 项目概述
- 项目名:your-project
- 类型:Node.js 后端服务
- 语言:TypeScript

## 目录结构
- src/           源码
- src/modules/   业务模块
- src/shared/    共享代码
- tests/         测试
- scripts/       脚本

## 环境要求
- Node.js 22+
- pnpm 9+

## 常用命令
| 操作 | 命令 |
|------|------|
| 安装依赖 | pnpm install |
| 开发 | pnpm dev |
| 构建 | pnpm build |
| 测试 | pnpm test |
| 单文件测试 | pnpm test path/to/file |
| lint | pnpm lint |
| type check | pnpm typecheck |

## 工程约定
- 包管理器:pnpm(禁用 npm/yarn)
- 代码风格:Prettier + ESLint,2 空格,单引号,无分号
- 命名:变量 camelCase,类 PascalCase,常量 UPPER_SNAKE
- 注释:复杂逻辑必须注释,公开 API 必须 JSDoc

## 禁止事项
- ❌ 不要修改 src/generated/(自动生成代码)
- ❌ 不要直接改 dist/(构建产物)
- ❌ 不要引入新依赖,除非充分论证
- ❌ 不要跳过测试提交

## PR / 提交规范
- 提交信息遵循 Conventional Commits(feat: / fix: / docs: 等)
- 一个 PR 只解决一个问题
- 必须包含测试,且测试通过
- 描述说明 why,不只是 what

## 完成标准(Definition of Done)
- [ ] 实现完成
- [ ] 测试补充并通过
- [ ] lint 无报错
- [ ] type check 通过
- [ ] git diff 无无关修改
- [ ] 文档更新(如涉及 API 变更)

## 代码审查
审查时遵循 [code_review.md](./code_review.md) 的规则。

## 执行计划
长任务参考 [PLANS.md](./PLANS.md) 模板。

SKILL.md 模板

---
name: log-triage
description: |
  排查应用日志,定位异常和错误。
  当用户说"查日志"、"日志报错"、"排查异常"时触发。
---

# Log Triage 技能

## 输入
- 日志文件路径或日志内容
- 关注的时间范围
- 关注的关键词(可选)

## 步骤
1. 读取日志文件
2. 按时间范围过滤
3. 提取 ERROR / WARN 级别
4. 关联同一请求的上下文
5. 输出:错误摘要 + 根因假设 + 建议排查方向

## 输出格式
- 错误时间、级别、消息
- 上下文(前后 N 行)
- 根因假设
- 建议下一步

code_review.md 模板

# Code Review Checklist

## 必查项
- [ ] 命名清晰,符合团队规范
- [ ] 单一职责,函数/类不过长
- [ ] 无明显副作用
- [ ] 错误处理完整(不吞异常)
- [ ] 无硬编码密钥/密码
- [ ] 无 SQL 注入、XSS 等安全风险

## 测试
- [ ] 新代码有测试
- [ ] 边界条件覆盖
- [ ] 测试通过

## 性能
- [ ] 无 N+1 查询
- [ ] 无不必要的全量加载
- [ ] 大数据量场景考虑分页

## 可维护性
- [ ] 复杂逻辑有注释
- [ ] 公开 API 有文档
- [ ] 无重复代码

PLANS.md 模板

## 任务:重构 auth 模块

## 背景
- 当前 auth 模块耦合严重,登录/登出/会话混在一起
- 目标:拆分为 login / logout / session 三个子模块

## 步骤
1. [ ] 阅读现有 src/auth/* 代码,理解依赖关系
2. [ ] 拆分 AuthSession 到 src/auth/session.ts
3. [ ] 拆分登录逻辑到 src/auth/login.ts
4. [ ] 拆分登出逻辑到 src/auth/logout.ts
5. [ ] 更新所有 import
6. [ ] 跑测试,确保不回归
7. [ ] 补充新模块的单元测试

## 风险
- 循环依赖:session 和 login 可能互相引用
- 中间件顺序:auth 中间件依赖 session

## 验证
- pnpm test 全绿
- 手动测试登录/登出/会话过期
- git diff 只涉及 src/auth/

资料来源

头条《Codex CLI 深度指南》——可直接用的 config.toml 起点
掘金《Codex 接哪个模型效果最好》——CI Profile
掘金《在 Codex 中配置使用智谱、Ollama 本地模型》——OSS 配置
掘金《我给 codex 装了个彩铃》——hooks 配置
OpenAI 官方 best practices——AGENTS.md、PLANS.md 指南