第九课：认证与配置命令

loginlogoutupdatecompletiondoctor

1. 概述

Codex CLI 提供了一套完整的认证、配置和诊断命令，帮助你管理 API 密钥、保持工具更新、配置 shell 自动补全，以及诊断常见问题。本课将详细讲解以下命令：

codex login / codex logout：认证管理
codex update：版本更新
codex completion：Shell 自动补全
codex doctor：系统诊断
codex features：功能列表
codex mcp：MCP 服务器管理
codex plugin：插件管理

2. `codex login`：登录认证

2.1 基本用法

# 交互式登录（推荐）
codex login

# 使用 API Key 直接登录
codex login --api-key sk-your-key-here

# 指定 provider 登录
codex login --provider openai

2.2 支持的认证方式

方式 1：OpenAI API Key

# 通过环境变量
export OPENAI_API_KEY=sk-your-key-here
codex login

# 通过参数
codex login --api-key sk-your-key-here

# 通过交互式输入（隐藏输入）
codex login
# 请输入 API Key: ************************

方式 2：ChatGPT 订阅

# 使用 ChatGPT Plus/Pro/Team 订阅
codex login --provider chatgpt

# 这会打开浏览器进行 OAuth 认证

方式 3：Azure OpenAI

# 使用 Azure OpenAI 服务
codex login --provider azure   --azure-endpoint https://your-resource.openai.azure.com   --azure-api-key your-azure-key   --azure-api-version 2024-02-15-preview

2.3 多 Provider 配置

# 登录多个 provider
codex login --provider openai --api-key sk-openai-key
codex login --provider azure --azure-endpoint https://...

# 查看已配置的 provider
codex login --list

# 切换默认 provider
codex login --provider openai --set-default

2.4 认证存储

认证信息存储在 ~/.codex/auth.json 中：

{
  "providers": {
    "openai": {
      "api_key": "sk-...",
      "default_model": "o4-mini"
    },
    "azure": {
      "endpoint": "https://...",
      "api_key": "...",
      "api_version": "2024-02-15-preview"
    }
  },
  "default_provider": "openai"
}

⚠️ 安全提示：

auth.json 文件权限应为 600（仅所有者可读写）
永远不要将 auth.json 提交到版本控制
建议使用环境变量或密钥管理工具存储 API Key

2.5 登录验证

# 验证当前登录状态
codex login --status

# 测试 API 连接
codex login --test

# 输出示例：
# ✅ Provider: openai
# ✅ API Key: 有效
# ✅ 模型: o4-mini 可用
# ✅ 配额: 剩余 $50.00

3. `codex logout`：退出登录

3.1 基本用法

# 退出当前 provider
codex logout

# 退出指定 provider
codex logout --provider openai

# 退出所有 provider
codex logout --all

3.2 清理认证数据

# 退出并删除本地认证数据
codex logout --purge

# 仅删除 API Key（保留其他配置）
codex logout --keep-config

3.3 退出后的状态

退出后，Codex 会：

清除内存中的 API Key
更新 auth.json（删除对应 provider 的凭证）
后续调用会提示需要重新登录

codex logout
# 已退出 openai provider
# 使用 'codex login' 重新登录

codex "测试"
# 错误：未登录。请先运行 'codex login'

4. `codex update`：版本更新

4.1 基本用法

# 检查更新
codex update --check

# 更新到最新版本
codex update

# 更新到指定版本
codex update --version 0.5.0

# 强制更新（即使已是最新）
codex update --force

4.2 更新渠道

# 使用稳定版（默认）
codex update --channel stable

# 使用测试版
codex update --channel beta

# 使用开发版
codex update --channel nightly

各渠道说明：

渠道	更新频率	稳定性	适用场景
`stable`	每 2-4 周	最稳定	生产环境
`beta`	每周	较稳定	提前体验新功能
`nightly`	每天	可能有问题	开发者测试

4.3 自动更新检查

Codex 默认在启动时检查更新，可通过配置禁用：

# 禁用自动检查
codex config set auto_update_check false

# 设置检查间隔（天）
codex config set update_check_interval 7

4.4 更新日志

# 查看最近的更新日志
codex update --changelog

# 查看当前版本和最新版本的差异
codex update --diff

5. `codex completion`：Shell 自动补全

5.1 基本用法

# 生成 Bash 补全脚本
codex completion bash

# 生成 Zsh 补全脚本
codex completion zsh

# 生成 Fish 补全脚本
codex completion fish

5.2 安装补全

Bash

# 方法 1：临时安装（当前会话有效）
eval "$(codex completion bash)"

# 方法 2：永久安装
codex completion bash > ~/.codex-completion.bash
echo 'source ~/.codex-completion.bash' >> ~/.bashrc
source ~/.bashrc

Zsh

# 方法 1：使用 oh-my-zsh
mkdir -p ~/.oh-my-zsh/custom/plugins/codex
codex completion zsh > ~/.oh-my-zsh/custom/plugins/codex/_codex
# 在 ~/.zshrc 中添加 codex 到 plugins 列表

# 方法 2：手动安装
codex completion zsh > ~/.codex-completion.zsh
echo 'source ~/.codex-completion.zsh' >> ~/.zshrc
source ~/.zshrc

Fish

# Fish 自动加载补全目录
codex completion fish > ~/.config/fish/completions/codex.fish
# 重新加载 Fish 配置
source ~/.config/fish/config.fish

5.3 补全功能

安装补全后，你可以：

# Tab 补全命令
codex <Tab>
# 输出：
# login    logout    resume    fork    archive    delete
# sessions    update    completion    doctor    features
# mcp    plugin    exec    ...

# Tab 补全参数
codex resume --<Tab>
# 输出：
# --last    --model    --sandbox    --help

# Tab 补全会话 ID
codex resume <Tab>
# 输出：
# session_abc123    session_def456    session_ghi789

6. `codex doctor`：系统诊断

6.1 基本用法

# 运行完整诊断
codex doctor

# 仅检查特定项目
codex doctor --check api
codex doctor --check config
codex doctor --check dependencies

6.2 诊断内容

codex doctor 会检查以下内容：

🔍 Codex CLI 诊断报告
═══════════════════════════════════════

📋 版本信息
  ✅ Codex CLI: v0.5.2
  ✅ Node.js: v20.10.0
  ✅ 操作系统: macOS 14.5

🔑 认证状态
  ✅ OpenAI API Key: 已配置
  ✅ API 连接: 正常
  ✅ 配额: 充足

⚙️ 配置检查
  ✅ 配置文件: ~/.codex/config.json 有效
  ✅ 认证文件: ~/.codex/auth.json 存在
  ⚠️ 会话目录: 156 个会话，建议清理

📦 依赖检查
  ✅ git: 2.43.0
  ✅ node: v20.10.0
  ✅ npm: 10.2.0
  ❌ docker: 未安装（可选）

🔧 工具链检查
  ✅ 终端: 可用
  ✅ 文件系统: 可读写
  ✅ 网络: 可访问 api.openai.com

💡 建议
  1. 运行 'codex sessions clean' 清理旧会话
  2. 考虑安装 Docker 以使用沙箱模式
  3. 当前使用 stable 渠道，可考虑 beta 获取新功能

6.3 自动修复

# 自动修复可修复的问题
codex doctor --fix

# 修复特定问题
codex doctor --fix permissions
codex doctor --fix config

6.4 诊断报告导出

# 导出诊断报告
codex doctor --output report.txt

# 导出为 JSON（用于自动化处理）
codex doctor --json > doctor_report.json

# 导出为 Markdown
codex doctor --markdown > doctor_report.md

7. `codex features`：功能列表

7.1 查看功能列表

# 列出所有功能
codex features

# 列出已启用的功能
codex features --enabled

# 列出实验性功能
codex features --experimental

7.2 功能输出示例

📦 Codex 功能列表
═══════════════════════════════════════

核心功能
  ✅ 交互模式 (interactive)
  ✅ 非交互模式 (exec)
  ✅ 沙箱模式 (sandbox)
  ✅ 会话管理 (sessions)
  ✅ 网页搜索 (web_search)

高级功能
  ✅ 图片理解 (vision)
  ✅ 文件编辑 (file_editing)
  ✅ 终端执行 (terminal)
  ✅ Git 集成 (git_integration)
  ⚠️ 浏览器自动化 (browser) - 需要安装 Playwright

实验性功能
  🔬 MCP 服务器 (mcp)
  🔬 插件系统 (plugins)
  🔬 多模型路由 (model_routing)
  🔬 语音输入 (voice_input)

7.3 功能管理

# 启用实验性功能
codex features enable browser

# 禁用功能
codex features disable voice_input

# 查看功能详情
codex features info browser

8. `codex mcp`：MCP 服务器管理

8.1 什么是 MCP

MCP（Model Context Protocol）是一个开放协议，允许 AI 模型与外部工具和数据源通信。通过 MCP，你可以扩展 Codex 的能力。

8.2 MCP 服务器管理

# 列出已配置的 MCP 服务器
codex mcp list

# 添加 MCP 服务器
codex mcp add filesystem npx @modelcontextprotocol/server-filesystem /path/to/dir

# 移除 MCP 服务器
codex mcp remove filesystem

# 测试 MCP 服务器连接
codex mcp test filesystem

8.3 常用 MCP 服务器

# 文件系统服务器
codex mcp add filesystem npx @modelcontextprotocol/server-filesystem ~/projects

# GitHub 服务器
codex mcp add github npx @modelcontextprotocol/server-github

# PostgreSQL 服务器
codex mcp add postgres npx @modelcontextprotocol/server-postgres postgresql://localhost/mydb

# Slack 服务器
codex mcp add slack npx @modelcontextprotocol/server-slack

8.4 MCP 配置文件

MCP 服务器配置存储在 ~/.codex/mcp.json：

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "/path/to/dir"],
      "env": {}
    },
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

9. `codex plugin`：插件管理

9.1 插件列表

# 列出已安装的插件
codex plugin list

# 列出可用的插件
codex plugin search

# 查看插件详情
codex plugin info <plugin-name>

9.2 插件安装与卸载

# 安装插件
codex plugin install @codex/plugin-prettier
codex plugin install @codex/plugin-eslint

# 卸载插件
codex plugin uninstall @codex/plugin-prettier

# 更新插件
codex plugin update @codex/plugin-eslint
codex plugin update --all

9.3 插件开发

# 创建插件模板
codex plugin create my-plugin

# 本地开发插件
codex plugin link ./my-plugin

# 发布插件
codex plugin publish ./my-plugin

插件目录结构：

my-plugin/
├── package.json
├── index.ts          # 入口文件
├── tools/            # 自定义工具
│   └── my-tool.ts
├── hooks/            # 生命周期钩子
│   └── on-start.ts
└── README.md

10. 其他配置命令

10.1 `codex config`：配置管理

# 查看所有配置
codex config list

# 获取配置值
codex config get model
codex config get sandbox.mode

# 设置配置值
codex config set model o4-mini
codex config set sandbox.mode workspace-write

# 重置配置
codex config reset model
codex config reset --all

10.2 `codex version`：版本信息

# 查看版本
codex version

# 详细版本信息
codex version --verbose

# 输出示例：
# Codex CLI v0.5.2
# Commit: abc123def456
# Built: 2026-06-28T10:00:00Z
# Runtime: Node.js v20.10.0
# OS: darwin arm64

10.3 `codex feedback`：反馈

# 提交反馈
codex feedback "希望增加批量文件编辑功能"

# 报告 bug
codex feedback --bug "在处理大文件时崩溃"

# 查看反馈历史
codex feedback --list

11. 综合示例

11.1 新用户首次设置

# 1. 登录
codex login

# 2. 检查系统状态
codex doctor

# 3. 安装自动补全
codex completion bash >> ~/.bashrc
source ~/.bashrc

# 4. 检查更新
codex update --check

# 5. 开始使用
codex "Hello, Codex!"

11.2 团队环境配置

# 1. 使用团队 API Key
codex login --api-key $TEAM_API_KEY

# 2. 配置团队默认设置
codex config set model gpt-4.1
codex config set sandbox.mode workspace-write

# 3. 安装团队推荐的 MCP 服务器
codex mcp add github npx @modelcontextprotocol/server-github

# 4. 安装团队插件
codex plugin install @codex/plugin-team-lint

11.3 故障排查流程

# 1. 运行诊断
codex doctor

# 2. 检查认证
codex login --status

# 3. 检查配置
codex config list

# 4. 查看版本
codex version --verbose

# 5. 如果问题持续，重置配置
codex config reset --all
codex login

12. 最佳实践

12.1 安全最佳实践

使用环境变量存储 API Key：不要硬编码在配置文件中
定期轮换 API Key：建议每 90 天更换一次
不要共享认证文件：每个人的 auth.json 应该独立
使用 codex doctor 定期检查：确保系统状态正常

12.2 配置最佳实践

使用 Profile 隔离不同项目：避免配置冲突
文档化团队配置：将推荐配置写入项目 README
使用 .codex/config.json 项目级配置：覆盖全局设置
定期运行 codex update：保持工具最新

12.3 补全最佳实践

所有 shell 都安装补全：提高效率
定期更新补全脚本：新版本可能有新命令
自定义补全规则：为常用命令添加别名

思考题

codex login 支持哪些认证方式？在团队环境中，你推荐使用哪种方式管理 API Key？
codex doctor 会检查哪些内容？如果诊断报告显示 API 连接失败，你会如何排查？
MCP 服务器的作用是什么？请列举三个实用的 MCP 服务器并说明它们的用途。
如何为 Bash、Zsh 和 Fish 三种 shell 安装自动补全？各自的安装步骤有什么区别？
如果你需要在一个新服务器上从零开始配置 Codex CLI，完整的步骤是什么？包括认证、配置、补全和诊断。