作者：闪大夫 | 2026年5月
本文聚焦技术实现，分享本地部署 AI 编程工具的完整路径及避坑经验。

---

前言

2026 年，开发者工具链正在发生一个明显的迁移：从浏览器端的 Chat 界面，转向终端里的 CLI 和桌面端的 Desktop App。

原因很实际：

上下文完整性：CLI 能直接读取整个代码仓库，理解文件间的关系，而不是让你手动粘贴片段

权限边界可控：本地运行的工具可以精确控制它访问哪些目录、执行哪些命令

工作流嵌入：在终端里写完需求直接生成代码、运行测试、提交 Git，不用切窗口

隐私与合规：部分场景下代码不能上传到第三方服务器，本地部署是硬需求

目前主流的两条路线：OpenAI Codex CLI 和 Anthropic Claude Code。本文不介绍概念，直接讲怎么装、怎么配、怎么避坑。

---

声明：这些工具都需要付费

Codex CLI 和 Claude Code 都可以本地部署运行，但调用模型本身需要付费，访问原文 ，查看 ChatGPT Plus 等 AI 服务订阅托管，适合需要稳定订阅又不想折腾境外支付的开发者。

---

一、OpenAI Codex CLI 部署与使用

1.1 安装

Codex CLI 是 OpenAI 官方推出的终端 AI 编程助手，当前基于 GPT-5-Codex 模型（GPT-5 的代码专用版本）。

# 前置依赖：Node.js 18+
node -v

# 全局安装
npm install -g @openai/codex

# 验证安装
codex --version

1.2 认证

# 交互式登录，弹出浏览器完成 OAuth
codex login

# 或直接设置 API Key（适合无头服务器 / 自动化流水线）
export OPENAI_API_KEY="your-key-here"
# 如用第三方兼容端点（如国内代理）
export OPENAI_BASE_URL="https://your-proxy-url/v1"

Codex 支持两种模式：

• ChatGPT 订阅账号登录：Plus / Pro 用户直接用订阅权益调用
• API Key 登录：按量计费，适合重度使用或自动化场景

1.3 核心用法

# 进入交互模式
codex

# 直接在当前 Git 仓库上下文中提问
codex "解释这个项目的目录结构"

# 指定模型
codex --model gpt-5-codex "重构 src/utils/request.ts，增加重试逻辑"

# 自动执行模式（跳过每次确认）
codex exec --full-auto "修复所有 ESLint 报错并运行测试"

# 无沙箱模式（最快，最危险）
codex exec --yolo "修复所有 src/ 下的 TODO"

# PR 代码审查
gh pr checkout 42
codex review --base origin/main

三个核心参数的区别：

参数	效果	适用场景
exec	单次执行，退出	一次性任务
--full-auto	自动执行，跳过沙箱确认	自动化流水线
--yolo	无沙箱，不做任何限制	快速原型，谨慎使用

1.4 自定义 Agent 配置

通过 .codex.yaml 定义专用 Agent：

# .codex.yaml
agents:
  code-reviewer:
    description: "代码审查 Agent，基于团队规范"
    prompt: |
      你是一个严格的代码审查者。检查以下内容：
      1. TypeScript 类型是否完整
      2. 是否有潜在的空指针
      3. 是否符合项目 ESLint 规则
      4. 函数复杂度是否合理
    model: gpt-5-codex
    approval: manual

1.5 Git Worktree 并行任务（Codex 独家功能）

# 创建独立 worktree
git worktree add -b fix/issue-78 /tmp/issue-78 main

# 并行执行修复
codex exec --full-auto "Fix issue #78: describe the bug" \
  --workdir /tmp/issue-78

Codex 强制要求在 Git 仓库中运行。如果想在临时目录测试：

cd $(mktemp -d) && git init && codex exec "Build a snake game"

---

二、Claude Code 部署与使用

2.1 两种形态

Anthropic 的 Claude Code 有两种使用方式：

Desktop App（桌面客户端）

• 下载地址：claude.ai/download
• 支持 macOS / Windows
• 图形界面，文件拖拽式上下文，MCP 深度集成

CLI（命令行，开发者预览）

• 安装：npm install -g @anthropic-ai/claude-code
• 在终端中直接对话，支持管道和脚本化

2.2 CLI 安装与认证

# 安装
npm install -g @anthropic-ai/claude-code

# 认证
claude auth login
# 或 API Key 认证（国内推荐）
claude auth login --console

# 环境变量方式（最省事）
export ANTHROPIC_API_KEY="your-key-here"
export ANTHROPIC_BASE_URL="https://api.minimaxi.com/anthropic"  # 如用 MiniMax

# 验证状态
claude auth status --text

claude auth status --text 输出示例：

Provider: anthropic (firstParty)
API Key: set (last 4: xxxx)
Model: claude-opus-4.7

2.3 两种运行模式

Print 模式（单次非交互，推荐日常使用）

claude -p "Add error handling to src/api.py" --max-turns 10

这是最干净的集成方式：一条命令、一个任务、执行完退出。不需要 PTY，不需要处理交互对话框。

适合：

• 集成到编辑器（PyCharm External Tool、VS Code Task）
• CI/CD 流水线
• 自动化脚本
• 从 Python subprocess 调用

核心参数：

参数	作用
--max-turns N	限制 Agent 循环次数，防止失控
--allowedTools Read,Edit,Bash	白名单工具，只给必要的权限
--dangerously-skip-permissions	跳过所有确认提示（全自动模式）
--output-format json	结构化输出，便于程序解析
--model sonnet	指定模型，可选 sonnet/opus/haiku

带权限跳过的自动化命令：

claude -p "Refactor the database layer in src/db/" \
  --dangerously-skip-permissions \
  --allowedTools Read,Edit,Bash \
  --max-turns 15

JSON 输出格式：

{
  "type": "result",
  "subtype": "success",
  "result": "Refactoring complete. 3 files modified.",
  "session_id": "75e2167f-xxxx-xxxx",
  "num_turns": 7,
  "total_cost_usd": 0.034,
  "duration_ms": 8432,
  "stop_reason": "end_turn"
}

Interactive 模式（多轮对话）

claude
# 或带初始任务
claude "帮我重构认证模块"

进入全功能 TUI，适合复杂功能从零设计、代码审查讨论、探索性编程。

交互模式必须配合 tmux，否则无法从外部程序监控和发送输入：

# 启动 tmux session
tmux new-session -d -s claude -x 140 -y 40

# 在 tmux 中启动 Claude
tmux send-keys -t claude 'cd /path/to/project && claude' Enter

# 等待启动完成后发送任务
sleep 5
tmux send-keys -t claude 'Refactor the auth module' Enter

# 查看进度
tmux capture-pane -t claude -p -S -30

# 退出
tmux send-keys -t claude '/exit' Enter

2.4 管道模式 — Claude CLI 的杀手锏

# 分析错误日志
cat error.log | claude -p "分析这些错误日志，给出修复建议" --max-turns 1

# 审查最近变更
git diff HEAD~3 | claude -p "审查这三天的代码变更，写一份 changelog" --max-turns 1

# 指定权限级别
claude --permission ask "运行 npm test 并修复失败的用例"

2.5 MCP 协议集成（Claude 独有优势）

Claude Code 支持 MCP（Model Context Protocol），允许 AI 连接外部工具和数据源。

// ~/.claude/mcp_config.json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-github"],
      "env": {
        "GITHUB_TOKEN": "$GITHUB_TOKEN"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://localhost/mydb"
      }
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-playwright"]
    }
  }
}

配置完成后，Claude 可以直接：

• 读取 GitHub Issues / PRs
• 查询数据库结构并生成 SQL
• 启动浏览器进行端到端测试

---

三、在 PyCharm 中集成 Claude Code

3.1 PyCharm 2024+（官方插件）

PyCharm 2024 及以上版本支持 Claude Code 官方 JetBrains 插件：

1. Settings → Plugins → 搜索 “Claude”
2. 安装后点击 “Connect”
3. 完成 OAuth 授权

3.2 PyCharm 2021-2023（External Tool 方式）

官方插件不兼容，只能用 External Tool 曲线集成。

第一步：创建 bat 包装脚本

在 C:\Users\Public\claude-p.bat 创建：

@echo off
set ANTHROPIC_API_KEY=your-api-key-here
set ANTHROPIC_BASE_URL=https://api.minimaxi.com/anthropic
D:\npm-global\claude.cmd -p "Understand the requirements. Analyze the file at: %~f1. Then write all necessary code changes." --dangerously-skip-permissions

关键点：%~f1 是 bat 参数扩展，获取当前文件完整路径。PyCharm 2025.3 的 $FILE_PATH$ 宏存在已知 bug，会传递字面字符串 $FILE_PATH$ 而不是实际路径，%~f1 是唯一可靠的绕过方式。

第二步：添加 External Tool

1. Settings → Tools → External Tools → 点击 +
2. 配置：
   • Name: Claude Code
   • Program: C:\Users\Public\claude-p.bat
   • Arguments: $FILE_PATH$（手动输入，不要复制粘贴，$ 符号在复制中容易丢失）
   • Working directory: $FileDir$

第三步：验证

打开任意 .py 文件，点击 Tools → External Tools → Claude Code，Claude Code 会读取文件并开始分析。

---

四、VS Code 中集成

Claude Code

VS Code 官方扩展市场有 “Claude Code” 扩展（Anthropic 出品）：

1. Cmd+Shift+P → “Claude: Set API Key”
2. 输入 API Key
3. Cmd+Shift+P → “Claude: Open Claude Code”

Codex

VS Code 官方扩展市场有 “Codex” 扩展（OpenAI 出品），安装后配置 API Key 即可。

---

五、CI/CD 中使用

Claude Code 在 GitHub Actions

- name: Run Claude Code review
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  run: |
    npm install -g @anthropic-ai/claude-code
    claude -p "Review this PR for bugs and security issues" \
      --dangerously-skip-permissions \
      --allowedTools Read,Bash \
      --max-turns 10

Codex 在 GitLab CI

run-code-review:
  script:
    - npm install -g @openai/codex
    - codex exec --full-auto "Review the changes in this MR"

---

六、选择建议

你的场景	推荐工具
在终端里快速改 bug	Codex CLI
审查整个项目的架构	Claude Code
CI/CD 自动代码审查	Codex CLI
AI 直连数据库/GitHub/Jira	Claude Code（MCP）
复杂多步骤重构	Claude Code
快速原型生成 + 即时反馈	Codex CLI

两个工具可以共存：

• 用 Claude Code 做需求分析和架构设计（长上下文 + MCP 集成）
• 用 Codex CLI 做具体代码生成和自动修复（沙箱执行 + 多文件操作）

两者都可以接入 Git Hook，在 commit 前自动审查。

---

七、常见问题与避坑

Q1：Claude Code 提示 “Failed to connect to api.anthropic.com”

原因：Claude Code v2.1.138 的已知 bug——交互模式会硬编码 api.anthropic.com，忽略 ANTHROPIC_BASE_URL 环境变量。

解法：使用 -p 打印模式代替交互模式，环境变量在 -p 模式下正常生效。

Q2：Codex 报错 “Not a git repository”

Codex 强制要求在 Git 仓库中运行。如果想在临时目录测试：

cd $(mktemp -d) && git init && codex exec "Build a snake game"

Q3：Claude Code 权限确认弹窗导致自动化脚本卡住

使用 --dangerously-skip-permissions 可以跳过所有确认。但注意：此参数在 Windows 上对非 ASCII 内容（中文）有额外的安全检查，中文代码建议先用模板文件方式绕过。

Q4：国内网络无法访问官方 API

两个方案：

1. 使用国内兼容 API（MiniMax、硅基流动等），通过 ANTHROPIC_API_KEY + ANTHROPIC_BASE_URL 配置
2. 配置代理工具（如 Clash），设置 HTTPS_PROXY 环境变量

Q5：Claude Code 写完代码后忘记提交

设置 Hook，在 Claude 完成时自动提交：

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "git add -A && git commit -m 'Claude Code: auto-commit on task completion'"
      }]
    }]
  }
}

作者：闪大夫 | 2026年5月 | 本文是我的本地 AI 工具链系列，欢迎交流实践中的问题。