Claude Code 部署使用指南：从0到精通

Claude Code：终端内的AI编程助手本文全面介绍Anthropic推出的终端AI编程工具Claude Code，涵盖其核心功能、安装配置和高级用法。作为一款对话式CLI工具，Claude Code不仅能理解项目架构，还能完成从代码编写到Git提交的完整工作流。文章详细对比了与Copilot等工具的区别，提供系统要求、定价方案和最新Opus 4.7模型特性说明。内容包含安装指南、认证配置、

图小城

610人浏览 · 2026-04-25 17:17:20

图小城 · 2026-04-25 17:17:20 发布

摘要： Claude Code 是 Anthropic 推出的终端内 AI 编程助手，自发布以来迅速成为开发者社区最受关注的 AI 编程工具之一。本文从实际使用出发，涵盖安装部署、认证配置、IDE 集成、MCP 扩展、CI/CD 集成、SDK 编程式调用等完整内容，助你快速上手并深入掌握 Claude Code。

–

前言：我为什么推荐 Claude Code
1. Claude Code 是什么
2. 与同类工具对比
3. 系统要求与定价
4. 安装指南
5. 认证配置
6. 接入第三方大模型 API
7. 30 分钟快速上手
8. 交互模式详解
9. 核心命令速查
10. IDE 集成
11. 配置文件体系
12. CLAUDE.md——项目记忆文件
13. 自定义斜杠命令
14. MCP 集成
15. Hooks 钩子系统
16. CI/CD 自动化集成
17. Claude Agent SDK
18. 最佳实践与工作流
19. 安全建议
20. 常见问题排查
21. 总结与展望

前言：我为什么推荐 Claude Code

在 AI 编程工具井喷的今天，GitHub Copilot、Cursor、Cline、Augment 等工具层出不穷。但经过深度使用，我发现 Claude Code 是唯一一个真正让我产生"这是开发伙伴，而不是代码补全器"感觉的工具。

三个核心体验差异：

它能理解架构，而不只是文件：让它"重构认证模块"，它会先花时间阅读所有相关文件、理解依赖关系，然后给出完整的重构方案——而不是只改当前文件。
它能完成完整工作流：从分析需求 → 写代码 → 跑测试 → 修 Bug → Git 提交 → 创建 PR，一气呵成。
它的上下文窗口极大：能记住整个项目的对话历史，跨文件修改时不会顾此失彼。

这篇文章是我在实际使用中积累的经验总结，希望能帮助你少走弯路。

1. Claude Code 是什么

Claude Code 是 Anthropic 公司开发的终端内 AI 编程助手（CLI 工具）。与传统的 IDE 插件不同，它直接运行在终端中，具备以下核心能力：

核心能力一览

能力	描述
代码库理解	自动分析项目结构、依赖关系和架构模式
文件编辑	精确的字符串替换编辑 + 整文件写入 + 创建新文件
终端执行	运行构建、测试、lint、安装依赖等任意 shell 命令
Git 管理	自动创建分支、提交、推送、创建 Pull Request
子代理系统	通过 Sub-agents 并行处理多个独立任务
网页搜索	实时获取最新技术文档和资料
图片理解	支持截图输入，用于 UI 开发对比

与 GitHub Copilot / Cursor 的本质区别

Copilot / Cursor 是"补全器"——在你输入时给出代码建议。
Claude Code 是"代理"——你下达任务，它自主规划并执行全程。

它更像是你身边一位能独立工作的资深开发搭档，而非一个被动的提示工具。

2. 与同类工具对比

维度	Claude Code	GitHub Copilot	Cursor	Cline/Augment
运行方式	CLI（终端）	IDE 插件	IDE（基于 VSCode）	IDE 插件
交互方式	对话式，自然语言驱动	Tab 补全 + Chat	内联编辑 + Chat	对话式
上下文理解	整个项目 + Git 历史	当前文件 + 相邻 Tab	整个项目	整个项目
代理能力	强（完整工作流）	弱（主要是补全）	中（内联编辑）	中（依赖外部 API）
自定义扩展	MCP + Hooks + 自定义命令	有限	有限	有限
CI/CD 集成	原生 GitHub Action	GitHub Actions	无原生	有限
SDK	Python + TypeScript	无	无	无
底层模型	Claude（最强编码模型）	GPT-4o/Copilot 模型	多模型可选	多模型可选
定价	$20-200/月	$10-39/月	$20/月	按 API 用量

适用场景建议

个人开发者 / 小团队：Claude Code Pro ($20/月) 性价比极高
高强度编码 / 大项目：Max5 ($100/月) 或 Max20 ($200/月)
企业团队：Team 方案 + MCP 集成 + 统一 CLAUDE.md 规范
CI/CD 自动化：Agent SDK + GitHub Actions 原生支持

3. 系统要求与定价

系统要求

组件	最低要求	推荐配置
Node.js	18.0+	20 LTS
Python	3.10+（仅 Agent SDK）	3.12+
操作系统	macOS / Linux / WSL / Windows 10+	macOS 15+ / Ubuntu 24.04+
Git	2.30+	2.40+
认证	API Key 或 Claude.ai 订阅	Claude Pro/Max 订阅

Windows 用户注意：虽然支持 Windows，但在 WSL 中运行体验更流畅。部分 MCP 服务在原生 Windows 上需要额外配置（见第 13 节）。

定价方案对比

方案	月费	Token 额度	模型访问	适合场景
Pro	$20	基础	有限 Opus	日常编码、中小项目
Max5	$100	5x 基础	完整 Opus	高强度编码、大型项目
Max20	$200	20x 基础	完整 Opus	近乎自主开发、企业级
Team	按席位	按方案	按方案	团队协作、统一管理

当前可用模型（2026 年 4 月）

模型	代号	定价 (输入/输出)	上下文	定位	推荐场景
Opus 4.7	`opus`	$5/$25 每百万 token	1M	🔥 最新旗舰	复杂架构、长周期任务、深度调试
Sonnet 4.6	`sonnet`	$3/$15 每百万 token	200K	均衡之选	日常首选，编辑/重构/测试
Haiku 4.5	`haiku`	$1/$5 每百万 token	200K	极速响应	简单查询、快速修改

Opus 4.7 新特性（2026 年 4 月 16 日发布）

Claude Opus 4.7 是 Anthropic 最新旗舰模型，相比 Opus 4.6 有显著提升：

基准测试	Opus 4.6	Opus 4.7	提升幅度
SWE-bench Verified	80.8%	87.6%	+6.8%
CursorBench	58%	70%	+12%
长周期任务	基准	+36%	大幅提升
结构生物学	30.9%	74.0%	+43.1%

关键变化：

思考模式新增 xhigh 档位：介于 high 和 max 之间，性价比更高
全新 tokenizer：相同文本产生的 token 数比旧版多 1.0-1.35 倍（注意成本估算）
更强的指令遵循：可能需要重新优化复杂 prompt
图片分辨率提升：最高 2,576px（约 3.75MP），是之前的 3 倍

在 Claude Code 中启用 Opus 4.7：

{
  "env": {
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-7"
  }
}

# 或启动时指定
claude --model opus

# 会话中切换并选择思考强度
/model
# 然后选择 Opus → 选择 effort level（low/medium/high/xhigh/max）

实战建议：日常用 Sonnet，遇到复杂问题时切换到 Opus 4.7。不要在简单任务上浪费 Opus 的配额。

4. 安装指南

方法 A：官方安装脚本（推荐首选）

这是最省心的方式，自动处理依赖和环境变量：

# 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

方法 B：包管理器安装

# Homebrew（macOS）
brew install --cask claude-code

# WinGet（Windows）
winget install Anthropic.ClaudeCode

方法 C：npm 全局安装

适用于已经安装了 Node.js 的环境：

npm install -g @anthropic-ai/claude-code

安装后验证与更新

# 验证安装
claude --version
# 输出类似：v1.0.xx

# 查看帮助（确认命令可用）
claude --help

# 更新到最新版本
claude update

# 日常建议每周更新一次

各平台安装坑点

Linux 常见问题：

# 如果提示权限不足
sudo npm install -g @anthropic-ai/claude-code

# 如果 node 版本过低，先用 nvm 升级
nvm install 20
nvm use 20

Windows 常见问题：

# PowerShell 执行策略限制
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

# 然后重新运行安装命令
irm https://claude.ai/install.ps1 | iex

macOS 常见问题：

# 如果 Homebrew 找不到 cask
brew update && brew upgrade
brew install --cask claude-code

5. 认证配置

两种认证方式

Claude Code 支持 OAuth 订阅登录和 API Key 两种认证方式。

重要优先级规则：如果同时设置了两者，API Key 优先于 OAuth 订阅。这可能导致你产生 API 费用而非使用订阅额度！

方式 A：OAuth 订阅登录（推荐 Pro/Max 用户）

# 在终端输入
claude login

# 浏览器会自动打开 Anthropic 登录页面
# 完成登录后，终端显示 "Authentication successful"
# 凭证缓存在 ~/.claude/settings.json

验证登录状态：

# 在 Claude Code REPL 中输入
/status

# 输出示例：
# Account: yourname@email.com (Pro)
# Auth method: OAuth
# Connection: ✅ Connected

方式 B：API Key（推荐 API 付费用户）

环境变量方式（推荐）：

# macOS / Linux — 添加到 ~/.bashrc 或 ~/.zshrc
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxxxxx"

# Windows PowerShell — 添加到 $PROFILE
$env:ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxxxxx"

# Windows CMD
setx ANTHROPIC_API_KEY "sk-ant-api03-xxxxxxxxxxxxx"

settings.json 方式（备选）：

// ~/.claude/settings.json
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-ant-api03-xxxxxxxxxxxxx",
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com"
  }
}

API Key 在 console.anthropic.com 的 API Keys 页面创建。

认证方式确认

运行 /status 可以清晰看到当前使用的认证方式：

/status
# 输出：
# ✅ Claude Code v1.0.xx
# Auth: OAuth (user@email.com)  或  Auth: API Key (sk-ant...xxxx)
# Model: claude-sonnet-4-6
# 会话 cost: $0.023

企业环境：AWS Bedrock / Google Vertex AI

# AWS Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION="us-west-2"
# 还需要 AWS IAM 权限

# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/sa-key.json"

6. 接入第三方大模型 API

Claude Code 默认使用 Anthropic 官方 API，但它也支持通过修改 API 端点来接入其他大模型。本章详细介绍 DeepSeek、OpenAI、Gemini、OpenRouter 等配置方法。

🔥 省钱攻略速览：

最省钱方案：NVIDIA 免费 API（6.7 节）—— 零成本，约 100 个免费模型，含 Qwen-Coder、DeepSeek V3.2 等顶级编码模型

性价比方案：DeepSeek 直连（6.2 节）—— 便宜、简单、Anthropic 原生兼容

多模型方案：Claude Code Router（6.4 节）—— 高峰期用免费 API 省钱，复杂任务切回 Claude

6.1 三种接入路径

路径 A：原生 Anthropic 兼容（直接配置）
  Claude Code ──→ 第三方 Anthropic 兼容 API ──→ 大模型
  适用：DeepSeek、智谱 GLM、MiniMax、Moonshot、OpenRouter

路径 B：代理转换（需要中间层）
  Claude Code ──→ 协议转换代理 ──→ OpenAI 兼容 API ──→ 大模型
  适用：OpenAI、Gemini、Ollama、OneAPI、本地模型

路径 C：免费 API（NVIDIA 提供）
  Claude Code ──→ free-claude-code/Claudex ──→ NVIDIA NIM
  适用：零成本日常开发，国内直连

核心原理：Claude Code 只讲 Anthropic Messages API 协议（/v1/messages），不能直接调用 OpenAI 格式（/v1/chat/completions）。路径 B 需要一个翻译层把 Anthropic 协议转成目标 API 协议。

6.2 路径 A：直连 DeepSeek（零代理配置）

DeepSeek 官方提供了 Anthropic 兼容端点，这是最简单的第三方接入方式：

// ~/.claude/settings.json
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-your-deepseek-api-key",
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_MODEL": "deepseek-chat",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-reasoner",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-chat",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-chat",
    "API_TIMEOUT_MS": "600000"
  }
}

使用效果：

对比维度	官方 Claude API	DeepSeek API
工具调用成功率	~95-98%	~85-90%
Diff 编辑准确率	优化	可能有 20-30% 重试率
上下文窗口	200K-1M	64K
费用（每百万 token）	$3-25	¥1-4
适用场景	所有任务	日常编码、简单任务

注意：DeepSeek 仅支持 64K 上下文，长会话需要更频繁地使用 /compact 压缩。

多配置切换技巧（v1.0.61+）：

# 创建 DeepSeek 专属配置
cat > ~/.claude/settings-deepseek.json << 'EOF'
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-your-deepseek-key",
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_MODEL": "deepseek-chat",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-reasoner",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-chat",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-chat"
  }
}
EOF

# 使用 DeepSeek 启动
claude --settings ~/.claude/settings-deepseek.json

6.3 其他原生 Anthropic 兼容提供商

以下提供商都原生支持 Anthropic 格式，配置方式同上（只需换 ANTHROPIC_BASE_URL）：

提供商	ANTHROPIC_BASE_URL	推荐模型	特点
DeepSeek	`https://api.deepseek.com/anthropic`	`deepseek-chat`, `deepseek-reasoner`	性价比最高
智谱 GLM	`https://open.bigmodel.cn/api/anthropic`	`glm-4.5`	国产，中文优化
MiniMax	`https://api.minimax.io/anthropic`	`MiniMax-M2`	长上下文
Moonshot	`https://api.moonshot.cn/anthropic`	`kimi-k2-turbo-preview`	长文档处理
OpenRouter	`https://openrouter.ai/api`	`anthropic/claude-sonnet-4`	多模型网关
302.AI	`https://api.302.ai`	`gemini-2.5-pro`	国内友好

关键提醒：ANTHROPIC_BASE_URL 不要加 /v1 后缀。Claude Code 会自动追加 /v1/messages。写 https://api.deepseek.com/anthropic/v1 会变成 /v1/v1/messages 导致 404。

6.4 路径 B：Claude Code Router（推荐代理方案）

对于 OpenAI、Gemini、Ollama 等 OpenAI-format API，需要使用代理进行协议转换。Claude Code Router 是目前最成熟的方案。

安装：

npm install -g @anthropic-ai/claude-code
npm install -g @musistudio/claude-code-router

配置文件 ~/.claude-code-router/config.json：

{
  "APIKEY": "your-auth-key-for-the-proxy",
  "PROXY_URL": "http://127.0.0.1:7890",
  "LOG": true,
  "API_TIMEOUT_MS": 600000,
  "Providers": [
    {
      "name": "openai",
      "api_base_url": "https://api.openai.com/v1/chat/completions",
      "api_key": "sk-openai-xxx",
      "models": ["gpt-4o", "gpt-4o-mini"],
      "transformer": { "use": ["openai"] }
    },
    {
      "name": "deepseek",
      "api_base_url": "https://api.deepseek.com/chat/completions",
      "api_key": "sk-ds-xxx",
      "models": ["deepseek-chat", "deepseek-reasoner"],
      "transformer": {
        "use": ["deepseek"],
        "deepseek-chat": { "use": ["tooluse"] }
      }
    },
    {
      "name": "openrouter",
      "api_base_url": "https://openrouter.ai/api/v1/chat/completions",
      "api_key": "sk-or-v1-xxx",
      "models": [
        "google/gemini-2.5-pro-preview",
        "anthropic/claude-sonnet-4",
        "openai/gpt-4o"
      ],
      "transformer": { "use": ["openrouter"] }
    },
    {
      "name": "ollama",
      "api_base_url": "http://localhost:11434/v1/chat/completions",
      "api_key": "ollama",
      "models": ["qwen2.5-coder:latest", "deepseek-coder-v2:latest"]
    }
  ],
  "Router": {
    "default": "deepseek,deepseek-chat",
    "think": "deepseek,deepseek-reasoner",
    "longContext": "openrouter,google/gemini-2.5-pro-preview",
    "longContextThreshold": 60000,
    "background": "ollama,qwen2.5-coder:latest"
  }
}

启动和使用：

# 启动路由器（后台运行代理）
ccr start

# 在 Claude Code 中动态切换模型
/model openrouter,openai/gpt-4o
/model deepseek,deepseek-chat
/model openai,gpt-4o-mini

# 查看路由器状态
ccr status

# 一键启动（代理 + Claude Code）
ccr code

Router 智能路由说明：

"Router": {
  "default": "deepseek,deepseek-chat",                    // 默认模型
  "think": "deepseek,deepseek-reasoner",                  // 需要深度思考时自动切换
  "longContext": "openrouter,google/gemini-2.5-pro-preview", // 上下文超过 60K 时切换
  "longContextThreshold": 60000,                          // 触发长上下文切换的阈值
  "background": "ollama,qwen2.5-coder:latest"              // 后台任务使用本地模型省钱
}

6.5 路径 B 替代方案对比

工具	类型	支持后端	成熟度	推荐场景
Claude Code Router	npm 代理	DeepSeek, OpenAI, Gemini, OneAPI, Ollama, NVIDIA	⭐⭐⭐	首选，功能最全
free-claude-code	Python 代理	NVIDIA NIM（专为免费 API）	⭐⭐⭐	🔥 NVIDIA 免费 API 首选
LiteLLM	Python 代理	100+ 模型	⭐⭐⭐	需要广泛 API 兼容时
Claudex	CLI 分支	NVIDIA, 多内置提供者	⭐⭐	一键式免费使用
Bifrost	本地代理	20+ 提供商	⭐⭐	完整 Anthropic 兼容
claude-bridge	Node.js 拦截	OpenAI, Gemini, Ollama	⭐⭐	轻量级，无需单独进程
cc-manager	配置管理器	9 种预设模板	⭐⭐	快速切换配置

LiteLLM 快速配置（备选）

pip install litellm

# litellm_config.yaml
model_list:
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: sk-openai-xxx
  - model_name: deepseek-v3
    litellm_params:
      model: deepseek/deepseek-chat
      api_key: sk-ds-xxx

# 启动代理
litellm --config litellm_config.yaml --port 4000

# 连接 Claude Code
export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_AUTH_TOKEN="sk-1234"
claude

6.6 自定义模型选择器

通过环境变量自定义 /model 命令中的可用模型：

{
  "env": {
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-7",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-chat",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "gpt-4o-mini",
    "CLAUDE_CODE_SUBAGENT_MODEL": "deepseek-chat",
    "ANTHROPIC_CUSTOM_MODEL_OPTION": "gpt-4o",
    "ANTHROPIC_CUSTOM_MODEL_OPTION_NAME": "GPT-4o (via Router)",
    "ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION": "OpenAI GPT-4o through proxy"
  }
}

模型变量说明：

环境变量	作用
`ANTHROPIC_DEFAULT_OPUS_MODEL`	`/model` 中 Opus 选项对应的实际模型 ID
`ANTHROPIC_DEFAULT_SONNET_MODEL`	`/model` 中 Sonnet 选项对应的实际模型 ID
`ANTHROPIC_DEFAULT_HAIKU_MODEL`	`/model` 中 Haiku 选项对应的实际模型 ID
`CLAUDE_CODE_SUBAGENT_MODEL`	子代理使用的模型
`ANTHROPIC_CUSTOM_MODEL_OPTION`	自定义模型 ID（添加到选择器）
`ANTHROPIC_CUSTOM_MODEL_OPTION_NAME`	自定义模型显示名称
`CLAUDE_CODE_MAX_OUTPUT_TOKENS`	最大输出 token 数

Shell 别名快速切换：

# 添加到 ~/.bashrc 或 ~/.zshrc
alias claude-ds='ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic" ANTHROPIC_AUTH_TOKEN="sk-ds-xxx" ANTHROPIC_MODEL="deepseek-chat" claude'
alias claude-gpt='ANTHROPIC_BASE_URL="https://api.openai.com" ANTHROPIC_AUTH_TOKEN="sk-oai-xxx" ANTHROPIC_MODEL="gpt-4o" claude'
alias claude-gl='ANTHROPIC_BASE_URL="https://open.bigmodel.cn/api/anthropic" ANTHROPIC_AUTH_TOKEN="xxx" ANTHROPIC_MODEL="glm-4.5" claude'

6.7 路径 C：NVIDIA 免费 API（🚀 零成本接入，强烈推荐）

🔥 特别推荐：这是目前性价比最高的 Claude Code 使用方式——完全免费、不限总量、国内直连。 NVIDIA 在 build.nvidia.com 上开放了约 100 个免费大模型 API 端点，涵盖国内外主流模型，包括阿里 Qwen-Coder、智谱 GLM、DeepSeek V3.2、MiniMax M2.7、Kimi K2 等顶级编码模型。只需注册账号就能无限调用（限速不限量）。

平台概览

项目	详情
平台地址	https://build.nvidia.com/explore/discover
API Base URL	`https://integrate.api.nvidia.com/v1`
免费模型数	约 100 个可用端点（总共 190+ 模型）
速率限制	每分钟 40 次请求（不限总量，不绑卡，永久免费）
网络	🇨🇳 国内直连，无需 VPN
API 格式	OpenAI 兼容（需代理转换才能在 Claude Code 中使用）
注册方式	邮箱注册 → 手机验证（支持 +86） → 生成 API Key → 过期时间选"Never Expire"

💡 重要提示：API Key 生成后只显示一次，务必立即保存！建议用 Gmail/Outlook 等域名邮箱注册，避免 QQ/微信快捷登录可能的权限问题。

🏆 NVIDIA 免费编码模型完整列表（2026 年 4 月最新）

第一梯队：顶级编码模型

这些模型在 SWE-bench、Aider 等编码基准测试中表现优异，适合复杂开发任务。

模型 ID	参数量	上下文	亮点
`qwen/qwen3-coder-480b-a35b-instruct`	480B (35B 激活)	256K	🔥 阿里通义千问专用代码模型，支持 Agentic Coding + 浏览器工具调用，代码能力最强
`deepseek-ai/deepseek-v3.2`	685B	128K	🔥 DeepSeek V3 最新版，稀疏注意力 + 集成 Agentic 工具，推理能力出色
`moonshotai/kimi-k2-instruct`	MoE	256K	🔥 Moonshot 编程强模型，超长上下文 256K，支持大规模代码分析
`mistralai/devstral-2-123b`	123B	256K	Mistral 代码专用模型，深度推理，擅长复杂算法
`minimaxai/minimax-m2.7`	2300B (100B 激活)	—	🔥 MiniMax 最新旗舰，SWE-bench Pro 56.2%，工具调用/Agent 能力出色

第二梯队：强力编码模型

综合表现优秀，适合日常开发和通用编程任务。

模型 ID	参数量	亮点
`z-ai/glm-4.7`	—	智谱 GLM-4.7，多语言编程助手，社区口碑好
`z-ai/glm-5.1`	744B	智谱最新旗舰，开源 MIT 许可，综合能力强
`mistralai/mistral-large-3`	675B	Mistral 通用 MoE 旗舰，多语言支持优秀
`meta/llama-4-maverick`	MoE	Meta 最新多模态模型，通用+代码双优
`stepfun-ai/step-3.5-flash`	200B	阶跃星辰开源推理引擎，速度型
`nvidia/nemotron-3-super-120b-a12b`	120B (12B 激活)	NVIDIA 自研旗舰，推理效率高
`ibm/granite-code`	—	IBM 代码专用模型，企业级稳定性

第三梯队：轻量/实用模型

适合简单任务、快速查询、低延迟场景。

模型 ID	亮点
`microsoft/phi-4-mini`	微软轻量级推理模型，速度极快
`google/gemma-4-27b-it`	Google 最新 Gemma 4 系列，轻量高效
`meta/llama-3.3-70b-instruct`	Llama 70B 经典，均衡稳定
`qwen/qwen3-235b-a22b`	通义千问 235B MoE，适合复杂推理
`deepseek-ai/deepseek-r1`	DeepSeek 深度推理专用，有思考链输出

🎯 Claude Code 编码推荐优先级：

复杂任务 → qwen3-coder-480b 或 deepseek-v3.2

Agent/工具调用 → minimax-m2.7

长上下文分析 → kimi-k2-instruct (256K)

日常编码 → glm-4.7 或 mistral-large-3

快速轻量 → phi-4-mini 或 gemma-4-27b-it

方案 A：free-claude-code 代理（推荐）

这是目前最成熟的 NVIDIA → Claude Code 方案：

# 1. 克隆项目
git clone https://github.com/Alishahryar1/free-claude-code.git
cd free-claude-code

# 2. 配置环境变量（选择你想要的模型）
cat > .env << 'EOF'
NVIDIA_NIM_API_KEY="nvapi-your-key-here"
# 推荐模型（按需选择一个）
MODEL="nvidia_nim/qwen/qwen3-coder-480b-a35b-instruct"
# MODEL="nvidia_nim/deepseek-ai/deepseek-v3.2"
# MODEL="nvidia_nim/minimaxai/minimax-m2.7"
# MODEL="nvidia_nim/moonshotai/kimi-k2-instruct"
# MODEL="nvidia_nim/z-ai/glm-4.7"
EOF

# 3. 安装依赖并启动代理
uv sync
uv run uvicorn server:app --host 0.0.0.0 --port 8082

Claude Code 配置：

// ~/.claude/settings-nvidia.json
{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:8082",
    "ANTHROPIC_AUTH_TOKEN": "freecc"
  }
}

# 使用 NVIDIA 免费 API 启动
claude --settings ~/.claude/settings-nvidia.json

架构说明：

Claude Code ──Anthropic 协议──→ free-claude-code (:8082) ──OpenAI 协议──→ NVIDIA NIM
                                                                       (integrate.api.nvidia.com)

代理自动处理：

协议转换（Anthropic ↔ OpenAI）
思考标签解析（<think> → 结构化 thinking blocks）
工具调用解析（文本格式 → 结构化 tool_use）
请求优化（拦截本地无关查询节省配额）
速率限制（40 RPM 限流 + 429 自动退避重试）

方案 B：Claudex（一键式，免配置）

如果觉得手动搭代理太麻烦，可以用 Claudex——内置 NVIDIA 支持的 Claude Code 分支：

# 安装
npm install -g @john2026/cluadex

# 配置环境变量
export NVIDIA_API_KEY="nvapi-your-key"
export NVIDIA_MODEL="qwen/qwen3-coder-480b-a35b-instruct"

# 直接使用
cluadex

方案 C：Claude Code Router 集成 NVIDIA

在 Claude Code Router 中添加 NVIDIA 提供者，支持免费模型和付费模型的混合路由：

// ~/.claude-code-router/config.json 中添加
{
  "Providers": [
    {
      "name": "nvidia",
      "api_base_url": "https://integrate.api.nvidia.com/v1/chat/completions",
      "api_key": "nvapi-your-key",
      "models": [
        "qwen/qwen3-coder-480b-a35b-instruct",
        "deepseek-ai/deepseek-v3.2",
        "minimaxai/minimax-m2.7",
        "moonshotai/kimi-k2-instruct",
        "z-ai/glm-4.7",
        "mistralai/devstral-2-123b"
      ],
      "transformer": { "use": ["openai"] }
    }
  ],
  "Router": {
    "default": "nvidia,qwen/qwen3-coder-480b-a35b-instruct",
    "background": "nvidia,microsoft/phi-4-mini"
  }
}

# 动态切换模型
ccr start && ccr code
# 在 Claude Code 中：/model nvidia,deepseek-ai/deepseek-v3.2

⚠️ 注意事项与最佳实践

项目	说明
⚡ 速度	免费 API 高峰期可能较慢，大模型（>200B）可能超时需重试
🔢 频率限制	40 RPM 硬限制，个人开发足够，不适合生产环境/CI/CD
🎯 模型选择	复杂任务用 `qwen3-coder-480b`/`deepseek-v3.2`，日常用 `glm-4.7`，轻量用 `phi-4-mini`
📊 稳定性	`qwen3-coder-480b`、`glm-4.7`、`kimi-k2-instruct` 社区反馈最稳定
🚫 不要用 `/model`	模型在代理配置中指定，不在 Claude Code 内切换（Router 方案除外）
🔑 密钥安全	API Key 仅显示一次，务必立即保存；过期时间选 “Never Expire”
📧 注册建议	优先用域名邮箱注册，支持 +86 手机验证

💡 总结：NVIDIA 免费 API 是目前 Claude Code 用户的最佳"白嫖"方案。100 个免费模型中，qwen3-coder-480b、deepseek-v3.2、minimax-m2.7、kimi-k2-instruct 是编码场景的四大王牌，配合 free-claude-code 代理即可零成本享受 Claude Code 的完整功能。

7. 30 分钟快速上手

第一次使用，建议按以下步骤体验：

第一步：进入项目

cd your-project
claude

第二步：生成项目记忆文件

/init

Claude 会自动分析代码库结构、依赖、框架，生成 CLAUDE.md。这个过程通常需要 1-2 分钟。

第三步：尝试第一个任务

帮我找到项目里所有 TODO 注释，列成一个清单

Claude 会使用 Grep 工具搜索代码库并返回结果。

第四步：做一个代码修改

在 src/utils/ 下创建一个 formatDate.ts，实现日期格式化工具函数，支持多种格式字符串

Claude 会：

检查 src/utils/ 目录是否存在
查看项目中是否已有类似工具
创建文件并实现功能
使用 Edit 工具精确写入代码

第五步：提交代码

提交这些更改，commit message 用英文

Claude 会：

运行 git status 确认变更
运行 git diff 查看差异
自动生成合理的 commit message
执行 git add 和 git commit

快速上手要点

你想做什么	怎么说
分析代码	“分析这个模块的设计，有什么可以改进的地方”
修复 Bug	“运行测试，找出失败原因并修复”
添加功能	“添加一个 API 端点，支持分页查询”
重构	“把这个类拆分成两个，单一职责原则”
写测试	“为这个模块写单元测试，覆盖边界情况”
代码审查	`/review`
查看花费	`/cost`
切换模型	`/model`
清空对话	`/clear`

8. 交互模式详解

Claude Code 有四种交互模式，掌握切换方式是高效使用的关键。

模式对比

模式	进入方式	Claude 能做什么	需要确认	适用场景
交互模式（REPL）	默认 `claude`	读写文件 + 执行命令 + Git	✅ 每次文件变更需确认	日常开发（最常用）
自动接受模式	`Shift+Tab`	同上	❌ 无需确认，自主操作	批量修改、信任的任务
计划模式	两次 `Shift+Tab`	只读 + 分析 + 提案	❌ 不写代码	前期探索、方案设计
打印模式	`claude -p "提示"`	只读分析	❌ 非交互	CI/CD、脚本、快速查询

REPL 模式实战

# 基本启动
claude

# 带初始提示启动
claude "帮我在项目里找到所有未使用的 import"

# 恢复上次会话
claude -c

# 指定模型启动
claude --model opus

# 限制工具调用次数（防止循环）
claude --max-turns 20

# 添加额外工作目录
claude --add-dir ../shared-lib

# 调试模式
claude --verbose

打印模式实战（-p）

打印模式适合脚本化、管道处理：

# 代码审查
claude -p "审查这个文件的潜在 bug" < src/api/handler.ts

# 日志分析
cat /var/log/app.log | claude -p "分析错误日志，找出最频繁的错误类型"

# 生成文档
cat package.json | claude -p "分析依赖关系，生成项目依赖说明文档"

# 结合 gh CLI 进行 PR 审查
gh pr diff | claude -p "审查这个 PR 的变更，关注性能和安全问题"

# JSON 格式输出（适合自动化处理）
claude -p "列出项目所有 API 端点" --output-format json

模式切换流程图

默认 REPL 模式（人工确认）
    │
    ├── Shift+Tab → 自动接受模式（AI 自主执行）
    │       └── Shift+Tab → 回到 REPL 模式
    │
    ├── 两次 Shift+Tab → 计划模式（只读提案）
    │       └── 两次 Shift+Tab → 回到 REPL 模式
    │
    └── Ctrl+C → 强制终止当前操作

9. 核心命令速查

斜杠命令完整列表

命令	功能	使用频率
`/help`	列出所有可用命令	⭐⭐⭐
`/clear`	清除上下文，重置对话	⭐⭐⭐
`/compact [指令]`	压缩上下文，保留关键信息	⭐⭐⭐
`/model`	切换模型（Sonnet ↔ Opus ↔ Haiku）	⭐⭐⭐
`/cost`	查看当前会话花费	⭐⭐⭐
`/status`	查看认证、版本、连接状态	⭐⭐
`/init`	自动生成 CLAUDE.md	⭐⭐
`/memory`	编辑 CLAUDE.md	⭐⭐
`/review`	审查当前分支变更	⭐⭐
`/permissions`	查看/调整工具权限	⭐⭐
`/add-dir`	添加额外工作目录	⭐
`/config`	打开配置面板	⭐
`/doctor`	健康检查诊断	⭐
`/pr_comments`	查看 PR 评论	⭐
`/sessions`	管理历史会话	⭐
`/ide`	检查 IDE 连接状态	⭐
`/vim`	切换 Vim 键位	⭐
`/terminal-setup`	配置 Shift+Enter	⭐
`/mcp`	MCP 服务器管理	⭐

键盘快捷键

快捷键	功能	记忆要点
`Esc` ×1	打断 Claude 当前回复	想让它"停"
`Esc` ×2	回到对话开头	“从头开始”
`Ctrl+C`	强制终止	紧急停止
`Shift+Tab` ×1	切换自动接受	“自动模式”
`Shift+Tab` ×2	切换计划模式	“计划模式”
`Alt+T`	开启扩展思考	“Think”
`Ctrl+O`	文件选择器	“Open”
`#`	保存指令到 CLAUDE.md	“记住这个”

10. IDE 集成

VS Code（官方支持）

安装：

方式一：在 VS Code 集成终端运行 claude，自动检测并安装

方式二：扩展商店搜索 Anthropic.claude-code 手动安装

要求： VS Code ≥ 1.98.0，Node.js ≥ 18

核心体验：

功能	说明
🔀 Diff 查看器	并排对比 Claude 的建议编辑，语法高亮，逐块接受/拒绝
⌨️ 快速启动	`Cmd+Esc` (Mac) / `Ctrl+Esc` (Win/Linux)
📋 选区共享	编辑器选中的代码自动传给 Claude
🔍 诊断集成	VS Code Problems 面板的错误对 Claude 可见
📑 标签页感知	Claude 知道打开的文件，优先关注活跃文件
@ 文件引用	`@file` 引用支持自动补全

JetBrains IDE（Beta 支持）

安装： Marketplace 搜索 “Claude Code [Beta]”

支持的 IDE： IntelliJ IDEA、PyCharm、WebStorm、GoLand、Android Studio 等

前置条件：

# 必须先全局安装 CLI
npm install -g @anthropic-ai/claude-code
# 安装后完全重启 IDE

注意事项（经常踩坑）：

# 如果 IDE 找不到 claude 命令（用 nvm/asdf/mise 的用户）
# 解决办法：找到 claude 的实际路径
which claude
# 输出：/home/user/.nvm/versions/node/v20.11.0/bin/claude

# 然后在 JetBrains 设置 → Claude Code → CLI Path 中填入这个路径

远程开发（JetBrains Gateway）： 插件必须安装在远程主机上，不是本地客户端。

VS Code vs JetBrains 对比

维度	VS Code	JetBrains
集成方式	原生图形扩展	CLI 包装 + IDE diff 查看器
成熟度	🟢 官方 GA	🟡 Beta
安装体验	⭐⭐⭐ 自动检测	⭐⭐ 需手动配置
Diff 体验	并排高亮	JetBrains 原生 diff
上下文分享	诊断 + 选区 + Tab	基础上下文
推荐度	首选	等待 GA

11. 配置文件体系

两级目录结构

# 项目级（提交到 Git，团队共享）
your-project/
├── CLAUDE.md                   # 团队编程规范
├── CLAUDE.local.md             # 个人覆盖（gitignore）
└── .claude/
    ├── settings.json           # 权限 + Hooks（提交）
    ├── settings.local.json     # 个人权限覆盖（gitignore）
    ├── .mcp.json               # MCP 服务配置（提交）
    ├── rules/                  # 模块化规则
    ├── commands/               # 自定义命令
    ├── skills/                 # 自动技能
    └── hooks/                  # Hook 脚本

# 用户级（不提交，全局生效）
~/.claude/
├── settings.json               # 个人全局设置
├── CLAUDE.md                   # 个人全局指令
├── commands/                   # 个人命令
├── keybindings.json            # 键盘绑定
└── projects/                   # 会话历史

settings.json 完整参考

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(npm test *)",
      "Bash(npx prisma *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Read",
      "Write",
      "Edit",
      "Grep",
      "Glob"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force *)",
      "Bash(git reset --hard *)",
      "Bash(curl *)",
      "Bash(wget *)",
      "Read(.env)",
      "Read(.env.*)",
      "Read(*secret*)",
      "Read(*credential*)",
      "Read(*.pem)",
      "Read(*.key)"
    ]
  },
  "env": {
    "NODE_ENV": "development",
    "DEBUG": "claude:*"
  }
}

配置合并优先级

优先级从低到高：

1. /etc/claude-code/settings.json      # 企业 IT 强制策略（不可覆盖）
        ↓ 被以下覆盖
2. ~/.claude/settings.json              # 用户全局默认
        ↓ 被以下覆盖
3. <project>/.claude/settings.json      # 项目团队设置
        ↓ 被以下覆盖
4. <project>/.claude/settings.local.json # 个人本地覆盖（gitignore）

核心原则：deny 规则是确定性的，AI 模型无法绕过。对不可逆操作（rm -rf、force push），永远用 deny 规则锁定，不要指望 CLAUDE.md 中的文字提示。

.gitignore 必须添加

# Claude Code 个人文件
CLAUDE.local.md
.claude/settings.local.json
.claude/agent-memory-local/

12. CLAUDE.md——项目记忆文件

CLAUDE.md 是 Claude Code 的核心配置文件，每次会话启动自动读取。写得好不好，直接影响 Claude 对你项目的理解程度。

最佳实践示例

# 项目概述
这是一个电商后台管理系统，使用 React 19 + TypeScript + Ant Design 构建。

## 技术栈
- 框架：React 19 + Vite
- 语言：TypeScript (strict mode)
- UI 库：Ant Design 5.x
- 状态管理：Zustand
- 路由：React Router v6
- HTTP：Axios + React Query
- 测试：Vitest + React Testing Library
- 包管理：pnpm

## 项目结构
- src/components/ — 通用 UI 组件
- src/features/ — 按业务模块组织（auth/, orders/, products/）
- src/hooks/ — 自定义 Hook
- src/api/ — API 调用层
- src/stores/ — Zustand store
- src/utils/ — 工具函数
- src/types/ — TypeScript 类型定义

## 编码规范
- 使用函数组件 + Hooks，禁止 class 组件
- API 调用统一使用 src/api/request.ts 中的 request 实例
- 新增 API 接口必须在 src/types/api.ts 中定义类型
- 所有表单使用 Ant Design Form + 自定义校验规则
- 文件命名：组件用 PascalCase，工具用 camelCase
- 组件文件放在对应 feature 目录下，不要放在 src/components/

## 测试要求
- 新增组件必须有渲染测试
- 工具函数必须有单元测试
- 涉及表单校验的需要测试边界情况

## 常用命令
- pnpm dev — 启动开发服务器 (localhost:3000)
- pnpm build — 生产构建
- pnpm test — 运行测试（Vitest）
- pnpm test -- --coverage — 测试覆盖率报告
- pnpm lint — ESLint 检查
- pnpm typecheck — TypeScript 类型检查

自动生成与手动优化

# 第一步：自动生成
/init
# Claude 分析代码库后生成基础 CLAUDE.md

# 第二步：手动补充
/memory
# 在编辑器中添加：
# - 团队的编码风格偏好
# - 特殊的架构决策
# - 禁止使用的模式

高级用法

@include 拆分大文件：

# CLAUDE.md 主文件
@.claude/rules/coding-standards.md
@.claude/rules/api-conventions.md
@.claude/rules/testing-requirements.md

CLAUDE.local.md 个人覆盖：

# CLAUDE.local.md（不提交到 Git）
# 优先使用中文回复
# 每次修改后自动运行 pnpm typecheck

# 快捷键： 在会话中按 #，Claude 会把当前对话中的重要指令自动追加到 CLAUDE.md。

13. 自定义斜杠命令

在 .claude/commands/ 下创建 .md 文件，文件名即命令名。

示例 1：代码审查命令

.claude/commands/review.md：

description: 审查当前分支的完整 diff，检查代码质量

## 变更文件
!`git diff --name-only main...HEAD`

## 完整 Diff
!`git diff main...HEAD`

请逐文件审查：
1. 是否有未处理的边界情况
2. 是否有潜在的 SQL 注入或 XSS 风险
3. 是否有 N+1 查询性能问题
4. 错误处理是否完整
5. 是否需要更新测试

最后给出合并建议：✅ 可合并 / ⚠️ 建议修改 / ❌ 不可合并

使用时在 REPL 中输入 /project:review。

示例 2：带参数的 Issue 修复

.claude/commands/fix-issue.md：

description: 拉取 GitHub Issue 内容并尝试修复
argument-hint: [issue-number]

## Issue 内容
!`gh issue view $ARGUMENTS --json title,body,labels,comments`

请根据 Issue 描述定位问题代码，给出修复方案并实施。
修改完成后，commit message 中引用 "Fixes #$ARGUMENTS"。

使用时：/project:fix-issue 42

命令位置与作用域

位置	前缀	可见范围
`.claude/commands/`	`/project:commandname`	项目级
`~/.claude/commands/`	`/user:commandname`	用户全局

! 语法：自定义命令中 !`command` 会实际执行 shell 命令并将输出注入到 Claude 的上下文，让 Claude 看到真实的实时数据。

14. MCP 集成

MCP（Model Context Protocol） 是连接 Claude 与外部世界的桥梁——文件系统、数据库、浏览器、GitHub 等。

快速添加 MCP 服务

# 添加 GitHub MCP
claude mcp add --scope project github -- npx -y @modelcontextprotocol/server-github

# 添加文件系统 MCP
claude mcp add --scope project fs -- npx -y @modelcontextprotocol/server-filesystem /path/to/project

# 添加浏览器自动化（Playwright）
claude mcp add --scope project browser -- npx @playwright/mcp@latest

# 列出所有 MCP 服务
claude mcp list

# 查看某个服务详情
claude mcp get github

# 移除服务
claude mcp remove github

.mcp.json 配置详解

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
      }
    },
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

Windows 上的 MCP 配置

Windows 用户需要额外包装命令：

{
  "mcpServers": {
    "filesystem": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "D:/projects"]
    },
    "github": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${env:GITHUB_TOKEN}"
      }
    }
  }
}

实用 MCP 服务推荐

服务	用途	推荐度
github	管理 Issue、PR、仓库	⭐⭐⭐
filesystem	安全读写文件	⭐⭐⭐
playwright	浏览器自动化测试	⭐⭐⭐
postgres	数据库查询与分析	⭐⭐
puppeteer	网页抓取与截图	⭐⭐
brave-search	网络搜索	⭐⭐
sequential-thinking	复杂推理	⭐
slack	开发通知	⭐

15. Hooks 钩子系统

Hooks 在生命周期事件发生时确定性执行（零 AI 参与），配置在 settings.json 的 hooks 字段。

实用 Hook 示例

示例 1：每次文件写入后自动 lint 并格式化：

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "npx eslint --fix $CLAUDE_FILE_PATH && npx prettier --write $CLAUDE_FILE_PATH"
      }]
    }]
  }
}

示例 2：会话开始检查环境：

{
  "hooks": {
    "SessionStart": [{
      "hooks": [{
        "type": "command",
        "command": "node -v && npm -v && npx tsc --noEmit --version && echo '✅ Ready'"
      }]
    }]
  }
}

示例 3：阻止危险 Git 操作：

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'rm -rf|git push.*--force|git reset.*--hard'; then echo '❌ 不允许此操作' && exit 1; fi"
      }]
    }]
  }
}

示例 4：完成后发送通知：

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "notify-send 'Claude Code' '任务处理完成' || true"
      }]
    }]
  }
}

Hook 事件速查

分类	事件	说明
生命周期	`SessionStart`, `SessionEnd`	会话开始/结束
用户交互	`UserPromptSubmit`	用户提交提示
工具使用	`PreToolUse`, `PostToolUse`, `PostToolUseFailure`	工具执行前中后
权限	`PermissionRequest`, `PermissionDenied`	权限请求/拒绝
AI 响应	`Stop`	Claude 完成响应
子代理	`SubagentStart`, `SubagentStop`	子代理启停
上下文	`PreCompact`, `PostCompact`	上下文压缩
通知	`Notification`	发送通知前
环境	`FileChanged`, `CwdChanged`	文件/目录变更
任务	`TaskCreated`, `TaskCompleted`	任务生命周期

16. CI/CD 自动化集成

GitHub Actions PR Review

name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize, reopened]
  issue_comment:
    types: [created]

jobs:
  review:
    # 仅在 PR 事件或 @claude 评论时触发
    if: |
      github.event_name == 'pull_request' ||
      (github.event_name == 'issue_comment' &&
       contains(github.event.comment.body, '@claude'))
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      issues: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Claude Code Review
        uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "/review"
          claude_args: "--max-turns 10 --model sonnet"

GitLab CI

# .gitlab-ci.yml
claude-review:
  image: node:20-alpine
  only:
    - merge_requests
  before_script:
    - npm install -g @anthropic-ai/claude-code
  script:
    - |
      gh pr diff ${CI_MERGE_REQUEST_ID} | \
      claude -p "审查这个 MR 的代码变更" \
        --model sonnet \
        --max-turns 5 \
        --output-format json > review.json
    - cat review.json
  artifacts:
    paths:
      - review.json

非交互式集成模式

# 最简模式 — 适合脚本和流水线
claude -p "分析 $FILE 的代码质量" \
  --max-turns 5 \
  --output-format json \
  --allowedTools "Read,Grep,Glob"

# 限定只读工具 — 安全模式下使用
claude -p "搜索所有未使用的依赖" \
  --allowedTools "Read(npm ls),Bash(npm ls *)"

17. Claude Agent SDK（编程式调用）

安装

# Python SDK
pip install claude-agent-sdk

# TypeScript SDK
npm install @anthropic-ai/claude-agent-sdk

Python 示例：单次查询

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    messages = []
    async for msg in query(
        prompt="分析项目中的循环依赖问题",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Bash"],
            permission_mode="acceptEdits",
            model="sonnet",
            max_turns=10,
        ),
    ):
        messages.append(msg)

    # 获取最终结果
    result = messages[-1].result if messages else "无结果"
    print(result)

asyncio.run(main())

Python 示例：多轮对话

import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

async def main():
    async with ClaudeSDKClient(options=ClaudeAgentOptions(
        permission_mode="acceptEdits",
        model="sonnet",
        max_turns=15,
    )) as client:

        # 第一轮：探索
        await client.query("分析认证模块的架构")
        async for msg in client.receive_response():
            if hasattr(msg, "result"):
                print(f"[分析结果] {msg.result}")

        # 第二轮：执行（Claude 记住上一轮的上下文）
        await client.query("根据刚才的分析，重构认证模块以支持 JWT")
        async for msg in client.receive_response():
            if hasattr(msg, "assistant"):
                print(msg.assistant)

asyncio.run(main())

TypeScript 示例

import { query, ClaudeAgentOptions } from "@anthropic-ai/claude-agent-sdk";

async function main() {
  for await (const msg of query({
    prompt: "列出项目中所有未使用的导出",
    options: {
      allowedTools: ["Read", "Glob", "Grep"],
      permissionMode: "acceptEdits",
      model: "sonnet",
      maxTurns: 8,
    },
  })) {
    if ("result" in msg) {
      console.log(msg.result);
    }
  }
}

main();

SDK 权限模式对比

模式	值	行为	安全级别
默认审批	`"default"`	通过 `canUseTool` 回调自定审批逻辑	高
自动编辑	`"acceptEdits"`	自动批准文件编辑，其他需确认	中
完全绕过	`"bypassPermissions"`	所有操作无需确认	仅用于 CI/沙箱

18. 最佳实践与工作流

上下文管理三原则

1. 不相关任务之间 → /clear（完全重置）
2. 上下文长但有用 → /compact（压缩保留要点）
3. /clear 之前 → /memory（保存重要发现到 CLAUDE.md）

标准开发工作流

流程 A：新功能开发（探索→规划→实现→提交）

┌─────────────────────────────────────────────────────┐
│ 1. 探索阶段（计划模式）                             │
│    "阅读认证相关文件，只需要解释，先不写代码"       │
│    → Claude 分析架构，解释现有模式                  │
├─────────────────────────────────────────────────────┤
│ 2. 规划阶段（计划模式）                             │
│    "根据分析结果，设计实现方案"                     │
│    → Claude 给出 DB 变更、API 设计、文件清单         │
├─────────────────────────────────────────────────────┤
│ 3. 编码阶段（自动接受模式）                         │
│    "按照方案实施，先从数据库 schema 开始"            │
│    → Claude 逐步创建/修改文件                       │
├─────────────────────────────────────────────────────┤
│ 4. 提交阶段                                         │
│    确认变更 → "创建提交" → "创建 PR"                │
└─────────────────────────────────────────────────────┘

流程 B：Bug 修复

1. "运行测试套件，列出所有失败的测试"
2. "分析每个失败测试的根因"
3. "修复代码，使所有测试通过"（切换到自动接受模式）
4. "修复后再次运行全部测试确认"
5. 确认无误后提交

流程 C：代码审查

1. 切换到目标分支
2. 输入 /review
3. Claude 分析 diff，逐文件给出审查意见
4. 根据意见决定是否修改

进阶技巧总结

技巧	说明
打断重定向	按 `Esc` 一次让 Claude 换方向，不重新开始
并行工作	用 `git worktrees` 在不同功能上同时跑多个 Claude 实例
管道输入	`cat logs.txt \| claude -p "分析"` 处理大量文本数据
URL 引用	直接贴文档链接，Claude 自动抓取读取
子代理分解	复杂问题拆成独立子任务并行处理
先计划后执行	复杂任务先用计划模式设计方案，确认后再实施
保持更新	`claude update` 每周一次

19. 安全建议

分层安全策略

第一层：settings.json deny 规则（确定性，不可绕过）
    ├── 阻止危险命令：rm -rf, git push --force, curl
    ├── 阻止读取敏感文件：.env, *secret*, *credential*
    └── 阻止修改关键配置

第二层：Hooks 钩子（确定性，实时拦截）
    ├── PreToolUse 拦截：检查命令是否包含危险模式
    ├── PostToolUse 审计：记录所有文件修改日志
    └── SessionEnd 清理：删除临时凭证

第三层：CLAUDE.md 指导（概率性，行为偏好）
    ├── 编码规范
    ├── 架构约束
    └── 操作约定

安全配置模板

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(pnpm *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git add *)",
      "Bash(git commit *)",
      "Bash(node *)",
      "Bash(tsc *)",
      "Read",
      "Write",
      "Edit",
      "Grep",
      "Glob"
    ],
    "deny": [
      "Bash(rm *)",
      "Bash(sudo *)",
      "Bash(curl *)",
      "Bash(wget *)",
      "Bash(git push *)",
      "Bash(git reset *)",
      "Bash(git checkout -- *)",
      "Bash(gh pr merge *)",
      "Bash(docker rm *)",
      "Bash(kubectl delete *)",
      "Read(.env*)",
      "Read(*id_rsa*)",
      "Read(*.pem)",
      "Read(*secret*)",
      "Read(*credential*)",
      "Read(*token*)"
    ]
  }
}

CI 环境特别提醒

# ⚠️ 在 CI 中锁定 Action 版本到具体 SHA
- uses: anthropics/claude-code-action@a1b2c3d4  # 不要用 @v1

# CI 中使用最小权限
claude -p "..." \
  --allowedTools "Read,Grep,Glob" \
  --disallowedTools "Bash(*),Write,Edit"

20. 常见问题排查

Q1：安装后 `claude` 命令找不到

# 检查 npm 全局安装路径
npm list -g --depth=0 | grep claude

# 获取 npm 全局 bin 路径
npm config get prefix
# 输出：/usr/local 或 ~/.npm-global

# 确认 claude 是否在 bin 目录
ls "$(npm config get prefix)/bin/claude"

# 将 bin 目录添加到 PATH（添加到 ~/.bashrc 或 ~/.zshrc）
export PATH="$(npm config get prefix)/bin:$PATH"

# 重新加载配置
source ~/.bashrc  # 或 source ~/.zshrc

Q2：Windows 上 MCP 服务启动失败

// .mcp.json — Windows 必须用 cmd /c 包装
{
  "mcpServers": {
    "myserver": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "package-name", "arg1", "arg2"]
    }
  }
}

Q3：认证混乱，API 费用异常

# 先诊断
/status

# 如果显示 API Key 但你用的是订阅
unset ANTHROPIC_API_KEY
# 或删除 settings.json 中的 ANTHROPIC_AUTH_TOKEN

# 重新用 OAuth 登录
claude login

Q4：上下文窗口频繁自动压缩

在不同任务之间使用 /clear 重置上下文
把重复性规范写入 CLAUDE.md 避免每次复述
使用 /compact 手动压缩前先 /memory 保存关键信息
合理使用 --max-turns 限制范围

Q5：Node.js 版本不兼容

# nvm 管理版本
nvm install 20
nvm use 20
nvm alias default 20  # 设为默认

# 验证
node --version   # 应显示 v20.x.x
npm --version    # 应显示 10.x.x

# 重新安装 Claude Code
npm install -g @anthropic-ai/claude-code

Q6：IDE 显示 “Not Connected”

/ide
# 查看连接状态

# VS Code 解决方案：
# 1. 确认扩展已安装 (anthropic.claude-code)
# 2. 重新加载窗口：Cmd/Ctrl + Shift + P → "Reload Window"
# 3. 检查 VS Code 版本 ≥ 1.98.0

# JetBrains 解决方案：
# 1. 确认 CLI 全局安装：npm list -g @anthropic-ai/claude-code
# 2. 设置 CLI 路径到实际位置
# 3. 完全退出并重新打开 IDE

Q7：WSL 中运行报错

# WSL 中可能需要安装额外依赖
sudo apt update
sudo apt install -y ca-certificates curl

# 确认 Node.js 版本
node --version  # 低于 18 需要升级

Q8：第三方 API 调用返回 404

# 最常见的原因：ANTHROPIC_BASE_URL 多加了一层 /v1 路径

# ❌ 错误写法（会导致 /v1/v1/messages 双路径）
export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic/v1"

# ✅ 正确写法（Claude Code 会自动追加 /v1/messages）
export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"

# 验证端点是否可达
curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ANTHROPIC_AUTH_TOKEN" \
  -d '{"model":"deepseek-chat","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

Q9：切换第三方 API 后工具调用失败率高

DeepSeek 等模型对工具调用的支持不如 Claude 原生优化
降低单次会话的复杂度，减少并行工具调用
使用 --max-turns 10 限制循环次数避免死循环
对于复杂任务，建议切回官方 Claude API
使用 Router 的 longContext 自动切换功能，复杂场景自动使用 Gemini Pro

21. 总结与展望

Claude Code 解决了什么根本问题

传统开发流程中，开发者的大量时间浪费在：

阅读代码 → 理解逻辑 → 改代码 → 跑测试 → 改 Bug → 提交
    ↑______________________循环________________________↓

Claude Code 改变了这个循环：

下达任务 → Claude 阅读 → Claude 改代码 → Claude 跑测试 → Claude 修 Bug → Claude 提交
    ↑________________________________循环_____________________________↓
                    （你只需审核关键节点）

核心优势回顾

真正的代理能力：不是补全，是独立完成任务
完整工作流：从分析到提交 PR 一气呵成
深度代码理解：架构级认知，非文件级
多模型接入：支持 Anthropic + DeepSeek、OpenAI、Gemini 等第三方 API
灵活扩展：MCP + Hooks + 自定义命令 + SDK 四位一体
安全可控：确定性 deny 规则 + 概率性行为指导

适合谁用

角色	推荐方案	推荐配置
学生/学习	NVIDIA 免费 API	零成本，qwen3-coder-480b 满足学习需求
独立开发者	Pro ($20/月) + NVIDIA 免费备用	日常 Sonnet，省钱用 NVIDIA 免费 API
全栈工程师	Max5 ($100/月) + Opus 4.7	高频使用，Opus 4.7 应对复杂任务，NVIDIA 免费做轻量任务
技术负责人	Max20 ($200/月)	CI/CD 集成 + 代码审查自动化 + 多模型路由
企业团队	Team + 统一 CLAUDE.md	统一安全策略 + 统一编码规范

展望

AI 编程正从"辅助编码"走向"自主开发"，Claude Code 是这个趋势的领跑者。Opus 4.7 的发布进一步印证了这一方向——更强的长周期任务处理能力和代码基准测试表现，使得 AI 能够承担越来越复杂的开发任务。

建议尽早建立:

团队的 CLAUDE.md 规范体系
MCP 工具链集成
多模型路由策略（NVIDIA 免费 API 做轻量任务 + DeepSeek 做日常编码 + Claude Opus 攻克复杂问题）

这是未来开发效率竞争的关键基础设施。

参考资源：

本文基于 Claude Code 2026 年 4 月最新版本编写，涵盖 Opus 4.7 新特性和第三方大模型 API 接入方法。AI 工具迭代迅速，如有较大更新请以官方文档为准。

如果本文对你有帮助，欢迎点赞收藏转发，也欢迎在评论区交流你的使用经验。

DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

做了个 Claude Code/Codex/Gemini 国内平替平台aikopen

我越来越觉得：AI Coding 不会替代程序员。AI 协作能力而不是单纯手写代码速度。CodexGeminiCursorDevinWindsurf欢迎一起交流。也想看看：大家现在真实 AI Coding 使用场景到底是什么。

DeepSeek技术社区

Claude Code接入国产模型的唯一捷径找到了！小米原生（免费送百亿taken）、阿里直连、DeepSeek百万上下文！

2026年5月最新的8款国产大模型（DeepSeek V4、Kimi K2.6、Qwen3.5-Plus、豆包Seed 2.0 Pro、智谱GLM-5.1、小米MiMo V2.5-Pro、文心ERNIE 5.1、混元Hy3 preview）接入Claude Code的能力，从代码性能、上下文长度、价格、Agent支持等维度对比，并提供具体配置参数与选型建议。

DeepSeek技术社区

2026 年度 GEO 服务行业影响力榜单：技术硬实力与用户口碑双维度专业评级

该系统已无缝覆盖 15 + 全球主流 AI 搜索平台，涵盖 ChatGPT、Gemini、Perplexity、DeepSeek、豆包、Kimi、腾讯元宝等，同时具备 20 + 全球主流语种的本地化适配能力，可覆盖全球 20+AI 搜索平台，核心护城河是跨模型的通用共识分发协议，一次接入、全平台生效。公司拥有 12 个全球办公节点，横跨亚洲、欧洲、北美三大洲，以上海全球总部为核心，同步布局深圳、武