超详细 Claude Code 终端教程，从入门到精通（国产模型版）

各位看官今天来聊 Claude Code，这篇只干一件事：让小白在终端里把它用起来！

一句话：Claude Code 是住在终端里的 AI 助手，能读文件、改文件、跑命令。

和网页聊天最大的区别——聊天是它写好、你复制粘贴；Claude Code 是直接在你电脑上改。

不用懂编程，全篇要敲的命令不到二十条，大部分复制粘贴就行。

目录

• 一、Claude Code 是什么 —— 壳和核，三种形态

• 二、安装 —— 一行命令

• 三、启动·登录 —— 三条路选一条

• 四、接第三方模型平台 —— 先拿密钥，再用 CC-Switch 或手动配置

• 五、验证 —— 一条 curl 分清三种错

• 六、第一次干活 —— 五步走一遍

• 七、日常用法 —— 三个前缀、十个命令、CLAUDE.md、进阶命令

• 八、权限 —— 动手之前先问一声

• 九、上下文·模型 —— 省钱就靠这两件事

• 十、进阶四件套 —— 知道有这回事就行

• 十一、快捷键

• 十二、常见坑

• 十三、问题答疑

一、Claude Code 是什么

打个比方。网页版 AI 像电话客服，给建议，挂了电话活还得自己干。

Claude Code 像上门师傅，进到项目文件夹，自己翻柜子（读文件）、动手修（改文件）、修完试一遍（跑命令）。

壳和核

Claude Code 是壳，模型是核。 壳可以换核——第四节接第三方模型平台、第九节选模型，都是在换核。

官方的几个核：

Sonnet 5     日常主力，默认用它就对了
Opus 5.5     最新旗舰，长任务、复杂任务
Fable 5.1    更高一档，最难的活
Haiku 4.5    最快最便宜，轻活

接上第三方模型平台，还能换成 DeepSeek 这类国产模型，见第四节。

三种形态，两种能动本地文件

网页版的 Claude Code 也一样碰不到本地：它跑在云端虚拟机上，只能改 GitHub 仓库。

一上来用网页版，然后纳闷「为什么它看不到我的文件」——它本来就看不到。

简单记忆版

🧠 LLM        → 大模型，负责想
🤖 Agent      → 智能体，负责干活
📚 Skill      → 说明书，教它怎么干
🔌 MCP        → 插头，连外部工具
💻 CLI        → 命令行，就是终端
🪝 Hook       → 到点自动执行
👥 Subagent   → 分身，独立干活
🔢 Token      → 计费和记忆的单位

网站

Anthropic 公司官网：  https://www.anthropic.com/
Claude 聊天助手：     https://claude.ai/
Claude 学院：         https://academy.claude.com/
Claude Code 文档：    https://code.claude.com/docs

二、安装

最低要求：macOS 13、Windows 10 1809、Ubuntu 20.04 / Debian 10，内存 4GB。

Windows 不用装 WSL，原生就支持。装了 Git for Windows 走 Bash，没装走 PowerShell，都能跑。

有官方 Claude 账号的，也推荐装个桌面版。但 CLI 命令行版做得很好，一定要装、一定要学！ 桌面APP 和 CLI 是两个独立的程序，需要分别安装。

这不，我两个号都被封了，心碎。不打算再充值了，第二个号还不给退款！

封号后的提示：Organization disabled

一行命令

macOS / Linux：

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

官方脚本不需要装 Node.js。

分不清 PowerShell 还是 CMD？看提示符前面有没有 PS，有就是 PowerShell。

其他装法，任选一种：

brew install --cask claude-code              #macOS Homebrew

winget install Anthropic.ClaudeCode          #Windows

npm install -g @anthropic-ai/claude-code     #要先装 Node.js

注意：别用 sudo npm install -g。 sudo 是超级管理员权限，官方明确警告会有权限和安全问题。

验证

claude --version    #看到版本号就成

claude doctor       #体检：安装和配置有没有问题

提示 command not found，九成是 PATH 没刷新, 或者环境变量没有配好。

关掉终端，重开一个即可。

三、启动·登录

claude

第一次运行会弹出浏览器，要求登录。

先说结论：免费版 claude.ai 账号用不了。 需要 Pro、Max、Team、Enterprise 或 Console（API）账号之一。

三条路选一条：

登录卡住，一般是这两种：

• 浏览器没弹出来：按 c 复制登录链接，手动粘进浏览器。

• 回调失败（远程服务器、WSL、容器里常见）：页面会显示一串 code，粘回终端 Paste code here if prompted 那行。

凭据 macOS 存在钥匙串，Linux / Windows 存在 ~/.claude/.credentials.json。

这个文件等于密码，别发给别人，别提交到仓库。

进了 Claude Code 之后，登录、退出、换账号，用 /login 和 /logout。

某些时候新模型不可用 ，需要手动更新，手动更新命令

claude update       #手动更新

四、接第三方模型平台

走官方订阅的，这节和下一节可以跳过。

第三方模型平台是什么

一句话：Claude 官方以外、能接进 Claude Code 的模型服务。

大致三类：卖自家模型的，比如 DeepSeek；聚合几百个模型的，比如 OpenRouter；还有转卖 Claude 调用权的代购型平台。

用它的理由：官方要境外信用卡、直连网络不稳、官方号容易被封。价格有高有低，要自己比。

代价只有一个，但很重：请求内容全部经过第三方服务器。

每一段代码、每一个问题，都要过平台的手。

• 个人学习、开源项目 → 可以用

• 公司代码、客户数据、密钥文件 → 不要用

便宜不等于划算。 有的平台 token 计量不透明，先小额充值试一下。

另外，地址指向非官方时，Remote Control 和语音听写不可用，MCP 工具搜索默认关闭。

第一步：拿到密钥

DeepSeek

申请地址：https://platform.deepseek.com/api_keys

密钥只显示一次，复制、填好，再关窗口。

忘了复制，或者某个 key 不用了，直接删掉重建就行。

接口文档：https://api-docs.deepseek.com/zh-cn/

OpenRouter

地址：https://openrouter.ai/

目前唯一比较推荐的大型第三方模型平台。名声早有耳闻，不过我的使用经验暂时还不多。

初步看下来：近 500 个模型可用，几乎覆盖全球主流模型；支持主流信用卡、支付宝（AliPay）和 USDC 加密货币付款；余额可以手动充值，也可以设置自动充值。

第二步，方法一：CC-Switch（推荐）

一句话：一个切换模型平台的桌面软件，点点鼠标就配好，不用手写配置文件。

下载地址：https://ccswitch.io/zh/

下载、安装、打开，进 Claude 板块。

点添加供应商。列表里没有的，选「自定义」。

填入 API Key，保存。

用了 CC-Switch，下面的手动配置就不用再做了，两种方法别混着用。

第二步，方法二：手动配置

三个变量

平台会给两样东西：一个地址、一串密钥。交给 Claude Code 靠三个变量：

两个密钥变量只填一个。平台读哪个头就填哪个，填错就是 401。

文档没写的话，先用 ANTHROPIC_AUTH_TOKEN，报 401 再换。

地址结尾不要带 /v1。Claude Code 会自己拼上 /v1/messages，带了就变成 /v1/v1/messages，直接 404。

✅ https://your-relay.example.com
❌ https://your-relay.example.com/v1

写进配置文件

编辑 ~/.claude/settings.json（Windows 是 %USERPROFILE%\.claude\settings.json），没有就新建：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-relay.example.com",
    "ANTHROPIC_AUTH_TOKEN": "你的密钥"
  },
  "model": "sonnet"
}

一次写好，所有项目、所有终端窗口都生效。

这是严格 JSON：不能写 // 注释，最后一项后面不能有逗号。 写错了启动报 Settings Error。

或者用环境变量（临时试）

macOS / Linux：

export ANTHROPIC_BASE_URL=https://your-relay.example.com
export ANTHROPIC_AUTH_TOKEN=你的密钥

Windows PowerShell：

$env:ANTHROPIC_BASE_URL = "https://your-relay.example.com"
$env:ANTHROPIC_AUTH_TOKEN = "你的密钥"

只对当前窗口有效，关了就没了。想长期用，回去写配置文件。

两处都设了、值不一样，以 settings.json 为准。

不同项目用不同平台

项目根目录建 .claude/settings.local.json，格式同上。优先级比用户级高，只管这一个项目。所以项目级的配置就会覆盖用户级的，这个要清楚！

密钥只放 settings.local.json，别放 .claude/settings.json——后者是要提交到仓库的，等于把钥匙挂在门口。

一个反直觉的坑

配了第三方模型平台，已登录的官方订阅就不生效了。

优先级是定死的：平台 token > API key > 登录的订阅。想切回订阅，把变量清掉：

unset ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN    #settings.json 里的 env 也要删

五、验证：一条 curl

配完别急着用，先跑一条命令。这一步能省掉半小时瞎猜。

curl -sS -w '\n%{http_code}\n' -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-5", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

这条读的是环境变量。用 CC-Switch 或只写了 settings.json 的，把 $ANTHROPIC_BASE_URL 和 $ANTHROPIC_AUTH_TOKEN 直接换成地址和密钥。

model 换成平台文档里的模型名，比如 DeepSeek 就填它文档里给的名字。

看返回，对号入座：

curl 通了，进 Claude Code 敲 /status。

Anthropic base URL 那行显示平台地址，就是接上了。

最后问一句「用一句话解释什么是递归」。有回答，全流程打通。

curl 测不出来的三个报错：

• 启动警告两个凭据源：第三方模型平台和已登录的订阅同时存在。二选一，unset 变量或者 /logout。

• 400，提到 Extra inputs are not permitted：平台的上游不认新字段。设 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1。

• 设了 ANTHROPIC_API_KEY 却被忽略：之前拒绝过这个 key。/config 里打开 Use custom API key。

所有连接问题，先回来跑这条 curl。 地址错、密钥错、网络不通，它能一次分开。

六、第一次干活：走一遍

找一个不重要的文件夹练手，有备份的、弄乱了也无所谓的。

第一步：进文件夹，启动

cd ~/Documents/练手文件夹    #cd 就是切换目录
claude

在哪个文件夹启动，它就只能看到哪个文件夹。

第一次进一个文件夹，会问是否信任，选 Yes。

如图需要用方向键，向下移动光标, 选Yes,回车就确定✅ 启动进项目了

第二步：先让它看，别让它动

这个文件夹里有什么？帮我列一下

这一步是确认：它看到的，和你以为的一样。

第三步：派一件小活，先要方案

把这里的文件按主题分到几个子文件夹，拿不准的放进「待定」。
先给我方案，别动手。

「先给我方案，别动手」这一句，就等于手动开了 plan 模式。

方案没问题，再说「可以，按这个执行」。

第四步：盯着每一步

动手时，每个有风险的操作都会停下来问：允许一次、总是允许、拒绝。

看清它要干什么，再按。 前几次尤其要看。

第五步：检查，不满意就回滚

/diff      #看改了哪些文件
/rewind    #回滚到之前的检查点

不写代码也能用

只要活是「在文件夹里处理文件」，它就能干：

这个文件夹是攒的文章，按主题分组，每组写一个 index.md 做目录

把文件名里的日期统一成 YYYY-MM-DD，改之前先列新旧对照表

读完所有 md 文件，把提到的工具名和它解决的问题做成一张表

把英文文档翻译成中文，专业名词保留英文，放在括号里

共同点：给了位置、给了动作、给了标准。

提示词：具体 > 笼统

三个随手能用的句式：

先看，别改：——————
只做这一件事，别顺手改别的：——————
做完告诉我改了哪几个文件

不满意就追加，别重说。「方向不对，问题在……，重来一次」——上下文还在，追加比重开省事。

跑偏太远了，再 /clear 重来。

七、日常用法

三个前缀

@ 最常用。 @README.md 这个文件讲了什么，等于指着文件说「就看这个」。

十个常用命令

命令只在消息开头生效，写在句子中间没用。

CLAUDE.md：给 AI 的员工手册

一句话：每次会话开始自动读取的长期指令。

放项目根目录，是这个项目的规矩；放 ~/.claude/CLAUDE.md，是所有项目通用的规矩。两份同时生效。

最省事的做法：进项目跑一次 /init，让它自己生成，再手动改。

值得写的四块：

# 关于这个项目
是什么、用什么技术栈

# 目录结构
每个文件夹放什么

# 行为规则
能做什么、不能做什么

# 代码规范
缩进、命名习惯

控制在 200 行以内。 它每次都进上下文，写太长一直占着地方，规则多了遵守度还会下降。

长流程放 Skill，见第十节。

进阶命令

十个基础命令用顺了，再加这几个：

/goal 最值得学。

普通对话是一问一答，答完就停。/goal 是给一个完成条件——没达成，自己接着干；达成了，才停。

/goal 所有测试都通过                     #定目标
/goal docs 下每篇 md 都有 frontmatter
/goal                                  #不带参数，看当前目标
/goal clear                            #提前结束

条件要写成能检查的。「测试全过」能判断，「代码写得更好」判断不了，只会一直跑、一直烧 token。

/btw 适合插嘴。 干到一半想问「刚才那个函数是干嘛的」，用 /btw 问，答案不进对话历史，不占上下文。

/loop 适合盯状态。

/loop 5m 看一下构建跑完没有，跑完告诉我结果    #每 5 分钟一次

关掉会话就停。

补充命令

/agents 手动开子智能体。

把常用任务写成 agent 文件放进 ~/.claude/agents/，需要时直接调：

/code-review       #调代码审查 agent
/agents            #看有哪些 agent 可用

agent 有独立记忆，跑完把结果交回主对话，不会把一堆中间输出淹没你的上下文。详见第十节。

/memory 管长期记忆。

Claude Code 有跨会话的持久记忆。/memory 打开编辑界面，可以手动加、改、删。比如告诉它你偏好的代码风格、常用项目路径，下次开新会话照样记得。

补充命令

偶尔会需要：

以上常用命令、进阶命令、补充命令共三档 36 条，是日常真正较经常会用到的。官方完整命令表有 115 条，想看全集去 https://code.claude.com/docs/zh-CN/commands

八、权限

这一节关系到数据安全，别跳。

默认模式下，每次要改文件、跑命令，都会先问一声。

这个设计是对的。 删除、覆盖、推送这类操作，看清楚再点。

Shift + Tab 切模式

按 Shift + Tab 循环切换，状态栏会显示当前模式。先记三个：

复杂任务先切 plan。 方向对齐了再放手干，能省掉大量返工。

危险参数

--dangerously-skip-permissions 跳过所有确认，连 .git、.claude 目录的写入都不问。

官方的说法是：只在容器、虚拟机这类隔离环境里用。 在装着真实数据的电脑上用，后果自负。

硬拦：deny 规则

想让它永远碰不到某些文件，写进 settings.json：

{
  "permissions": {
    "deny": ["Read(./.env)", "Read(./.env.*)"],
    "ask": ["Bash(git push *)"]
  }
}

判定顺序 deny → ask → allow。deny 先匹配，allow 挖不出 deny 的例外。

权限由程序执行，不由模型执行。 CLAUDE.md 里写「不许读 .env」只是劝它别读，deny 规则才是真拦住。

查看和修改规则用 /permissions。

九、上下文·模型：省钱靠这两件事

上下文

一句话：上下文就是 AI 的短期记忆。 每句对话、读过的每个文件、每段命令输出，都占地方。

每提问一次，整段历史都要重新发一遍。对话越长，每次越贵。

/compact 不是省钱键。 压缩本身要读完整段对话，是一次很大的请求。

不需要连续性，/clear 才是免费的。

/compact 可以指定保留重点：

/compact 只保留代码改动和测试结果

模型

日常用 sonnet，难活切 opus，轻活用 haiku。

别一直挂着最贵的，价格差好几倍。

/model                  #会话内打开选择器
claude --model opus     #启动时指定

长期默认值写进 settings.json 的 "model"。

用别名，别写版本号。 sonnet、opus、haiku 会自动指向当前推荐版本，写死的版本号过一阵就旧了。

第三方模型平台例外。 走平台时模型名不做校验，原样发过去，写错了要等第一次请求才报错。

平台的模型名和官方不一样，就在 settings.json 的 env 里把别名映射过去：

"ANTHROPIC_DEFAULT_SONNET_MODEL": "平台的 sonnet 档模型名",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "平台的 opus 档模型名",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "平台的 haiku 档模型名"

HAIKU 那一个还管后台轻活，比如给会话起标题。指向便宜模型，能省一笔。

省 token 的习惯

• 换任务就 /clear，最有效的一条

• 跑偏了早按 Esc 打断，别等它跑完

• 提示词写具体，少走弯路

• 复杂任务先 plan

• 时不时 /context 看一眼占用

十、进阶四件套

不用全学。知道是什么、什么时候用得上，就够了。

Skills

和 CLAUDE.md 的区别：CLAUDE.md 每次都加载，Skill 用到才加载。

放在 ~/.claude/skills/名字/SKILL.md：

---
name: commit
description: 提交当前改动，写规范的提交说明
---

具体步骤写在这里

description 最重要——AI 靠它判断什么时候该用。 手动调用就输入 /commit。

以前 .claude/commands/ 下的自定义命令已经并进 Skills，旧写法照样能用。

Subagents

派出去干活的帮手。中间过程不占主对话，只带一个摘要回来。

放在 ~/.claude/agents/ 下，一个 md 文件一个：

---
name: code-reviewer
description: 审查代码质量
tools: Read, Glob, Grep
---

你是一个代码审查员……

用的时候直接说「用 code-reviewer 审查一下刚才的改动」。想新建，也可以直接让它帮着写。

Hooks

区别在确定性：CLAUDE.md 是「AI 可能会做」，Hook 是「一定会做」。

每次改完文件自动格式化：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

常用事件：PreToolUse（执行前）、PostToolUse（执行后）、Stop（回答结束）。

MCP

新手可以不用太深入。官方给的信号很明确：发现自己老是从另一个工具往对话里复制粘贴数据，再考虑它。

claude mcp add --transport http notion https://mcp.notion.com/mcp    #添加
claude mcp list                                                       #查看
claude mcp remove notion                                              #删除

只连信任的服务器。 会拉取外部内容的服务器，有提示注入风险。

十一、快捷键

换行问得最多：\ + 回车，或者 Ctrl + J，所有终端都能用。

iTerm2、herdr、Warp、Ghostty、Windows Terminal 里 Shift + Enter 直接可用，其他终端跑一次 /terminal-setup。

输入框为空时按 ?，弹出全部快捷键。要在英文输入法下按。

十二、常见坑

前面都讲过，这里压成一行一条。出了问题先对一遍：

1. sudo npm install -g → 权限和安全问题，别加 sudo

2. npm update -g 升不上去 → 改用 npm install -g @anthropic-ai/claude-code@latest

3. command not found → 关掉终端重开

4. 地址带 /v1 → 404

5. 密钥填错变量 → 401

6. 密钥写进 .claude/settings.json → 会被提交到仓库，改放 settings.local.json 并确认它在 .gitignore 里

7. settings.json 里写注释、尾逗号 → Settings Error

8. 配了第三方模型平台，订阅失效 → 平台凭据优先，切回要清掉变量

9. 走平台时照抄官方模型名 → 第一次请求才报错

10. CC-Switch 和手动配置混着用 → 两边互相覆盖，只留一种

11. 真机上用 --dangerously-skip-permissions → 只在容器、虚拟机里用

12. 以为 CLAUDE.md 能拦住操作 → 硬拦用 deny

13. 把 /compact 当省钱键 → 换任务用 /clear

14. 一个会话干一整天 → 越往后每次越贵

15. 公司代码走第三方模型平台 → 内容经过第三方

16. 从来不看用量 → /context 看占用，/usage 看用量

十三、问题答疑

1. 免费能用吗？

软件免费，调用api 都要钱。走官方要付费账号（Pro 起步），或者官方API, 或者走第三方聚合模型平台，又或者 deepseek 这种自产模型平台按量付费。

2. 一定要会编程吗？

不用。能看懂文件夹结构、知道什么文件放哪，就能用。第六节那些整理文件的活，一行代码都不用写。

3. 会不会把电脑搞乱？

默认模式每次动手都问。只要不开 bypass，就不会有失控操作。

保险起见，重要项目先 git commit 一次，再让它干活。

4. 和 Cursor、VS Code 里的 AI 有什么区别？

编辑器里的 AI 主要帮着写代码；Claude Code 在终端里跑，能操作整个文件夹、跑命令、管 Git。两者可以一起用。

5. 第三方模型平台还是官方订阅？

个人学习、预算有限 → 第三方模型平台。长期重度用 → 算总账，订阅可能更划算。有保密要求 → 只能官方。

6. 能同时开几个？

多开几个终端窗口就行，每个窗口的上下文互相独立。

7. 改错了怎么办？

/rewind 回滚，或者输入框为空时按两下 Esc。有 Git 的话，用 Git 回退也行。

8.什么是code 命令？

装了 VS Code（https://code.visualstudio.com/），终端里敲：

code ./    #用 VS Code 打开当前目录

./ 换成别的路径也行。改完的文件，在 VS Code 里看、改、保存都方便。

Mac 上第一次用，要先在 VS Code 里按 Cmd + Shift + P，运行 Shell Command: Install 'code' command in PATH。

最后

对 Claude 真的又爱又恨：爱它用起来顺手，恨它疯狂封号。

靠黑科技防封号去用，成本太高，也心累，天天担惊受怕。想来想去，用第三方模型平台就好了，所以写下这篇！

真想用官方，还有一种可能更保险的方式：买一台正经的美国IP虚拟机，在虚拟机远程登录claude 使用。

四条，记住就够：

一、先跑通一条命令，再谈配置。 装完先 claude --version，配完先跑 curl。

二、第三方模型平台三件事：地址不带 /v1、密钥填对变量、别写进会提交的文件。

三、默认权限模式最安全。 想提速先用 plan 看方案，别一上来就跳过确认。

四、换任务就 /clear。 省钱又提效，性价比最高的一条。

Claude Code 不是学完再用的东西，是越用越知道怎么使唤的工具。

先让它干一件最小的事——「这个文件夹是干嘛的？」跑顺了，再交大活。

作者

我是想风 @xaiwind，一个关注出海与 AI 、AIGC的创作者。

如果文章对你有帮助，欢迎点赞、收藏、关注。本文由claude code opus5.5 辅助创作结合本人经验创作而成，文章包售后，学习使用有任何问题，可以评论区或者私聊我！

每天进步一点，我们终会到达目的地！ #ClaudeCode

往期优质文章：

万字长文 ｜超详细的 GitHub 教程，从入门到精通

https://x.com/xaiwind/status/2104039563719262546

超详细Codex上手教程，从入门到精通

https://x.com/xaiwind/status/2102738292580225350

超简单 Grok Bot ，入门到一键构建机器人团

https://x.com/xaiwind/status/2100027951618416963