Claude Code 模型切换与 Skills 技能系统完整指南 — 志趣 ZhiQu 返回首页配置技巧 节点Claude Code 模型切换与 Skills 技能系统完整指南
Claude Code 模型切换与 Skills 技能系统完整指南
> 掌握模型切换、多供应商调用和自定义 Skills，让 Claude Code 真正成为你的专属 AI 编程助手。
适配版本：Claude Code CLI v1.0+ | 最后更新：2026-06-21
全文导读
| 你的背景 | 优先阅读 | 路径说明 |
|---|
| 🆕 零基础新手 | 一 → 二 → 三.1-三.2 → 五.1-五.3 → 九.Q1-Q3 | 先跑通安装和基本切换，再学 Skill 创建 |
| 💻 有 CLI 基础 | 三 → 四 → 五.4-五.6 → 六 | 直接看模型脚本和进阶 Skill |
| 🔧 团队/运维 | 三.7（配置优先级）→ 五.6 → 七 → 八 | 重点看权限管控和团队共享 |
| 🐛 踩坑求助 | 九（全文） | 按报错关键词跳转对应 Q&A |
> ⭐ = 核心必看章节 | ⚠️ = 含重要安全/兼容性警告
一、前置环境准备
> 🆕 如果你还没安装 Claude Code 或配置过 API Key，必须先完成本节。已配置的读者可跳到第二章。
1.1 安装 Claude Code
# 确保 Node.js >= 18（推荐 LTS 22.x）
node --version
# 全局安装
npm install -g @anthropic-ai/claude-code
# 验证
claude --version
国内用户先配 npm 镜像：npm config set registry https://registry.npmmirror.com
1.2 基础 API Key 配置
方式一：环境变量（推荐）
# 临时（仅当前终端）
export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxx"
# 永久（写入 ~/.zshrc）
echo 'export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc
方式二：项目级 .env 文件（更安全，推荐团队使用）
# 创建 .env 文件（不会被 Git 追踪）
echo 'ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxx' > .env
echo '.env' >> .gitignore
> ⚠️ 安全警告：绝对不要将含 API Key 的配置文件提交到 Git。确保 .gitignore 包含 .env、*.key、*.pem。
1.3 验证配置
claude
# 进入交互界面后：
/help # 查看全部命令
/model # 查看当前模型
1.4 新手 3 分钟极简上手
不想折腾脚本？只靠内置命令就够了：
npm install -g @anthropic-ai/claude-code # 1. 安装
export ANTHROPIC_API_KEY="sk-ant-xxx" # 2. 设 Key
claude # 3. 启动
# 启动后直接在对话中用 /model 切换：
/model # 查看可选模型
/model opus # 切换到 Opus 处理复杂任务
/model haiku # 切换到 Haiku 快速问答
> 不需要任何 .zshrc 别名或 Shell 脚本，内置 /model 命令即可覆盖 80% 的日常场景。后续章节的自定义脚本用于高级自动化。
1.5 核心基础命令速查
| 命令 | 作用 |
|---|
/help | 查看所有可用命令 |
/clear | 清空当前对话上下文 |
/cost | 查看当前会话 token 消耗和费用 |
/doctor | 诊断配置和连接状态 |
/model | 查看/切换当前模型 |
/skills | 查看已加载的 Skills 列表 |
exit | 退出 Claude Code |
二、Claude Code 支持的模型体系
2.1 官方 Anthropic 模型
| 模型 | 定位 | 适用场景 | 视觉 |
|---|
claude-opus-4-8 | 最强旗舰 | 复杂架构、深度审查、大型重构 | ✅ |
claude-sonnet-4-6 | 平衡之选 | 日常编码、Bug 修复、代码生成 | ✅ |
claude-haiku-4-5 | 极速轻量 | 简单问答、快速补全、低延迟 | ✅ |
claude-fable-5 | 创意型 | 文档撰写、设计讨论、文案创作 | ❌ |
> 以上模型为 Anthropic 2026 最新固件，对应 Claude Code CLI v1.0+。Fable 5 仅擅长文本创作，不支持图片/PDF 分析。
2.2 第三方兼容模型
| 供应商 | Base URL | 代表模型 | 视觉 | Skills | 工具调用 |
|---|
| DeepSeek | https://api.deepseek.com/anthropic | deepseek-v4-pro, deepseek-v4-flash | ❌ | ✅ | 部分 |
| OpenAI 中转 | 取决于网关 | 取决于网关 | ⚠️ | ⚠️ | ⚠️ |
| Claude 官方能力 | DeepSeek /anthropic | OpenAI 中转 |
|---|
| 图片/PDF 输入 | ❌ 不支持 | ⚠️ 取决于网关 |
| 长上下文 1M | ❌ 不支持 | ❌ 不支持 |
reasoning_effort | ⚠️ 自动适配，手动不生效 | ❌ 完全不支持 |
system 角色消息 | ❌ 返回 400 | ⚠️ 取决于网关 |
| Prompt Cache | ❌ 不支持 | ❌ 不支持 |
| PDF 长文档缓存 | ❌ 不支持 | ❌ 不支持 |
| Skills 系统 | ✅ 基本支持 | ⚠️ 部分 Skill 可能异常 |
2.3 模型与 reasoning_effort 对照
> ⚠️ 重要前置条件：reasoning_effort 在官方 Claude 模型中需要先开启 thinking 扩展思考才生效，不开启则参数无效。新版 Opus（4.8+）部分场景使用自适应推理，手动设置 effort 可能被忽略。
| 模型 | 支持的 effort | 前提条件 | 特殊说明 |
|---|
claude-opus-4-8 | low/medium/high/xhigh/max | 需开启 thinking | 新版自适应，手动可能被忽略 |
claude-sonnet-4-6 | low/medium/high | 需开启 thinking | 三档均需手动开启扩展思考 |
claude-haiku-4-5 | low/medium | 需开启 thinking | 两档 |
deepseek-v4-pro | low/medium/high | 自动适配 | 手动设置不生效；推理时 temperature/top_p 无效 |
deepseek-v4-flash | low | 自动适配 | 仅快速模式 |
| OpenAI 中转 | ❌ 完全不支持 | — | 设置无效，不报错 |
三、模型切换实战 ⭐
3.1 内置命令（新手首选）
/model # 查看当前模型和全部可用模型列表
/model opus # 切换到 Claude Opus 4.8
/model sonnet # 切换到 Claude Sonnet 4.6
/model haiku # 切换到 Claude Haiku 4.5
/model default # 重置为默认模型
配套 /effort 命令（需开启 thinking 扩展）：
/effort # 查看当前设置
/effort high # 深度推理
/effort medium # 中等（默认）
/effort low # 快速模式
3.2 启动时指定模型
# 一次性指定（优先级最高）
ANTHROPIC_DEFAULT_MODEL="claude-opus-4-8" claude
3.3 项目级固定模型
// .claude/settings.json
{
"model": "claude-sonnet-4-6",
"smallModel": "claude-haiku-4-5"
}
> smallModel 用于轻量任务（自动补全、简单问答），可以和主模型不同，进一步节省成本。
> ⚠️ 配置优先级冲突警告：项目 settings.json 会覆盖你的环境变量和脚本设置。如果你用 cc-model ds-pro 切换到 DeepSeek，但项目目录下有 settings.json 指定了 claude-sonnet-4-6，实际生效的是 Sonnet。启动时注意当前目录。
3.4 配置优先级（完整链）
启动命令 --model 参数 ← 最高优先级（一次性覆盖所有配置）
↓ 覆盖
项目 .claude/settings.json ← 随 Git 提交，团队共享
↓ 覆盖
全局 ~/.claude/settings.json ← 仅本机生效，不提交 Git
↓ 覆盖
终端环境变量 ← Shell 脚本 / export
↓ 覆盖
软件内置默认模型 ← claude-sonnet-4-6（最低）
3.5 动态模型切换脚本 cc-model ⭐
# 模型切换函数（不覆盖原始 API Key，切回官方时自动恢复）
function cc-model() {
case "${1:-sonnet}" in
opus) unset ANTHROPIC_BASE_URL; export ANTHROPIC_DEFAULT_MODEL="claude-opus-4-8"
echo "→ Opus 4.8（最强旗舰）" ;;
sonnet) unset ANTHROPIC_BASE_URL; export ANTHROPIC_DEFAULT_MODEL="claude-sonnet-4-6"
echo "→ Sonnet 4.6（日常首选）" ;;
haiku) unset ANTHROPIC_BASE_URL; export ANTHROPIC_DEFAULT_MODEL="claude-haiku-4-5"
echo "→ Haiku 4.5（极速轻量）" ;;
fable) unset ANTHROPIC_BASE_URL; export ANTHROPIC_DEFAULT_MODEL="claude-fable-5"
echo "→ Fable 5（创意文案）" ;;
# 以下为第三方模型，仅修改 BASE_URL 和 MODEL，不覆盖 API Key
ds-pro) export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
export ANTHROPIC_DEFAULT_MODEL="deepseek-v4-pro"
echo "→ DeepSeek V4 Pro" ;;
ds-flash) export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
export ANTHROPIC_DEFAULT_MODEL="deepseek-v4-flash"
echo "→ DeepSeek V4 Flash" ;;
*) echo "用法: cc-model opus|sonnet|haiku|fable|ds-pro|ds-flash" ;;
esac
}
> ⚠️ 切回官方模型时 unset ANTHROPIC_BASE_URL 确保恢复原始 API 端点。不覆盖 ANTHROPIC_API_KEY，保留你原始 Key。
Windows PowerShell（$PROFILE）：
function cc-model {
param([string]$model = "sonnet")
switch ($model) {
"opus" { $env:ANTHROPIC_BASE_URL = $null; $env:ANTHROPIC_DEFAULT_MODEL = "claude-opus-4-8" }
"sonnet" { $env:ANTHROPIC_BASE_URL = $null; $env:ANTHROPIC_DEFAULT_MODEL = "claude-sonnet-4-6" }
"haiku" { $env:ANTHROPIC_BASE_URL = $null; $env:ANTHROPIC_DEFAULT_MODEL = "claude-haiku-4-5" }
"fable" { $env:ANTHROPIC_BASE_URL = $null; $env:ANTHROPIC_DEFAULT_MODEL = "claude-fable-5" }
"ds-pro" { $env:ANTHROPIC_BASE_URL = "https://api.deepseek.com/anthropic"
$env:ANTHROPIC_DEFAULT_MODEL = "deepseek-v4-pro" }
"ds-flash"{ $env:ANTHROPIC_BASE_URL = "https://api.deepseek.com/anthropic"
$env:ANTHROPIC_DEFAULT_MODEL = "deepseek-v4-flash" }
default { Write-Host "用法: cc-model opus|sonnet|haiku|fable|ds-pro|ds-flash" }
}
}
3.6 智能场景调度 cc-smart ⭐
与 cc-model 的区别：cc-model 手动指定模型，cc-smart 按任务复杂度自动选择。
function cc-smart() {
case "${1:-daily}" in
complex) cc-model opus # 复杂任务 → 最强 Opus
echo "→ 复杂任务模式" ;;
daily) cc-model ds-pro # 日常开发 → DeepSeek 省钱
echo "→ 日常开发模式" ;;
quick) cc-model ds-flash # 简单任务 → Flash 最快
echo "→ 快速模式" ;;
*) echo "用法: cc-smart complex|daily|quick" ;;
esac
}
3.7 多供应商独立共存
# ~/.zshrc — 三个独立别名，互不覆盖
alias cc-official='unset ANTHROPIC_BASE_URL; ANTHROPIC_DEFAULT_MODEL="claude-sonnet-4-6" claude'
alias cc-ds='ANTHROPIC_API_KEY="$DEEPSEEK_API_KEY" ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic" ANTHROPIC_DEFAULT_MODEL="deepseek-v4-pro" claude'
alias cc-local='ANTHROPIC_API_KEY="$LOCAL_API_KEY" ANTHROPIC_BASE_URL="https://ai.internal.company.com/anthropic" ANTHROPIC_DEFAULT_MODEL="claude-sonnet-4-6" claude'
3.8 OpenAI 中转网关落地配置
如果你有 OpenAI 兼容的 Anthropic 中转网关：
# ~/.zshrc — OpenAI 中转别名
alias cc-openai='ANTHROPIC_API_KEY="$OPENAI_API_KEY" \
ANTHROPIC_BASE_URL="https://your-gateway.com/anthropic" \
ANTHROPIC_DEFAULT_MODEL="gpt-5" \
claude'
# 注意：OpenAI 模型不支持 reasoning_effort、不支持 system 角色、
# 部分 Skill 工具调用可能异常。仅适合简单代码生成场景。
四、模型选择决策树
你要做什么？
│
├─ 简单问答/代码补全
│ └─ → Haiku 或 DeepSeek V4 Flash（最快最省）
│
├─ 日常编码/Bug 修复
│ ├─ 有预算 → Sonnet（质量最佳）
│ └─ 省钱 → DeepSeek V4 Pro（性价比最高，约 ¥18/月）
│
├─ 复杂重构/架构设计
│ └─ → Opus + effort: high（深度推理最强）
│
├─ 代码审查/安全审计
│ └─ → Opus + effort: high（不容有错）
│
├─ 文档/文案创作
│ └─ → Sonnet 或 Fable（表达清晰流畅）
│
├─ 需要图片分析
│ └─ → 官方 Claude（DeepSeek/OpenAI 中转不支持视觉）
│
└─ CI/CD 自动化
└─ → Haiku 或 DeepSeek V4 Flash（成本低、速度快）
五、Skills 技能系统 ⭐
5.1 Skills 是什么？
Skills 是 Claude Code 的自定义斜杠命令系统。把常用工作流封装成 Skill，通过 /skill-name 一键触发。
用户输入 /review-pr
↓
Claude Code 加载 Skill 的提示词 + 权限配置
↓
按照预设流程：检查代码 → 运行测试 → 生成报告
↓
返回结构化审查结果
5.2 Skills 存储路径
| 类型 | 路径 | 作用范围 | Git 管理 |
|---|
| 项目 Skill | .claude/skills/*.md | 当前项目 | ✅ 随项目提交 |
| 全局用户 Skill | ~/.claude/skills/*.md | 所有项目 | ❌ 不提交 |
5.3 完整 Frontmatter 字段大全 ⭐
---
# ── 基础字段 ──
name: review-pr # [必填] Skill 名称（/review-pr 调用）
description: 审查 PR 代码 # [必填] 简短描述
# ── 模型与推理 ──
model: claude-opus-4-8 # [可选] 指定执行模型
effort: high # [可选] 推理深度: low/medium/high
# ── 安全权限 ──
allowed-tools: # [强烈推荐] 工具白名单
- Read
- Grep
- Glob
- Bash(git:diff)
- Bash(git:log)
- Bash(npm:test)
disallowed-tools: # [可选] 工具黑名单
- Bash(rm:*)
- Bash(shutdown:*)
# ── 行为控制 ──
user-invocable: true # [可选] false=隐藏，仅被其他Skill调用
paths: # [可选] 限定文件范围
- "src/**/*.ts"
- "src/**/*.tsx"
# ── 参数声明 ──
arguments: # [可选] 标准化入参
- name: target
description: 要分析的文件路径
required: true
- name: strict
description: 是否开启严格模式
required: false
---
| 字段 | 类型 | 必填 | 说明 |
|---|
name | string | ✅ | Skill 名称 |
description | string | ✅ | 简短描述 |
model | string | ❌ | 指定模型 |
effort | string | ❌ | 推理深度 low/medium/high |
allowed-tools | array | ❌ | 强烈推荐。工具白名单 |
disallowed-tools | array | ❌ | 工具黑名单 |
user-invocable | bool | ❌ | false 时隐藏 Skill |
paths | array | ❌ | 限定文件范围 |
arguments | array | ❌ | 标准化参数声明 |
> ⚠️ 安全警告：不设置 allowed-tools 的 Skill 拥有全部用户权限，包括文件读写和 Shell 执行。所有 Skill 都应设置白名单。
5.4 实战 Skill 示例
Skill 1：代码审查（完整权限管控）
---
name: review-pr
description: 审查当前分支改动，检查安全、性能、可维护性
model: claude-opus-4-8
effort: high
allowed-tools: [Read, Grep, Glob, Bash(git:diff), Bash(git:log), Bash(npm:test)]
disallowed-tools: [Bash(rm:*), Bash(shutdown:*), Bash(git:push)]
paths: ["src/**/*.ts", "src/**/*.tsx"]
---
请对当前分支的改动进行全面代码审查。
## 审查维度
1. **正确性**：逻辑错误？边界条件？Null/Undefined 引用？
2. **安全性**：SQL 注入？XSS？敏感信息硬编码？
3. **性能**：循环嵌套？N+1 查询？缺失缓存？
4. **可维护性**：命名清晰？函数过长？注释充分？
## 输出
| 文件 | 维度 | 严重程度 | 问题描述 | 修复建议 |
|------|------|---------|---------|---------|
最后给出综合评分（1-10）和 TOP 3 修复建议。
Skill 2：API 文档生成
---
name: generate-api-docs
description: 扫描路由定义，生成 OpenAPI 3.0 文档
model: claude-sonnet-4-6
allowed-tools: [Read, Write, Glob]
disallowed-tools: [Bash(*)]
paths: ["src/**/*.ts", "routes/**/*.ts"]
---
请扫描项目 API 路由定义，生成 `docs/openapi.json`。
要求：包含 info、paths、components，每个端点含 summary、parameters、responses 和示例。
Skill 3：部署前检查
---
name: deploy-check
description: 部署前全面检查：环境变量、数据库、构建、安全、回滚
model: claude-opus-4-8
effort: high
allowed-tools: [Read, Grep, Glob, Bash(npm:run), Bash(node:*)]
disallowed-tools: [Bash(rm:*), Bash(git:push), Bash(docker:*)]
paths: [".env.example", "src/", "prisma/", "package.json"]
---
请对当前项目进行部署前检查：
1. 环境变量：.env.example 与生产一致？所有变量有文档？
2. 数据库：migration 可回滚？索引覆盖新查询？
3. 构建：npm run build 成功？npm audit 无高危？
4. 安全：新端点有认证？CORS 配置生产就绪？
5. 回滚：部署失败如何快速回滚？
每项 ✅ / ⚠️ / ❌ 标注。❌ 必须修复后才能部署。
5.5 参数化 Skill
---
name: analyze-file
description: 深度分析指定文件的代码质量
arguments:
- name: file
description: 文件路径
required: true
- name: strict
description: 严格模式
required: false
allowed-tools: [Read, Grep]
paths: ["{{file}}"]
---
请分析 {{file}}：
1. 代码结构是否合理？
2. 潜在性能问题？
3. 函数职责是否单一？
4. 是否需要重构？
{{#if strict}}
严格模式额外检查：
- 圈复杂度 > 10 的函数
- 超过 50 行的函数
{{/if}}
/analyze-file file=src/services/auth.ts strict=true
5.6 Skill 调试与日志
# 查看已加载 Skills
/skills
# 禁用/启用
/skills disable review-pr
/skills enable review-pr
# 详细日志模式启动
claude --verbose
# 常见加载失败排查
# 1. YAML 格式错误（Tab 缩进、--- 不配对）
head -10 .claude/skills/your-skill.md
# 2. 文件编码必须是 UTF-8
file .claude/skills/your-skill.md
# 3. 修改后重启 Claude Code（Skills 启动时加载）
5.7 链式调用与条件执行
# 串行（分号分隔）
claude -s "fix-ts-errors; review-pr; deploy-check"
# 条件链式（上一步成功才继续）
claude -s "fix-ts-errors" && claude -s "deploy-check"
六、完整项目实战 ⭐
# ── 第 1 步：初始化 ──
cd ~/my-node-project
cc-model ds-pro # 日常开发用 DeepSeek 省钱
claude
# 对话中：
> 帮我给 src/api/users.ts 加一个 GET /users/:id 的端点
> 加上参数校验和错误处理
# ── 第 2 步：质量把关 ──
/model opus # 切到最强模型
/review-pr # 执行代码审查 Skill
# 根据审查结果修改代码后：
# ── 第 3 步：生成文档 ──
/generate-api-docs # 自动生成 OpenAPI 文档
# ── 第 4 步：部署前检查 ──
/deploy-check # 环境变量/数据库/构建/安全全检
# ── 第 5 步：提交 ──
git add . && git commit -m "feat: add user endpoint"
七、安全、合规与成本管控 ⭐
7.1 API Key 安全
| 规则 | 说明 |
|---|
| 禁止提交 Git | .gitignore 包含 .env、*.key、~/.zshrc |
用 .env 文件 | 比直接写 Shell 配置更安全，便于团队隔离 |
| Key 泄露应急 | 立即到服务商控制台 Revoke → 创建新 Key → 更新本地 |
| 调用限流 | 设置 maxTurns 限制单次对话轮数，防止误操作循环消耗 |
7.2 第三方 API 合规
| 场景 | 建议 |
|---|
| 个人/开源项目 | 可以使用，注意不在对话中粘贴 API Key / 数据库密码 |
| 企业闭源项目 | 确认公司数据安全政策是否允许。敏感代码仅讨论方案，不粘贴完整源码 |
| 金融/医疗等强合规行业 | 建议自建 Anthropic 兼容网关，数据不出内网 |
7.3 Token 成本管控
// .claude/settings.json
{
"taskBudget": 50000, // 单次任务最大 token
"maxTurns": 25 // 单次对话最大轮数
}
/cost # 当前会话费用
/cost all # 累计费用
7.4 成本对比
| 供应商 | 模型 | 输入/1M tok | 输出/1M tok | 月费估算(日常) |
|---|
| Anthropic | Sonnet 4.6 | $3 | $15 | ≈¥210 |
| Anthropic | Opus 4.8 | $15 | $75 | ≈¥1050 |
| DeepSeek | V4 Flash | ¥1 | ¥4 | ≈¥9 |
| DeepSeek | V4 Pro | ¥2 | ¥8 | ≈¥18 |
> 月费按 500 万输入 + 100 万输出 token 估算。汇率参考：1 USD ≈ 7 CNY。
八、团队标准化落地
8.1 项目结构
my-project/
├── .claude/
│ ├── skills/ # 项目 Skills（提交 Git）
│ │ ├── review-pr.md
│ │ ├── deploy-check.md
│ │ └── generate-api-docs.md
│ ├── settings.json # 共享配置（提交 Git）
│ └── settings.local.json # 个人配置（不提交，覆盖 settings.json）
├── .gitignore
# .gitignore
!.claude/skills/ # 技能目录随项目走
.claude/settings.local.json # 个人配置不提交
.env # 密钥文件不提交
8.2 CI/CD 集成示例
# .github/workflows/code-review.yml
name: AI Code Review
on: [pull_request]
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: '22' }
- run: npm install -g @anthropic-ai/claude-code
- run: claude -s review-pr --print
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
- name: Post review comment
uses: actions/github-script@v7
with:
script: |
github.rest.issues.createComment({
...context.repo,
issue_number: context.issue.number,
body: '## AI Code Review\n\n' + process.env.REVIEW_OUTPUT
})
九、常见问题排查（按类型分类）
网络与认证类
Q1：401 Unauthorized
临时修复：echo $ANTHROPIC_API_KEY 确认 Key 正确。
永久方案：检查 Key 是否在 DeepSeek 控制台有效；设置 ANTHROPIC_AUTH_TOKEN 替代 ANTHROPIC_API_KEY。
Q2：400 Bad Request
排查：是否开启 1M 长上下文？是否使用 system 角色消息？DeepSeek /anthropic 端点均不支持。
永久方案：关闭长上下文；移除 system 提示或改用 user 消息。
Q3：model not found
检查：模型名全部小写 — deepseek-v4-pro ✅，DeepSeek-V4-Pro ❌。
deepseek-chat/deepseek-reasoner 已于 2026/07/24 弃用，返回此错误。批量替换：
sed -i '' 's/deepseek-chat/deepseek-v4-flash/g' ~/.zshrc
sed -i '' 's/deepseek-reasoner/deepseek-v4-pro/g' ~/.zshrc
source ~/.zshrc
配置与环境类
Q4：环境变量不生效
- macOS/Linux：
source ~/.zshrc 或重开终端
- Windows PowerShell：
. $PROFILE 或重开终端
- 检查是否有项目
settings.json 覆盖了环境变量（优先级更高）
Q5：claude: command not found
# macOS/Linux 一键修复
echo "export PATH=\"$(npm config get prefix)/bin:\$PATH\"" >> ~/.$(basename $SHELL)rc
source ~/.$(basename $SHELL)rc
# Windows PowerShell
$npmPath = npm config get prefix
[Environment]::SetEnvironmentVariable("Path", "$env:Path;$npmPath", "User")
Q6：Base URL 格式错误
- DeepSeek 正确：
https://api.deepseek.com/anthropic（注意 /anthropic 后缀）
- Cursor 正确：
https://api.deepseek.com（无后缀）
- 两者不可混用：Claude Code 必须用
/anthropic，Cursor 不能用 /anthropic
Skill 排查类
Q7：Skill 加载失败 / 执行报错
原因：YAML frontmatter 语法错误（Tab 缩进、--- 不配对、字段名拼写错）。
# 排查
head -10 .claude/skills/your-skill.md # 检查 frontmatter
file .claude/skills/your-skill.md # 确认 UTF-8 编码
claude --verbose # 查看详细日志
Q8：Skill 提示权限不足
原因：allowed-tools 未包含所需工具。
修复：在 Skill frontmatter 的 allowed-tools 中添加对应工具（如 Bash(npm:*)）。
模型行为类
Q9：切换模型后上下文错乱
/clear # 1. 清空上下文
/model sonnet # 2. 切回稳定模型
# 3. 手动总结：「以上讨论了 A 和 B，现在处理 C」
Q10：图片识别失败
DeepSeek /anthropic 端点不支持视觉。用文字描述图片内容替代，或临时切回官方 Claude。
Q11：设置 temperature 无效
推理模式下 temperature/top_p 自动忽略。切换到 deepseek-v4-flash 或关闭 thinking 扩展。
Q12：流式输出中断 / 工具调用截断
deepseek-v4-pro 推理模式下偶发。改用 deepseek-v4-flash。
费用与额度类
Q13：429 或 insufficient_balance
- 检查控制台 Billing 余额
- 推理 token 单独计费且消耗大，日常用 Flash 更省
- 减少并发 Claude Code 实例
附录 A：速查表
模型命令
| 命令 | 作用 |
|---|
/model | 查看/切换模型 |
/model opus|sonnet|haiku | 切换到指定模型 |
/model default | 重置默认 |
/effort | 查看推理深度 |
/effort low|medium|high | 设置推理深度 |
/cost | 查看会话费用 |
Skill 命令
| 命令 | 作用 |
|---|
/skills | 查看已加载 Skill |
/skills enable | 启用 |
/skills disable | 禁用 |
/skill-name | 执行 Skill |
claude -s | 启动时执行 Skill |
claude -s "s1; s2" | 链式执行 |
环境变量
| 变量 | 作用 |
|---|
ANTHROPIC_API_KEY | API 密钥 |
ANTHROPIC_BASE_URL | 自定义端点 |
ANTHROPIC_DEFAULT_MODEL | 默认模型 |
附录 B：术语表
| 术语 | 释义 |
|---|
| reasoning_effort | 推理深度，控制模型回答前的思考程度。值越高思考越多、成本越高 |
| Frontmatter | Markdown 文件开头的 --- 包裹的 YAML 配置区 |
| 兼容网关 | 将一种 API 格式转换为另一种的中间服务 |
| 上下文窗口 | 模型一次对话中能"记住"的最大文本量 |
| token | 文本计量单位，约 0.75 英文单词或 0.5 汉字 |
| thinking 扩展 | 官方 Claude 的扩展思考功能，开启后模型回答前会进行内部推理 |
| Prompt Cache | 缓存重复提示词前缀，降低官方 Claude 的 token 成本 |
附录 C：完整配置模板
macOS / Linux（~/.zshrc）
# ===== API Keys =====
export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxx"
export DEEPSEEK_API_KEY="sk-xxxxxxxx"
# ===== 模型切换 =====
function cc-model() {
case "${1:-sonnet}" in
opus) unset ANTHROPIC_BASE_URL; export ANTHROPIC_DEFAULT_MODEL="claude-opus-4-8" ;;
sonnet) unset ANTHROPIC_BASE_URL; export ANTHROPIC_DEFAULT_MODEL="claude-sonnet-4-6" ;;
haiku) unset ANTHROPIC_BASE_URL; export ANTHROPIC_DEFAULT_MODEL="claude-haiku-4-5" ;;
ds-pro) export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
export ANTHROPIC_DEFAULT_MODEL="deepseek-v4-pro" ;;
ds-flash) export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
export ANTHROPIC_DEFAULT_MODEL="deepseek-v4-flash" ;;
esac; echo "→ $ANTHROPIC_DEFAULT_MODEL"
}
# ===== 别名 =====
alias cc='claude'
alias cc-ds='ANTHROPIC_API_KEY="$DEEPSEEK_API_KEY" ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic" ANTHROPIC_DEFAULT_MODEL="deepseek-v4-pro" claude'
# 默认
cc-model sonnet