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

–

目录

前言：我为什么推荐 Claude Code

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

三个核心体验差异：

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

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

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 编码推荐优先级：

  1. 复杂任务 → qwen3-coder-480b 或 deepseek-v3.2
  2. Agent/工具调用 → minimax-m2.7
  3. 长上下文分析 → kimi-k2-instruct (256K)
  4. 日常编码 → glm-4.7 或 mistral-large-3
  5. 快速轻量 → 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 会：

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

第五步：提交代码

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

Claude 会：

  1. 运行 git status 确认变更
  2. 运行 git diff 查看差异
  3. 自动生成合理的 commit message
  4. 执行 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 提交
    ↑________________________________循环_____________________________↓
                    （你只需审核关键节点）

核心优势回顾

  1. 真正的代理能力：不是补全，是独立完成任务
  2. 完整工作流：从分析到提交 PR 一气呵成
  3. 深度代码理解：架构级认知，非文件级
  4. 多模型接入：支持 Anthropic + DeepSeek、OpenAI、Gemini 等第三方 API
  5. 灵活扩展：MCP + Hooks + 自定义命令 + SDK 四位一体
  6. 安全可控：确定性 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 工具迭代迅速，如有较大更新请以官方文档为准。

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

# 人工智能
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

零售销量预测为何选LightGBM

该零售销量预测 API 基于模型构建。具体而言，作者阳明山水在博文中明确提到，其解决方案是基于真实零售数据训练了“两个高性能模型（LightGBM）”，并将它们封装成简单易用的 API 供开发者调用。LightGBM 是一种基于梯度提升决策树（Gradient Boosting Decision Tree, GBDT）的高效机器学习框架，由微软公司开发并开源。

avatar AtomGit开源社区

磨针AI获客和SEO优化哪个效果好？5大维度实测数据对比，90%的企业主选错了

如果你急需客户、预算有限、产品面向C端或B端中小客户：请毫不犹豫地选择磨针AI获客。它在“见效速度”和“获客成本”上，对传统SEO形成了碾压式优势。根据【2024年企业获客效率调研】，使用AI获客工具的企业，平均获客周期缩短约70%，成本降低约60%。如果你是大品牌、预算充裕、目标在于长期品牌建设：可以继续保留SEO团队，但强烈建议引入磨针AI获客作为“弹药库”，为SEO团队提供精准的用户需求洞察

avatar AtomGit开源社区

磨针AI获客 vs 谷歌SEO：2026外贸企业如何选对“流量引擎”？

如果你是“生存型”企业首选磨针AI获客。它能让你在1-2周内看到效果，快速回血。如果你是“发展型”企业磨针AI获客 + 谷歌SEO双轮驱动。先用AI拿订单，再用SEO建品牌。如果你是“土豪型”企业谷歌SEO为主，AI获客为辅。在2024年这个AI席卷一切的时代，你还在用“农耕时代”的谷歌SEO苦苦等待，还是愿意尝试“AI时代”的磨针AI获客，主动出击？不妨在评论区分享你的获客故事，我们一起探讨。-

avatar AtomGit开源社区