Codex 提供丰富的配置选项，让你定制 Agent 的行为以适应不同的工作需求。
默认情况下 Codex App 会根据你的系统设置语言，如果没有可以通过 Settings（ 设置 ）：
选择 General（常规） 常规选项修改你需要的语言：
同样如果要中文改英文，勾选英文即可：
Codex App 的设置
打开方式：点击应用菜单中的设置（ Settings ），或按 Cmd + ,：
设置界面如下所示：
**常规（General）：**配置文件的打开方式、命令输出在对话线程中的显示量。还可设置多行提示需要 Cmd+Enter 确认，以及防止任务运行期间系统休眠。
**通知（Notifications）：**设置任务完成通知的触发时机，以及是否由应用主动请求系统通知权限。
**Agent 配置（Agent Configuration）：**App 中的 Codex Agent 与 IDE 和 CLI 扩展共享同一套配置。常用选项可在 App 内直接调整，高级选项需编辑 config.toml 文件（后文说明）。
**外观（Appearance）：**支持选择基础主题，调整强调色、背景色和前景色，以及更换 UI 字体和代码字体。可将自定义主题分享给他人。
**Codex 宠物（Codex Pets）:**可选的动态陪伴角色，路径：Settings（设置） > Appearance（外观） > Pets（宠物），可选择内置宠物或从本地 Codex 主目录加载自定义宠物。
操作方式：
- 在输入框中输入
/pet - 使用 Settings > Appearance 中的 Wake Pet 或 Tuck Away Pet
- 按
Cmd+K/Ctrl+K后运行同名命令
宠物悬浮窗可在使用其他应用时持续显示当前 Codex 工作状态（运行中 / 等待输入 / 待审查），并附有简短进度提示。
自定义宠物（创建流程）：
$skill-installer hatch-pet
安装后在命令菜单中选择 Force Reload Skills，再执行：
$hatch-pet create a new pet inspired by my recent projects
Git: 统一分支命名规范，配置是否启用强制推送（force push），并设置 Codex 自动生成提交信息（commit message）和 PR 描述时所用的提示语。
**环境：**可以查看项目目录及添加项目。
工作树： 利用 Git worktree 让 Codex 在同一项目中并行处理多个任务。
**浏览器使用（Browser Use）：**安装或启用内置 Browser 插件，管理网站白名单和黑名单。默认情况下，Codex 使用任何网站前都会先询问用户；将网站从黑名单移除后，Codex 将恢复询问行为。详见应用内浏览器文档。
**电脑操控（Computer Use）：**仅限 macOS。可查看桌面应用访问权限及相关偏好设置。如需撤销系统级权限，请前往 macOS 隐私与安全性 中修改屏幕录制或辅助功能权限。
**已归档的项目（Archived Threads）：**列出所有已归档的对话，显示日期和项目上下文。点击取消归档（ Unarchive） 可恢复指定线程。
配置文件位置
Codex 配置文件分层管理：
| 层级 | 路径 | 作用范围 |
|---|---|---|
| 用户级 | ~/.codex/config.toml | 全局默认配置 |
| 项目级 | .codex/config.toml | 项目特定配置 |
| 托管级 | 企业下发 | 企业统一配置 |
配置合并规则
配置按优先级合并：
- 托管配置优先级最高
- 项目配置覆盖用户配置
- 用户配置作为默认值
基础配置项
基础配置
# ~/.codex/config.toml
# 默认模型
model = "gpt-5.4"
# 推理强度
model_reasoning_effort = "medium" # minimal | low | medium | high | xhigh
# 推理摘要详细程度
model_reasoning_summary = "auto" # auto | concise | detailed | none
# 服务层级
service_tier = "flex" # flex | fast
# 审批策略
approval_policy = "suggest" # suggest | auto-edit | full-auto
AGENTS.md
AGENTS.md 是项目级的 Agent 指令文件，定义 Codex 在该项目中的行为规范。
文件发现顺序
- 读取全局
~/.codex/AGENTS.md - 从项目根目录向下搜索每个目录
- 更近目录的规则覆盖更远的
AGENTS.md 示例
项目 AGENTS.md
# 项目开发规范
## 技术栈
- 前端：React + TypeScript
- 后端：Python FastAPI
- 数据库：PostgreSQL
## 代码规范
- 使用 4 空格缩进
- 每行最多 100 字符
- 所有函数必须有类型注解
## 测试要求
- 新功能必须包含测试
- 使用 pytest 运行测试
## Git 提交
- 使用 Conventional Commits 格式
- 提交信息描述"为什么"
## Review guidelines
- Don't log PII
- Verify authentication middleware
- Check for SQL injection
子目录覆盖
可以在子目录放置 AGENTS.override.md：
子目录规则
# src/auth/ 模块规则
## 安全要求
- 所有密码必须 bcrypt 加密
- 添加审计日志
- 检查 SQL 注入
AGENTS.md 大小限制为 32 KiB，超过会被截断。
Skills（技能）
Skills 是可复用的自定义能力，封装常用任务逻辑。
技能目录位置
| 位置 | 路径 | 作用 |
|---|---|---|
| REPO | .agents/skills/ | 项目级技能 |
| USER | ~/.agents/skills/ | 用户级技能 |
| ADMIN | /etc/codex/skills/ | 系统级技能 |
| SYSTEM | 内置 | 官方预置技能 |
技能结构
skill-name/
├── SKILL.md # 技能定义（必需）
├── scripts/ # 可选脚本
├── references/ # 可选参考文档
└── assets/ # 可选资源
创建技能
技能定义
---
name: code-review-standard
description: 执行团队标准代码审查
---
# 代码审查标准
## 审查项目
1. 代码可读性
2. 潜在 Bug
3. 安全漏洞
4. 性能问题
5. 测试覆盖
## 输出格式
- 问题列表（按严重程度）
- 改进建议
- 评分（1-10）
技能触发
| 触发方式 | 示例 |
|---|---|
| 显式调用 | $skill-name 或 /skill-name |
| 隐式匹配 | 任务描述匹配技能 description |
Subagents（子代理）
Subagents 允许将复杂任务拆分给多个 Agent 并行处理。
内置代理类型
| 代理 | 功能 |
|---|---|
| default | 通用代理 |
| worker | 执行导向，适合实现和修复 |
| explorer | 探索导向，适合代码库分析 |
配置子代理
子代理配置
# ~/.codex/config.toml
[agents]
# 最大并行线程
max_threads = 6
# 最大嵌套深度
max_depth = 1
# 单任务超时
job_max_runtime_seconds = 1800
自定义代理
自定义代理
# ~/.codex/agents/reviewer.toml
name = "reviewer"
description = "专注代码审查和质量问题"
nickname_candidates = ["Reviewer", "QualityBot"]
developer_instructions = """
专注于代码质量审查：
- 检查代码风格一致性
- 发现潜在 Bug
- 评估测试覆盖
"""
Rules（规则）
Rules 定义命令执行策略，控制哪些命令可以自动执行。
规则文件
规则使用 Starlark 语言（类似 Python）：
规则定义
# ~/.codex/rules/default.rules
# 允许 Git 命令
prefix_rule(
pattern = ["git"],
decision = "allow",
justification = "Git commands are safe"
)
# 禁止 rm -rf /
prefix_rule(
pattern = ["rm", "-rf", "/"],
decision = "forbidden",
justification = "Prevent system damage"
)
# 询问 npm 命令
prefix_rule(
pattern = ["npm"],
decision = "prompt",
justification = "npm may modify dependencies"
)
决策类型
| 决策 | 行为 |
|---|---|
allow | 自动批准 |
prompt | 询问确认 |
forbidden | 禁止执行 |
Hooks（钩子）
Hooks 在特定事件时执行自定义脚本。
启用 Hooks
启用 Hooks
[features]
codex_hooks = true
Hook 事件
| 事件 | 触发时机 |
|---|---|
SessionStart | 会话启动 |
PreToolUse | 工具调用前 |
PostToolUse | 工具调用后 |
配置 Hook
Hook 配置
{
"hooks": [
{
"event": "PostToolUse",
"matcher": {
"toolName": "Bash"
},
"hooks": [
{
"type": "command",
"command": "echo 'Command executed'",
"timeout": 10
}
]
}
]
}
常见问题
Q: 配置修改后如何生效？
修改配置后需要重启 Codex 才能生效。
Q: AGENTS.md 应放在哪里？
项目根目录，或需要特殊规则的子目录。
Q: Skills 和 Rules 的区别？
Skills 定义任务执行逻辑，Rules 控制命令权限。
Q: 如何查看当前配置？
使用 /status 命令查看当前会话配置。
关于账号获取
官方订阅和 API 对国内用户都不太友好——海外卡、海外手机号、稳定的境外网络环境，每一项都是门槛。如果不想折腾，又想要接近官方的体验，可以看看 [Code80](code.ai80.vip/home)，真实订阅帐… API，换个 endpoint 就能直接用，省掉支付和网络两道坎，详情可以到官网了解：[code.ai80.vip](code.ai80.vip/home)。
Claude Code 安装与使用
在正式安装之前，先了解一下 Claude Code 有哪几种使用方式，选择最适合自己的方式入手。
| 方式 | 适合人群 | 优点 | 缺点 |
|---|---|---|---|
| Web 端 | 完全新手 | 无需安装，打开浏览器即可使用 | 功能相对有限，无法深度集成本地代码 |
| CLI（命令行） | 有一定基础的开发者 | 功能完整，集成度高，最接近设计初衷 | 需要熟悉命令行操作 |
| 编辑器集成（VS Code / Cursor 等） | 日常开发者 | 无缝融入已有工作流，不需要切换窗口 | 依赖插件和环境配置 |
选择建议：
- 如果你是完全新手，先访问 claude.ai/ 用 Web 端试试手感，熟悉 Claude 的对话方式
- 如果你想真正用于开发，直接学习 CLI（命令行），功能最完整
- 等 CLI 用熟之后，再根据需要考虑编辑器集成
目前 Claude Code 也提供了桌面版，可在以下地址下载：claude.com/download
本教程以 CLI 方式为主，因为它最稳定、最通用，也最接近 Claude Code 的设计初衷。
安装 Claude Code CLI
1、前置准备
在安装之前，你需要准备好以下两项：
① Claude 账号
- 访问 claude.ai 注册一个账号
- 如果你已经在使用 Claude 网页版聊天，说明账号已经有了，可以跳过这步
- 如果你打算使用国内大模型（如 DeepSeek、Minimax、GLM 等），可以暂时跳过账号注册，后文会介绍如何切换
② 命令行工具
- Mac / Linux：打开系统自带的 Terminal（终端）即可
- Windows：打开 PowerShell，或者安装并使用 WSL（Windows Subsystem for Linux）
2、使用官方脚本安装（推荐）
官方提供了一键安装脚本，根据你的系统选择对应的命令执行：
macOS、Linux、WSL：
curl -fsSL https://claude.ai/install.sh | bash
Windows PowerShell：
irm https://claude.ai/install.ps1 | iex
Windows CMD：
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
Homebrew:
brew install --cask claude-code
WinGet:
winget install Anthropic.ClaudeCode
安装完成后，验证是否安装成功：
claude --version
如果终端输出了版本号（如 1.x.x），说明安装成功:
2.1.81 (Claude Code)
3、使用 npm 安装（不推荐）
官方目前已不再推荐使用 npm 安装方式，建议优先使用上方的官方脚本。如果确实需要通过 npm 安装，请先确认已安装 Node.js：
node --version
如果输出了版本号（如 v18.17.0），说明已安装。如果提示命令不存在，请前往 nodejs.org 下载并安装。
确认 Node.js 可用后，执行以下命令安装 Claude Code：
npm install -g @anthropic-ai/claude-code
等待安装完成（可能需要几分钟），然后验证：
claude --version
4、更新 Claude Code
可以直接用以下命令更新：
claude install
或者：
claude update
Claude Code 在启动和运行时会自动检查更新，后台下载完成后，下次启动即生效。自动更新相关配置写在 settings.json 中：
实例
{
"autoUpdatesChannel": "stable" // 更新渠道：stable（稳定版，推荐）或 beta（测试版）
}
也可以在 Claude Code 内部通过 /config 命令进行配置。
如果你不需要自动更新，可以在 settings.json 的 env 中禁用：
实例
{
"env": {
"DISABLE_AUTOUPDATER": "1" // 设为 "1" 禁用自动更新，"0" 或删除该行则恢复自动更新
}
}
通过 Homebrew 或 WinGet 安装的 Claude Code 不支持自动更新，需要手动执行以下命令更新：
# macOS Homebrew brew upgrade claude-code #Windows WinGet winget upgrade Anthropic.ClaudeCode
5、常见安装问题排查
问题一：提示 npm command not found
- 原因：电脑上没有安装 Node.js
- 解决：前往 nodejs.org 下载安装 Node.js，安装完成后重新执行安装命令
问题二：提示 permission denied
-
原因：当前用户没有全局安装权限
-
解决（Mac / Linux）：在命令前加
sudo提升权限：sudo npm install -g @anthropic-ai/claude-code -
解决（Windows）：右键 PowerShell，选择"以管理员身份运行"，然后重新执行安装命令
问题三：安装速度很慢或卡住
- 原因：网络访问境外源速度慢
- 解决：添加
--registry参数切换到国内镜像源：npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com
终端推荐：如果你觉得系统默认终端体验一般，以下这些终端在使用 Claude Code 时体验更佳：
- WezTerm（跨平台）：wezterm.org/
- Alacritty（跨平台）：alacritty.org/
- Ghostty（Linux / macOS）：ghostty.org/
- Kitty（Linux / macOS）：github.com/kovidgoyal/…
卸载 Claude Code
根据你当初的安装方式选择对应的卸载命令。
1、官方脚本安装（原生安装）
删除 Claude Code 的可执行文件和版本文件：
macOS、Linux、WSL：
rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude
Windows PowerShell：
Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force
Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force
2、Homebrew 安装
brew uninstall --cask claude-code
3、WinGet 安装
winget uninstall Anthropic.ClaudeCode
4、npm 安装
npm uninstall -g @anthropic-ai/claude-code
5、删除配置文件（可选）
以上命令只卸载了可执行程序，配置文件和历史记录不会自动删除。如果你希望完全清除所有数据（包括设置、授权工具、MCP 服务器配置和会话历史），需要额外执行以下命令：
⚠️ 删除配置文件是不可恢复的操作，所有本地设置和历史记录将永久丢失，执行前请确认。
macOS、Linux、WSL：
# 删除全局用户设置和状态
rm -rf ~/.claude
rm ~/.claude.json
# 删除当前项目的本地设置（在项目目录中执行）
rm -rf .claude
rm -f .mcp.json
Windows PowerShell：
# 删除全局用户设置和状态
Remove-Item -Path "$env:USERPROFILE\.claude" -Recurse -Force
Remove-Item -Path "$env:USERPROFILE\.claude.json" -Force
# 删除当前项目的本地设置（在项目目录中执行）
Remove-Item -Path ".claude" -Recurse -Force
Remove-Item -Path ".mcp.json" -Force
登录 Claude Code
1、首次登录流程
在项目目录中启动 Claude Code：
claude
首次启动时，Claude Code 会引导你完成登录。你也可以在进入界面后手动输入登录命令：
/login
按照终端中的提示完成登录授权即可。登录后，凭据会保存在本地，下次启动无需重复登录。如果需要切换账号，重新执行 /login 即可。
2、支持的账号类型
你可以使用以下任意一种账号类型登录：
① Claude 订阅账号（推荐）
- Claude Pro：个人专业版
- Claude Max：最高级别订阅
- Claude Teams：团队版
- Claude Enterprise：企业版
② Claude Console 账号（API 访问）
- 通过 API 访问，使用预付费积分计费
- 适合开发者和需要程序化访问的场景
- 同一个邮箱可以同时拥有订阅账号和 Console 账号两种类型
3、自动创建工作区（Console 账号）
首次使用 Claude Console 账号认证 Claude Code 时，系统会自动在你的 Console 中创建一个名为 "Claude Code" 的工作区，用于：
- 集中跟踪所有 Claude Code 的 API 使用成本
- 便于管理组织内多人的 Claude Code 使用情况
启动第一次会话
1、在项目目录中启动
打开终端，先切换到你的项目目录，再启动 Claude Code。这样 Claude 才能读取你的项目文件，提供针对性的帮助：
cd /path/to/your/project
claude
2、欢迎界面
启动后，你会看到 Claude Code 的欢迎界面，包括当前会话信息、最近的对话记录和最新更新说明：
3、查看可用命令
在输入框中输入 /help 可以查看所有可用功能：
/help
输入 /resume 可以恢复之前中断的对话：
/resume
在输入框中直接输入 /，会弹出所有可用命令的补全列表：
详细的凭据管理信息可参考官方文档的 Credential Management 部分。
提出第一个问题
1、理解项目
进入项目目录启动 Claude Code 后，可以先让它分析你的代码库：
what does this project do?
Claude 会自动读取项目文件，并给出项目概要。
Claude Code 会根据需要自动读取文件——你不需要手动把文件内容复制粘贴到对话中，它会自己找到需要的上下文。
2、更多项目相关问题
你还可以询问更具体的信息：
what technologies does this project use?
where is the main entry point?
explain the folder structure
3、询问 Claude Code 的能力
也可以直接问 Claude 关于它自己能做什么：
what can Claude Code do?
how do I use slash commands in Claude Code?
can Claude Code work with Docker?
Claude 可以访问自己的文档，能够准确回答关于自身功能和特性的问题。
进行第一次代码修改
1、动手试一个简单任务
下面让 Claude Code 实际编写代码。我们创建一个测试目录，让它在 test.py 文件中添加一个 Hello World 函数：
cd runoob-test # 进入测试目录（没有则新建一个）
claude # 启动 Claude Code
进入界面后，输入：
在 test.py 文件中添加 hello world 函数
Claude Code 会展示建议的代码修改，并在执行前请求你的确认，选择 yes 后按回车即可应用：
2、Claude Code 的修改工作流
每次代码修改，Claude Code 都会按以下流程执行：
- 找到相关文件：自动在项目中定位需要修改的文件
- 展示建议的修改：以差异对比的形式展示将要做的改动
- 请求你的批准：执行前必须经过你的确认
- 执行编辑：确认后写入文件
你可以逐个审批每处修改，也可以在当前会话中开启"全部接受"模式批量确认。
使用 Git 功能
Claude Code 让 Git 操作变得像日常对话一样简单，直接用自然语言描述你想做的事即可。
1、基础 Git 操作
查看已修改的文件：
what files have I changed?
提交更改（Claude 会自动生成提交信息）：
commit my changes with a descriptive message
2、更复杂的 Git 操作
创建新分支：
create a new branch called feature/quickstart
查看最近的提交历史：
show me the last 5 commits
协助解决合并冲突：
help me resolve merge conflicts
修复 Bug 或添加功能
1、添加新功能
用自然语言描述你想要添加的功能，Claude Code 会找到合适的位置并实现它：
add input validation to the user registration form
2、修复现有问题
描述 Bug 现象，让 Claude 定位并修复：
there's a bug where users can submit empty forms - fix it
3、Claude Code 的问题处理流程
- 定位相关代码：在代码库中找到与问题相关的文件和函数
- 理解上下文：分析代码逻辑，理解问题的根本原因
- 实现解决方案：给出修改建议并展示 diff
- 运行测试：如果项目中存在测试，Claude 会尝试运行以验证修复效果
其他常见工作流
代码重构
refactor the authentication module to use async/await instead of callbacks
编写测试
write unit tests for the calculator functions
更新文档
update the README with installation instructions
代码审查
review my changes and suggest improvements
Claude Code 是你的 AI 结对编程伙伴。像跟一个有经验的同事交流一样跟它对话——描述你想实现什么，不用拘泥于特定命令格式，用自然语言表达即可，它会帮你找到最佳实现方式。
常用命令速查表
命令行命令（在终端中使用）
| 命令 | 功能 | 示例 |
|---|---|---|
claude | 启动交互模式（最常用） | claude |
claude "任务描述" | 执行一次性任务后退出交互模式 | claude "fix the build error" |
claude -p "查询内容" | 执行单次查询后立即退出（适合脚本集成） | claude -p "explain this function" |
claude -c | 继续当前目录的最近一次对话 | claude -c |
claude -r | 从历史中选择并恢复一次对话 | claude -r |
claude commit | 让 Claude 自动生成 Git 提交信息并提交 | claude commit |
claude update | 手动更新 Claude Code 到最新版本 | claude update |
claude --version | 查看当前安装的版本号 | claude --version |
交互模式内命令（在 Claude Code 界面中使用）
|
| 命令 | 功能 | 示例 |
|---|---|---|
/help | 显示所有可用命令和功能说明 | /help |
/login | 登录账号或切换到其他账号 | /login |
/resume | 从历史中恢复之前中断的对话 | /resume |
/clear | 清除当前对话历史，开始全新会话 | /clear |
/config | 查看和修改 Claude Code 配置 | /config |
exit 或 Ctrl+C | 退出 Claude Code，返回终端 | exit |
关于账号获取
官方订阅和 API 对国内用户都不太友好——海外卡、海外手机号、稳定的境外网络环境，每一项都是门槛。如果不想折腾，又想要接近官方的体验，可以看看 [Code80](code.ai80.vip/home)，真实订阅帐… API，换个 endpoint 就能直接用，省掉支付和网络两道坎，详情可以到官网了解：[code.ai80.vip](code.ai80.vip/home)。
