Claude Code + Codex 小白入门教程
CLI、VS Code 插件、桌面客户端,一次学会

开始前:认识终端(Terminal)

什么是 CLI? CLI = 命令行工具(Command Line Interface),就是"打字下指令"的软件,没有按钮和界面。Claude Code 和 Codex 都是 CLI:你在终端里打字告诉 AI 要做什么,它直接帮你读写文件、写代码、执行命令。

怎么打开终端?

• 按 Command + 空格 打开聚焦搜索,输入 终端 或 Terminal,回车。
• 或者:访达 → 应用程序 → 实用工具 → 终端。

打开后你会看到一行类似 你的名字@MacBook ~ % 的文字,后面有光标在闪。这就是"命令提示符",意思是"我准备好了,请输入命令"。

试一下你的第一条命令

$ pwd
# 屏幕会显示你现在所在的文件夹,比如 /Users/你的用户名

恭喜,你已经会用终端了。

安装 Claude Code

Claude Code 是 Anthropic 官方的 AI 编程 CLI。官方推荐"原生安装器",不需要提前装任何东西,一条命令搞定。

$ curl -fsSL https://claude.ai/install.sh | bash

$ claude --version
# 显示出版本号(比如 2.x.x)就说明装好了

如果 curl 命令因网络问题失败

可以改用 npm 方式安装(需要先完成第 2 章的 Node.js 安装,再回来执行):

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

安装 Codex CLI

Codex 是 OpenAI 官方的 AI 编程 CLI。它通过 npm 安装,而 npm 是 Node.js 自带的,所以先装 Node.js。

$ node --version
# 显示 v20.x.x 或更高就 OK(记得先重开终端)

$ npm install -g @openai/codex

$ npm install -g @openai/codex --registry https://registry.npmmirror.com

$ codex --version
# 显示版本号即成功。先不急着登录:中转走第 3 章,订阅会员走第 4 章

安装 CC Switch 并绑定中转 API

CC Switch 是什么? 一个免费开源的图形界面小工具。Claude Code 和 Codex 想用中转 API,本来要手动改隐藏配置文件、设环境变量,改错一个字符就全崩。CC Switch 把这些变成"填表格 + 点按钮",还能在多个供应商之间一键切换。

$ cd ~/Desktop
$ claude
# 直接进入对话界面、不要求登录官方账号,打个"你好"能正常回答 = 绑定成功
# 按 Ctrl+C 两次或输入 /exit 退出

$ codex
# 进入界面后随便说一句话测试

以后怎么切换供应商?

不用打开主窗口——右键点击屏幕顶部菜单栏里的 CC Switch 小图标,直接选目标供应商即可。换完之后 Claude Code 立即生效,Codex 记得重开终端。

另一条路:官方订阅会员直登(Pro / Plus 用户看这章)

如果你自己开通了 Claude Pro/Max 或 ChatGPT Plus/Pro 会员,可以不买中转、不装 CC Switch,直接用账号登录使用。这条路配置最简单、最稳定,而且 CLI、VS Code 插件、桌面客户端三种形态一次登录全部通用。

两条路怎么选?

Claude Code:用 Claude Pro/Max 账号登录

$ claude
# 首次启动会问登录方式,选 "Claude.ai (Pro/Max)" 这一项
# 已经在用中转、想改回订阅的:进入后输入 /login 重新选

Codex:用 ChatGPT Plus/Pro 账号登录

$ codex
# 首次启动选 "Sign in with ChatGPT",浏览器会弹出 ChatGPT 登录页
# 登录后授权,凭证自动写入 ~/.codex/,以后不用再登

登录一次,三种形态通用

订阅直登完成后:VS Code 插件(第 7、8 章)会自动复用 CLI 的登录态,打开就能用;桌面客户端(第 9、10 章)用同一个账号登录即可,Claude App 的 Code 功能对订阅用户完整开放——第 9 章里"中转不友好"的提醒对你不适用。IDE 和 CLI 的用量计入同一个额度池。

第一次使用 Claude Code

Claude Code 的使用逻辑是:先进入你的项目文件夹,再启动它。它只能看到和操作当前文件夹里的东西(这也是一种安全保护)。

# 1. 进入你的项目文件夹(比如桌面上一个叫 my-project 的文件夹)
$ cd ~/Desktop/my-project
# 2. 启动
$ claude

进入后就像聊天一样,直接用中文描述你想做什么:

• "帮我看看这个项目是做什么的"
• "帮我写一个爬取网页标题的 Python 脚本"
• "这个报错是什么意思:(粘贴报错信息)"

新手必知的三件事

1. 第一次进入一个项目,先输入 /init
它会让 Claude 扫描整个项目并生成 CLAUDE.md 文件(相当于项目说明书),以后每次对话它都会先读这个文件,理解更准。

2. 大改动之前,先按 Shift + Tab 切到计划模式(plan mode)
这个快捷键在三种模式间循环:普通模式 → 自动接受模式 → 计划模式。计划模式下 Claude 只出方案不动手改文件,你确认方案没问题再让它执行。新手强烈建议养成这个习惯。

3. 它每次改文件都会先问你同不同意
看清楚它要改什么再按回车确认。嫌麻烦可以切到自动接受模式,但新手前期建议逐条确认。

第一次使用 Codex CLI

和 Claude Code 类似:先 cd 进项目文件夹,再启动。

$ cd ~/Desktop/my-project
$ codex

进入交互界面后同样直接打中文需求。几个要点:

• 输入 / 会弹出命令菜单,可以切换模型、调整权限、总结对话等。
• 不想进交互界面、只想让它干一件事就退出:codex "帮我把这个文件夹里的图片按日期重命名"
• 临时换个模型跑一次(不改配置):codex --model 模型名
• 怀疑配置有问题时,运行 codex doctor 自动诊断配置和网络。

在 VS Code 里使用 Claude Code(插件版)

不喜欢黑乎乎的终端?Claude Code 有官方 VS Code 插件,给你一个图形化面板:点按钮确认修改、直观看到文件改动对比,对新手更友好。它和 CLI 共用同一套配置,所以第 3 章 CC Switch 配好的中转 API 直接就能用。

插件版专属技巧

在 VS Code 里使用 Codex(插件版)

Codex 也有官方 VS Code 插件,在编辑器侧边栏里聊天、生成和修改代码。它同样和 CLI 共用 ~/.codex/ 下的配置,CC Switch 配好的中转直接通用。

插件版排错三板斧

首次对话失败,90% 是这三个原因:① Base URL 写错(末尾斜杠 / 缺 /v1);② API Key 填错或余额用完;③ 模型名和中转站实际提供的不一致——模型名以你服务商后台列出的为准,写错会直接失败。逐一在 CC Switch 里核对并做健康检查,改完重启 VS Code。

Claude Code 桌面客户端(Claude App)

Anthropic 的官方桌面客户端 Claude App 里内置了完整的 Claude Code:一个带图形界面的独立软件,不用开终端、不用装 Node.js。它有三个标签页:Chat(普通聊天)、Cowork(云端后台代理)、Code(就是图形版 Claude Code,能直接读写你电脑上的文件)。

客户端的独特亮点

Codex 桌面客户端(Codex App)

OpenAI 的官方桌面客户端,定位是"AI 编程任务的工作台":可以同时管理多个项目、并行跑多个任务。对中转用户有个好消息:它和 CLI 共用 ~/.codex/ 下的同一套配置,所以第 3 章用 CC Switch 配好的中转 API,客户端直接就能用。

Claude Code 常用命令 & 快捷键速查

斜杠命令(在对话框里输入)

快捷键

推荐的标准工作流(抄作业)

1. cd 进项目 → claude 启动 → 新项目先 /init
2. Shift + Tab 切到计划模式,描述需求,审查它给的方案
3. 方案 OK → 让它执行(可切自动接受模式处理常规修改)
4. 中途用 /context 盯着上下文,超 70% 就 /compact
5. 干完用 /diff 检查所有改动 → 确认无误收工

Codex 常用命令速查

Codex 的配置文件在 ~/.codex/config.toml,不过既然用了 CC Switch,一般不需要手动碰它。两个记忆点:改了配置要重启终端/IDE 才生效;项目文件夹里如果也有 .codex/config.toml,会覆盖全局配置。

终端(命令行)基础命令速查

这些是 macOS 终端本身的命令,和 AI 工具无关,但天天要用。

文件夹导航

终端通用快捷键

常见问题排错

Q1:装完后输入 claude 或 codex 提示 "command not found"

先关掉终端重新开一个窗口再试。还不行的话,npm 装的工具可能路径没配好——最省事的办法是重新用第 1 章的 curl 原生方式装 Claude Code。

Q2:CC Switch 里切换了供应商,但 Claude Code(终端或插件)还在要求登录官方账号

在终端执行这条命令跳过初始化引导,然后重新启动 claude / 重启 VS Code:

$ echo '{"hasCompletedOnboarding": true}' > ~/.claude.json

(注意:如果你之前已经正常用过 Claude Code,不要随便执行这条,它会覆盖已有配置。)

Q3:请求一直报错 / 超时

按顺序检查:① Base URL 末尾是不是多了 /;② 在 CC Switch 里点"健康检查"看是否通过;③ 中转服务商的余额是否用完;④ 模型名是否和服务商提供的一致;⑤ Codex 的话,是否忘了重开终端/重启 VS Code。

Q4:之前手动配置过环境变量,现在切换供应商不生效

旧的环境变量会和 CC Switch 冲突。检查 ~/.zshrc 文件里有没有 ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、OPENAI_API_KEY 之类的行,有就删掉,保存后重开终端。可以让 Claude Code 自己帮你检查:"帮我看看 ~/.zshrc 里有没有 ANTHROPIC 或 OPENAI 相关的环境变量"。

Q5:npm 安装特别慢或卡住

$ npm config set registry https://registry.npmmirror.com/
# 换成国内镜像后,重新执行安装命令

Q6:VS Code 里插件图标不显示 / 面板打不开

Claude Code 插件:确认打开了一个文件(仅打开文件夹不够)、VS Code ≥ 1.98、重启窗口、暂时禁用其他 AI 插件、信任工作区。Codex 插件:首次启动要下载依赖,多等几分钟;确认发布者是 OpenAI 的正版插件。

Q7:怎么更新这些工具?

Claude Code:claude update(原生安装的会自动更新)。Codex:npm update -g @openai/codex。VS Code 插件:扩展市场会自动提示更新。桌面客户端(Claude App / Codex App):启动时自动检查更新。CC Switch:去 GitHub Releases 下载新版覆盖安装。

Q8:Codex 客户端在 CC Switch 换了供应商后不生效

和 CLI 同一个原因:配置只在启动时读取。Cmd + Q 完全退出 Codex App 再重新打开(点左上角红点关窗口是不够的,进程还在后台)。另外检查中转平台的 Key 是否选了 codex 类型/分组。

一页纸总结

# ── 安装 ──────────────────────────────
curl -fsSL https://claude.ai/install.sh | bash   ← 装 Claude Code
装 Node.js (nodejs.org 下载 LTS 版 pkg 双击装)
npm install -g @openai/codex                     ← 装 Codex
GitHub 下载 CC Switch.dmg 拖进应用程序

# ── 绑定中转 ───────────────────────────
CC Switch → 选应用(Claude/Codex) → ➕ 填 Key 和 Base URL(末尾无斜杠)
→ 健康检查 → 启用 → 重开终端
有官方会员可免中转:claude 里 /login 选订阅账号;codex 选 Sign in with ChatGPT(第 4 章)

# ── 日常使用(CLI)──────────────────────
cd 项目文件夹 → claude 或 codex → 中文描述需求
Claude Code 三板斧:/init 初始化、Shift+Tab 计划模式、/compact 省上下文

# ── 日常使用(VS Code)─────────────────
扩展市场装 "Claude Code"(Anthropic) 和 "Codex"(OpenAI)
和 CLI 共用配置,CC Switch 换供应商后:Claude 即时生效,Codex 重启 IDE

# ── 桌面客户端(App)───────────────────
Codex App:openai.com/codex 下载,和 CLI 共用配置,中转直接能用,改配置重启 App
Claude App:claude.com/download 下载,主要面向官方订阅;中转用户优先 CLI/插件

祝使用顺利!遇到任何报错,把报错信息原样粘贴给 Claude 问"这是什么意思、怎么解决"——这本身就是这些工具最好的用法。

实战案例:用 Claude Code 做一个「涂鸦跳跃」小游戏

学完前面的章节,来完整走一遍真实流程:从零开始,让 Claude Code 做出一个手机、电脑浏览器都能玩的小游戏。整个过程不需要你写一行代码。本章末尾嵌入了最终成品,现在就可以试玩。

$ mkdir ~/Desktop/doodle-jump
$ cd ~/Desktop/doodle-jump
$ claude

帮我做一个叫「涂鸦跳跃」的网页小游戏,做成一个单独的 HTML 文件 doodle.html,要求:
1. 小人不停自动弹跳,落到平台上会再次弹起,踩空掉出屏幕底部就游戏结束
2. 电脑上用左右方向键控制移动,手机上点按屏幕左右半边控制,
   小人从屏幕左边出去会从右边回来
3. 画面跟着小人往上滚动,爬得越高分数越高,顶部显示当前得分和最高分
4. 平台有普通和左右移动两种,偶尔出现弹簧,踩到会弹得特别高
5. 画风可爱,像画在方格纸上的涂鸦
6. 游戏结束显示得分和「再来一局」,点击屏幕重新开始

$ open ~/Desktop/doodle-jump/doodle.html

这个案例教会你的三件事

① 一次只提一个修改需求,改完确认再提下一个,比一口气提五个更不容易乱。② 描述现象,不要猜原因——说"手机上按住屏幕会变蓝"就够了,不用管是什么 CSS 属性没设。③ 让 AI 自己检查——收尾时说一句"帮我检查一下手机和电脑上还有没有操作问题",经常能揪出你没发现的 bug。

最终成品,直接试玩 👇

电脑:← → 方向键 · 手机:点按画面左右半边 · 教程附带的「涂鸦跳跃.html」就是这个游戏的独立文件,可单独转发

CLI、VS Code 插件、桌面客户端,到底用哪个?

学完前面的章节你已经见过三种形态了。它们背后是同一个 AI、同一套配置、同一份额度——就像同一位大厨,区别只是你在哪里"点菜"。

同一位"大厨",三种点菜方式:功能越强的,离"生肉和火"越近

一张表看懂差异

按人对号入座

• 纯小白、几乎不写代码 → 客户端起步,顺手后学 CLI;
• 要写代码、改项目 → VS Code 插件为主,CLI 为辅;
• 批量任务、想玩自动化 → CLI,它是三者的"根",另外两个都是它的皮肤;
• 同时盯好几个项目 → 客户端的多会话侧边栏最舒服。

MCP 入门:给 AI 插上"外设"

默认状态下,Claude Code / Codex 只能操作你项目文件夹里的东西——像一台没插外设的主机。MCP(Model Context Protocol)就是它的 USB 接口:插上不同的"外设"(MCP 服务器),AI 就多一种本事。

插什么外设,AI 就多什么本事——不插的时候它只认识你的项目文件夹

MCP 能干什么?几个真实例子

• 插上浏览器 MCP:让 AI 自己打开你做的网页,点一点、看有没有 bug;
• 插上文档 MCP(如 Context7):AI 写代码时自动查最新版官方文档,不再用过时写法;
• 插上数据库 MCP:直接问"上周注册用户有多少",它自己去查;
• 插上飞书/Slack MCP:让它读群消息、发通知。

怎么装?两条命令的事

以免费的文档查询外设 Context7 为例(装它不需要注册任何账号):

$ claude mcp add context7 -- npx -y @upstash/context7-mcp
# 注意:在终端里执行,不是在 claude 对话里
# 装完进入 claude,输入 /mcp 就能看到它;claude mcp list 可查已装列表

$ codex mcp add context7 -- npx -y @upstash/context7-mcp
# codex mcp list 查看已装;进入 codex 后输入 /mcp 查看运行状态

装完之后不需要特意"调用"它——直接正常提需求,AI 觉得需要时会自己用。比如装了 Context7 后说"用最新版 Tailwind 写个导航栏,查一下文档确认语法",它就会自动去查。

新手三条纪律

① 少而精:装 3~6 个就够了。每多插一个外设,AI 每次思考都要多背一份说明书(占上下文),装太多反而变笨变慢。② 只装可信来源的。MCP 服务器有权限替你做事,来路不明的等于把家门钥匙给陌生人——优先选官方或大厂出品、GitHub 上星标多的。③ 用不上就卸。claude mcp remove 名字 / codex mcp remove 名字 随时拆掉。

常用技巧集:让 AI 干活又快又准的 10 个习惯

工具会用了之后,效率差距全在"怎么跟 AI 说话、怎么安排活儿"上。这 10 条都是社区反复验证过的实战经验,按使用频率排序。

提需求的技巧

1. 说目标和验收标准,别说实现方法。❌"帮我用 flexbox 加个 div 居中" ✅"标题在手机上显示不居中,帮我修好,各种屏幕都要居中"。你负责"要什么",它负责"怎么做"。

2. 一次一件事。五个需求分五轮提,每轮确认满意再下一轮。一口气全说,它容易顾此失彼,出了问题你也不知道哪步错的。

3. 报错直接原样粘贴。不要自己翻译、总结报错信息,完整复制给它,再补一句"什么操作触发的"。截图也可以——直接把图片拖进对话框,它看得懂。

4. 给例子胜过给形容词。❌"做得好看点" ✅"参考 xxx 网站那种深色极简风"或直接丢一张你喜欢的截图。

管理项目的技巧

5. 把"家规"写进 CLAUDE.md。每次都要重复的要求(比如"注释用中文写""不要动 config 文件夹"),说一句"把这条记到 CLAUDE.md 里",以后每次对话它自动遵守。这是回报率最高的一个动作。

6. 干大活之前先让它"存档"。大改动前说一句"先用 git 提交一次当前状态"。改崩了就说"回到上次提交",一秒复原。不懂 git 也没关系,这两句话就够用。

7. 阶段性收尾时主动 /compact。别等上下文爆满被迫压缩——每完成一个阶段就 /compact,还能指定保留重点:/compact 保留数据库结构和已确认的方案。

省钱省额度的技巧

8. 简单活用便宜模型。改文案、写注释、重命名这类杂活,用 /model 切到轻量模型;难题再换回旗舰。订阅用户额度能多撑一倍不止。

9. 换任务就 /clear。旧任务的上下文对新任务是纯负担:又占额度又干扰判断。历史随时可以用 /resume 找回来,别舍不得清。

压箱底的一条

10. 让 AI 检查 AI。活干完加一句:"换个角度审查一下刚才的修改,列出可能有问题的地方"。相当于免费请了个质检员,经常能揪出真 bug。要求高的话,开个新对话(/clear 后)让"陌生的它"来审查,效果更狠。