配置与定制

配置层次结构

Codex 的配置系统采用分层结构，从全局到项目级逐层覆盖：

全局配置 (~/.claude/settings.json)
    ↓ 基础配置
用户配置 (~/.claude/settings.local.json)
    ↓ 覆盖全局
项目配置 (项目目录/.claude/settings.json)
    ↓ 覆盖用户配置
CLAUDE.md (项目目录/CLAUDE.md)
    ↓ 项目指令
环境变量
    ↓ 运行时覆盖
命令行参数

每一层都会继承上一层的配置，并允许针对性地覆盖。

全局配置

全局配置文件位于 ~/.claude/settings.json，适用于所有项目。

基本结构

{
  "models": {
    "default": "claude-3-opus",
    "temperature": 0.7,
    "maxTokens": 4096
  },
  "theme": {
    "mode": "dark",
    "fontSize": 14
  },
  "permissions": {
    "allowCommands": ["npm", "git", "node"],
    "allowPaths": ["/home/user/projects"]
  },
  "editor": {
    "tabSize": 2,
    "insertSpaces": true
  }
}

配置项说明

配置项	类型	默认值	说明
`models.default`	string	claude-3-opus	默认模型
`models.temperature`	number	0.7	生成随机性 (0-1)
`models.maxTokens`	number	4096	最大 Token 数
`theme.mode`	string	dark	主题模式
`permissions.allowCommands`	string[]	[]	允许的命令白名单

项目级配置

使用 settings.json

项目级配置放在项目根目录的 .claude/settings.json 中：

{
  "models": {
    "default": "claude-3-sonnet",
    "temperature": 0.5
  },
  "permissions": {
    "allowCommands": ["npm", "npx", "git", "node", "yarn"],
    "allowPaths": ["."]
  },
  "project": {
    "name": "my-app",
    "language": "typescript",
    "framework": "nextjs"
  }
}

使用 CLAUDE.md

CLAUDE.md 是项目级别的核心配置文件，使用 Markdown 格式为 Codex 提供项目上下文和指令：

# 项目指南

## 技术栈

- 前端：Next.js 14 + TypeScript + Tailwind CSS
- 后端：Next.js API Routes
- 数据库：PostgreSQL + Prisma ORM
- 认证：NextAuth.js

## 开发规范

- 使用函数组件和 Hooks，避免类组件
- 遵循 ESLint + Prettier 配置
- 组件文件使用 PascalCase 命名
- 工具函数使用 camelCase 命名

## 常用命令

- `npm run dev` — 启动开发服务器
- `npm run build` — 构建生产版本
- `npm run lint` — 代码检查
- `npm run test` — 运行测试

## 目录结构

- `src/app/` — Next.js App Router 页面
- `src/components/` — 通用组件
- `src/lib/` — 工具函数和库
- `src/types/` — TypeScript 类型定义

环境变量

系统环境变量

# .env 文件
ANTHROPIC_API_KEY=sk-xxx
CLAUDE_CONFIG_DIR=~/.claude
CLAUDE_PROJECT_DIR=./my-project

Codex 环境变量

变量名	说明	示例
`ANTHROPIC_API_KEY`	API 密钥	`sk-ant-xxx`
`CLAUDE_CONFIG_DIR`	配置目录	`~/.claude`
`CLAUDE_PROJECT_DIR`	项目目录	`./my-app`
`CLAUDE_THEME`	主题	`dark`
`CLAUDE_MODEL`	默认模型	`claude-3-opus`

自定义指令

您可以通过自定义指令来调整 Codex 的行为模式：

项目自定义指令

在 CLAUDE.md 中添加：

## 自定义指令

- 在修改前先阅读相关文件的完整内容
- 每次修改后运行测试确保功能正常
- 使用中文编写注释和文档
- 优先使用现有的组件和工具函数

会话自定义指令

在对话中使用：

请按照以下要求进行修改：
1. 保持代码风格一致
2. 添加必要的类型定义
3. 更新相关测试
4. 运行 lint 检查