03｜16 小时 Claude Code：跑通第一个任务，选对工作入口

07 · 第一次使用：跑通第一个例子

兄弟们，前面几篇全是铺垫——装好了、登录了、套餐也选好了。

工具摆在那儿，但你心里大概还是有点虚：这玩意儿到底怎么用？我打开终端，然后呢？

说句实话，很多人第一次跑 Claude Code 的时候，盯着那个光标愣了快一分钟，不知道该敲什么。生怕一句话说错就把代码搞砸了。

别紧张。今天咱们就走一遍最简单的流程：建一个只有几行代码的小项目，让 Claude 先读懂它，再让它帮你改一行。全程不超过五分钟，你会拿到人生第一次「Claude 帮我改代码并且改对了」的成功体验。这就够了——一旦跑通一次，后面全是水到渠成。

看完这一篇，你会拿到：

• 一套从开终端到跑通第一个任务的完整动作流程，照着敲就行
• 看懂 Claude Code 启动后那个「欢迎屏幕」每一块是什么
• 一个跑得通、给了预期输出的 hello world 级实战
• 几个让你「第一次就不踩坑」的关键提醒（权限怎么批、改错了怎么撤）

01 先建一个「玩具项目」

先说结论：第一次用，别拿你的正式项目练手，建个玩具项目。

为什么？因为正式项目文件多、依赖杂，Claude 一上来读半天，你也看不清它到底干了啥。玩具项目就两三个文件，它改了什么你一眼能看明白——这才是学习用的。

类比：学开车先去空场地。 没人一拿到驾照就上高架。先找个没人的空地，熟悉油门刹车，知道方向盘打多少车拐多少。玩具项目就是你的空场地——搞砸了也无所谓，重建一个就行。

对完全没碰过命令行的人来说，凡是第一次就拿公司项目练的，没有一个不慌的——光是 Claude 读文件那几秒钟的滚屏，就够手心冒汗了。换个法子，先建个三行代码的小文件，五分钟全跑通，信心一下就有了。

打开你的终端（Mac 上是「终端 / Terminal」，Windows 上推荐用 Git Bash 或 PowerShell），敲下面这几行：

mkdir hello-claude
cd hello-claude

这两行的意思是：新建一个叫 hello-claude 的文件夹，然后进到里面。mkdir = make directory（建文件夹），cd = change directory（进文件夹）。

接下来建一个最简单的 Python 文件。Mac / Linux 用：

echo 'def add(a, b):
    return a + b' > main.py

Windows PowerShell 里 echo 写多行略麻烦，你可以直接用记事本新建一个 main.py，把下面两行贴进去存好：

def add(a, b):
    return a + b

💡 一句话总结：第一次用 Claude Code，先建个两三行的玩具项目当「练车场」，改砸了重建即可，心不慌手不抖。

02 启动 Claude，看懂欢迎屏幕

项目建好了，现在在同一个文件夹里启动 Claude Code。确认你的终端当前就在 hello-claude 目录下（刚才 cd 进去了就还在），敲：

claude

注意：一定要在项目目录里启动 claude，不要在桌面或者主目录裸启。因为 Claude Code 把你当前所在的目录当成工作区——你在哪儿启动，它就读哪儿的文件。这是新手最常踩的第一个坑：在主目录启动，然后问「这个项目做什么」，Claude 一脸懵，因为主目录根本不是个项目。

类比：请装修师傅上门，得先把他领到要装修的那套房子。 你不能在小区门口跟他比划半天，他得站在屋里才知道哪面墙要砸、哪里要走线。cd 进项目目录再启动 claude，就是「把师傅领进门」。

启动后你会看到一个欢迎屏幕，按官方文档的说法，上面有你的会话信息、最近的对话、以及最新更新提示。对新手来说，你只需要认住三样东西：

输入框就是主战场。你不用学什么特殊语法，把它当成一个能读你代码的聊天框就对了——用大白话提需求即可。

想确认自己进对地方了，可以先敲一句最朴素的问题：

这个项目做什么？

Claude 会自己去读当前目录下的文件（这里就是 main.py），然后告诉你这是个干啥的项目。整个过程你不用手动把文件「喂」给它——官方文档明确写了：Claude Code 会根据需要自己读项目文件，你不必手动添加上下文。

💡 一句话总结：在项目目录里敲 claude 启动，认住「输入框 + /help」两样就够开工；它会自己读文件，你只管用大白话提需求。

03 让 Claude 先读懂代码

第一个真正的任务，不是让它改代码，而是让它解释代码。

为什么先解释？两个原因：一是让你确认 Claude 确实读到了你的文件（而不是在瞎编）；二是解释类任务零风险——它只是读和说，不会动你一个字，最适合第一次试水。

类比：新同事入职第一天，你不会直接甩给他核心模块去重构，而是先让他「读读代码，跟我讲讲这块是干嘛的」。 听他讲一遍，你就知道他读懂没有、靠不靠谱。让 Claude 解释代码，就是这个「入职第一天」的动作。

在输入框里敲：

解释 main.py 这个文件在做什么，用新手能理解的方式说明

回车。Claude 会读 main.py，然后给你一段大白话解释，大意是：这里定义了一个 add 函数，接收两个参数 a 和 b，返回它们相加的结果。

这一步跑通，意味着两件事成立了：Claude Code 装对了、登录态正常，而且它确实在读你的真实文件。地基稳了，下一步才敢让它动手改。

把对 Claude Code 的指令分成三类记，你以后用起来心里就有谱了：

💡 一句话总结：第一个任务先用「解释型」试水——确认它读到了你的文件、地基稳了，再让它动手。

04 让 Claude 改一行代码（关键：它会先问你）

现在到高潮了：让 Claude 真正改一次代码。

接着上面的会话，直接敲：

给这个函数增加类型注解，并补充基本的错误处理

这时候最关键的一幕来了——Claude 不会直接把你的文件改掉。它会：

1. 找到该改的文件（这里是 main.py）
2. 把它打算改成什么样，以 diff（差异对比）的形式摆给你看
3. 停下来，等你批准
4. 你点了「同意」，它才真正落盘

这是官方文档反复强调的一条铁律：

Claude Code 在修改文件前始终请求许可。你可以批准单个更改，或为本次会话启用「全部接受」模式。

类比：实习生动手前先问你一句。 一个靠谱的实习生，不会未经你同意就把生产代码改了——他会拿着改好的稿子过来：「头儿，我想这么改，你看行不行？」你点头他才动。Claude Code 默认就是这种「先问后动」的实习生。

你会看到一个让你选择的提示，通常是这几个选项的意思：

第一次，强烈建议你老老实实选「同意」就好，别急着开「全部接受」。说句实话，刚上手那阵子最容易图省事，一上来就把权限放到最松（后面篇章会讲的 --dangerously-skip-permissions，顾名思义「危险地跳过权限」），结果它在你没仔细看的情况下连改五六个文件，等你反应过来，已经分不清哪个改动是你要的、哪个是它自作主张加的了。教训就一条：越是不熟，越要让它一步一停。

看懂 diff 的小技巧：红色 / - 开头的是删掉的旧行，绿色 / + 开头的是加上的新行。你的 main.py 大概会从：

def add(a, b):
    return a + b

变成类似这样（具体写法 Claude 可能略有不同，意思一致即可）：

def add(a: float, b: float) -> float:
    if not isinstance(a, (int, float)) or not isinstance(b, (int, float)):
        raise TypeError("a 和 b 必须是数字")
    return a + b

加了类型注解（a: float），也加了基本的错误处理（传进来不是数字就报错）。这一刻，你就完成了第一次「人机协作改代码」。

💡 一句话总结：Claude 改文件前永远先问你——第一次老实选「同意」、看懂 diff 再点头，别图快开全自动。

05 改错了怎么办：两条「后悔药」

新手最大的恐惧就是：万一它改错了、改乱了，我又看不出来，怎么收场？

放心，有两条后悔药，而且很好用。

第一条：对话里直接说「改回去」。 Claude 记得这次会话里它干过什么，你不满意，直接用大白话告诉它：

刚才的改动我不满意，帮我改回原来的样子

它会把改动回退。类比：跟同事说「你刚才那版不行，还按原来的来」 ——不用你自己手动一行行抠回去。

第二条：用检查点（Checkpoint）回溯。 这是 Claude Code 的「游戏存档」机制——它会自动记录每次文件编辑前的状态，你可以一键跳回去。

类比：打游戏的存档读档。 你在 Boss 战前存了档，打输了不用从头再来，读档回到存档点就行。检查点就是 Claude 在动手前帮你悄悄存的档。

怎么触发？按官方文档：

/rewind

或者在输入框为空时，连按两下 Esc 键，就会弹出回溯菜单。

⚠️ 一个细节（官方文档明确提到）：如果输入框里有文字，连按两下 Esc 是清空文字、不是打开回溯菜单。所以要回溯，先确保输入框是空的。

还有一点要拎清楚——检查点只能撤销 Claude 通过它的编辑工具做的文件改动，不等于 Git。官方的建议很到位：

把 checkpoints 当成「本地撤销」，把 Git 当成「永久历史」。

也就是说，检查点适合「哎呀这步改坏了，跳回去」这种即时反悔；真正重要的进度，还是得靠 Git 提交存下来（Git 怎么用，后面专门有一篇讲）。

💡 一句话总结：改错别慌，一句「改回去」+ 检查点 /rewind 兜底；但真正的进度，该交给 Git 存档。

06 动手：五分钟跑通你的第一个任务

光看不练假把式。下面把前面几节串成一条可以照着敲、有预期输出的完整流程。打开终端，跟着走。

第一步：建玩具项目（Mac / Linux）

mkdir hello-claude
cd hello-claude
echo 'def add(a, b):
    return a + b' > main.py

Windows 用户：mkdir hello-claude 和 cd hello-claude 照敲，main.py 用记事本新建并贴入那两行 Python。

预期：hello-claude 文件夹里有一个 main.py，内容是 add 函数那两行。可以敲 ls（Windows 用 dir）确认文件在。

第二步：启动 Claude Code

claude

预期：出现欢迎屏幕，底部有输入框和光标。如果提示你登录，说明前面的登录步骤没完成，回去把第 02 篇的登录走一遍。

第三步：让它解释代码

在输入框里敲：

解释 main.py 这个文件在做什么，用新手能理解的方式说明

预期：Claude 读取 main.py，用大白话告诉你这是个「把两个数相加」的函数。看到它准确说出了 add 函数的作用 = 成功。

第四步：让它改代码，并批准

给这个函数增加类型注解，并补充基本的错误处理

预期：Claude 给出一段 diff（红 - 旧行、绿 + 新行），然后停下来等你选。看懂后选「同意 / Yes」。

第五步：确认改动落地

退出 Claude（敲 exit 或按 Ctrl+D），回到终端看文件：

cat main.py

（Windows PowerShell 用 type main.py）

预期：main.py 里出现了类型注解（像 a: float）和错误处理（raise TypeError(...)）。和你刚才批准的 diff 对得上 = 全流程跑通，恭喜！

⚠️ 万一卡在权限报错（Mac / Linux 上看到 Error: EACCES: permission denied 这类），具体修法因场景不同，后面「常见问题」篇会细讲，这里先知道有这么个坑。

💡 一句话总结：照着五步走一遍，跑通比读懂更重要——拿到第一次「Claude 帮我改对了」的成功体验，后面就水到渠成。

07 小结

这一篇你干了一件事：完整跑通了 Claude Code 的第一个任务——从建项目、启动、解释代码，到改代码并批准。

把核心动作串起来回顾一遍：

你现在应该能： 打开终端、在正确的目录启动 Claude、用自然语言让它读懂并修改一段代码，看懂它给的 diff，知道改错了怎么退回去。这套动作，就是你之后所有 Claude Code 使用的最小内核——后面再花哨的功能，本质都是在这个「提需求 → 看 diff → 批准 / 反悔」的循环上做加法。

下一篇 08「VS Code 集成」——命令行跑通了，但你可能更习惯在编辑器里写代码、看 diff 看得更清楚。下一篇就教你把 Claude Code 装进 VS Code，让它和你的代码并排坐着干活。

这张图把本篇五步串成一条竖向流程：建玩具项目 → 在项目目录里启动 claude → 让它解释代码（绿色·只读零风险）→ 让它改代码（琥珀色高亮·先给 diff 等你批准，即「先问后动」）→ 改错了用 /rewind 回溯（玫红色高亮·兜底「后悔药」），两处高亮正是新手最该记住的安全护栏。

08 · VS Code 集成

刚转去用 VS Code 扩展那阵子，很容易干一件挺蠢的事。

终端里跑得好好的 Claude Code，装完扩展想试试图形界面，打开一个空文件夹，左翻右翻就是找不到官方说的那个「Spark 图标」（工具栏里的火花形图标，Claude Code 在 IDE 里的入口标识）。这时候很容易以为装坏了，卸了重装、重启、清缓存，折腾了快二十分钟，最后翻文档才发现——那个图标只在你打开了具体文件时才出现，光开文件夹不够。对着一个空工作区找图标，找一辈子也找不到。

说白了，VS Code 集成不难，但它跟终端是两套交互逻辑，有些「想当然」会让你卡在最开始那一步。这篇把这些坑提前给你标出来。

看完这一篇，你会拿到：

• 在 VS Code（含 Cursor 等分支）装上 Claude Code 扩展的完整步骤，外加「图标找不到」的排查清单
• 并排 diff（逐行审阅改动）、@ 提及、计划审阅这三个图形界面独有的爽点怎么用
• 一张「扩展 vs CLI 该用哪个」的对照表，外加一组常用快捷键

01 先搞清楚：扩展和 CLI 是什么关系

「我已经会用终端里的 claude 了，还要不要装扩展？」先给结论：扩展不是替代 CLI，是在它外面套了一层图形界面。装扩展时会顺带把 CLI 带上，两者共享同一份 ~/.claude/settings.json 配置；对话历史可以恢复，但不是实时同步——你在扩展里聊到一半，回头在终端跑 claude --resume 就能主动接续那段对话。

类比：同一个后厨，两个点单窗口。 CLI 是趴在厨房窗口喊单——快、全、什么都能点；扩展是大堂服务员，帮你把菜单做得图文并茂、点单看进度更直观，但有几样「隐藏菜单」只有趴窗口才点得到。后厨是同一个，菜一模一样。

到底什么时候用哪个？官方给了张能力对照，整理如下：

一句话：写代码、审阅改动这类「跟文件打交道」的活，扩展明显更好用；!ls 这种 bash 快捷键、Tab 补全只有 CLI 有。一般的用法是主力开在扩展里，要批量跑命令或用扩展里没有的命令，就在集成终端直接敲 claude——历史是通的，无缝切换。

💡 一句话总结：扩展和 CLI 是同一个引擎的两张脸，共享历史和配置，按手头的活随时切换，不用二选一。

02 安装：三种姿势，外加图标找不到的排查

装之前先看一眼版本

官方硬性要求：VS Code 1.98.0 或更高版本，低于这个版本装不上或不工作（点「帮助 → 关于」看版本号）。首次打开扩展时会让你登录 Anthropic 账户；公司走 Bedrock、Vertex AI 等第三方提供商的，配置方式不同，末尾单独提。

三种安装方式

方式一：应用市场搜（最稳，推荐新手用）

在 VS Code 里按 Cmd+Shift+X（Mac）或 Ctrl+Shift+X（Windows/Linux）打开扩展视图，搜索 Claude Code，点安装。

上图是扩展视图里搜 Claude Code 的样子：红框那条「Claude Code for VS Code」、发布者带蓝色认证勾的 Anthropic 才是官方，认准它点进去装。

这里有个小白最容易踩的坑：搜 Claude Code 会跳出一堆名字相似的扩展，认准发布者是 Anthropic 的那个，别装成第三方仿冒的。

方式二：点链接直装

开着 VS Code 时，点链接 vscode:extension/anthropic.claude-code 会直接跳到扩展安装页（Cursor 把 vscode: 换成 cursor:）。

方式三：非主流编辑器 / 装不上时

扩展也能装在 VS Code 的其他分支里（Cursor、Devin Desktop、Kiro 等）——在它们的扩展视图搜 Claude Code，或从 Open VSX 注册表 装。万一死活装不上，别死磕，官方兜底方案是在集成终端直接跑 claude。

国内提示：安装、登录授权、之后让 Claude 干活都要连 Anthropic 服务，全程需要魔法上网，和终端版一致。

装完图标找不到？照这张清单排查

这就是开头那个坑。装好后扩展默认不弹窗，得自己把面板叫出来。最快的方式：先打开一个具体文件，再点编辑器右上角工具栏里的 Spark 图标（一个像火花的小图标）。

上图把三个入口的位置都标了出来：编辑器右上角的 Spark 图标（②，最快但只在开着文件时才出现）、活动栏的 Spark（①，一直都在）、状态栏的 ✱ Claude Code（③，没开文件也能点）。

关键就一句：Spark 图标只在你打开了文件时才出现，光开文件夹不够。 如果还是看不到，按官方这个顺序查：

实在找不到 Spark 图标，还有两个备选入口：

• 活动栏（最左侧那竖排图标）里的 Spark 图标——这个一直都在，点开是会话列表。
• 状态栏（窗口右下角）的 ✱ Claude Code——没开文件也能点，平时更顺手的就是这个，省得纠结有没有开文件。也可以走命令面板（Cmd+Shift+P / Ctrl+Shift+P）输入 Claude Code。

第一次点开面板会出现登录屏，点登录、在浏览器完成授权即可。（如果设了 ANTHROPIC_API_KEY 却还被要求登录，多半是 VS Code 没继承到终端环境变量，官方解法是从终端用 code . 启动 VS Code 把变量带进去。）

💡 一句话总结：装扩展认准 Anthropic 发布者，Spark 图标必须开着文件才出现——找不到先开文件，再不行就用右下角状态栏那个入口。

03 diff 视图：改动当面对质，看清了再点头

这是很多人最早被扩展圈粉的功能。终端版改文件时 diff 是文本符号画的，文件一大、改动一多就看着吃力。扩展把这事搬进了 VS Code 原生的 diff 视图——红绿高亮标增删，跟你平时看 Git diff 一个观感。

类比：合同签字前的「修订模式」对照。 对方把改好的合同发回来，左边原稿、右边改动版，每处增删都标得清清楚楚——你不是闭眼签字，是逐条看过才落笔。Claude 改代码也一样，把改动摆出来请求许可，你有三个选择：接受、拒绝、或直接告诉它改成别的样子。

还有个容易被忽略、用了一阵子才会注意到的细节：接受之前可以直接在 diff 视图里手动改 Claude 的建议，改完它会知道「你动过了」，不再按旧版往下走。比如让它重构一个 200 多行的函数，它一口气改了七八处，要是在 diff 里一眼扫到一处把边界判断写反了，当场在右侧改对再接受，就省了一轮来回。

💡 一句话总结：diff 视图把每处改动摆到你面前，看清、能当场改、再决定接不接受，比终端的文本 diff 安全得多。

04 @ 提及和选中代码：把上下文喂准

让 Claude 干活最大的浪费，是它「不知道你说的是哪段代码」于是绕圈子猜。扩展里有两招把上下文喂得又快又准。

第一招：@ 提及文件 / 文件夹

在提示框里输入 @，跟上文件名或文件夹名，Claude 就会去读那份内容。它支持模糊匹配，不用打全名：

> 解释一下 @auth 的逻辑（会自动匹配 auth.js、AuthService.ts 等）
> @src/components/ 里有什么？（文件夹记得加结尾的斜杠 / ）

类比：开会前先把资料甩进群。 与其口头描述「就那个登录相关的文件」，不如直接 @ 把文件丢给它，省得它满项目翻找、翻错。对超大 PDF 还能让它只读指定页（如第 1-10 页），不用啃完整本。

第二招：选中代码，它自动看见

这招比 @ 还省事：直接在编辑器里选中一段代码，Claude 就自动看到了，提示框下方会显示「已选中 XX 行」。你直接问「这段为什么会报错」，它就知道你指哪段。

几个常用配套技巧：

• 插带行号的引用：按 Option+K / Alt+K，自动插入像 @app.ts#5-10 这样带路径和行号的提及（需编辑器焦点）。
• 临时不让它看选中：点提示框底部「选择指示器」切换，出现「斜杠眼睛」图标就表示这段对 Claude 隐藏了——选中只是想复制时用得上。
• 拖文件当附件：拖文件到提示框时按住 Shift；点附件上的 × 移除。

比如排查一个样式 bug，CSS 嵌套了五六层。直接选中那段可疑规则丢一句「这里为什么不生效」，它两轮就定位到是父元素的 overflow: hidden 把子元素裁了——光用文字描述那段嵌套，得打半天字。

⚠️ 选中文本和当前打开的文件默认会随提示发给 Claude。像 .env 这种敏感文件，官方建议给路径加一条 Read 拒绝规则，匹配上后它就不会到达 Claude（以官方文档为准）。

💡 一句话总结：@ 提及喂文件、选中代码自动喂上下文——把「你说的是哪段」这个最大的猜测成本直接干掉。

05 计划审阅：让它先交方案，你批了再动手

这一节大概是扩展相比终端体验提升最大的地方。先说权限模式：点提示框底部的模式指示器可以切换，Claude Code 有这么几档：

还有第四档 bypassPermissions（绕过所有权限检查），需在设置里开启 allowDangerouslySkipPermissions，仅适用于完全隔离的沙箱环境，日常不推荐开。

类比：实习生动手前问不问你。 正常模式是「每步先举手问」、自动接受是「放手让他干」——而计划模式最特别，像实习生先交一份「我打算这么做」给你过目，你点头了才开干。

计划模式在 VS Code 里有个终端给不了的待遇：Claude 会把计划自动作为一份完整的 Markdown 文档打开，你能在上面加内联批注。不用笼统回一句「第二步不对」，而是直接在「第二步」那行旁边写「这里别动数据库，先加缓存」，它开工前就把你的意见吸收进去——比口头返工精确得多。

上图是计划模式打开的 Markdown 计划文档：Claude 把每一步列出来，你在「第 2 步」那行旁边写下内联批注（「别动数据库，先加内存缓存」），它批准开工前就把这条意见吸收进去。

想让它成默认？把设置里的 claudeCode.initialPermissionMode 改成 plan。一个稳妥的习惯是凡是「多文件、超过 50 行」的改动，先切计划模式。这里有个常见教训：图省事全程开自动接受，让它给一个模块加日志，它可能顺手把好几个文件的导入顺序也「优化」了一遍，回头得花十分钟才理清它动了哪些地方。大改动一律先看计划，在方案阶段就框住它，比事后收拾干净得多。

💡 一句话总结：计划模式 = 先看方案再动手，还能在 Markdown 计划上逐条批注——多文件大改动前切它，省下大把返工。

06 动手环节：10 分钟跑通图形界面全流程

下面从零走一遍，每步都给了「你该看到什么」，照着做就能自验装没装对、会不会用。

第 0 步：建个最小练手项目

不用真项目，新建个空文件夹放个文件就行。终端跑：

mkdir vscode-claude-demo && cd vscode-claude-demo
printf 'def greet(name):\n    return "Hello " + name\n\nprint(greet("world"))\n' > demo.py
code .

预期：VS Code 打开这个文件夹，左侧资源管理器里能看到 demo.py。（没装 code 命令行工具就手动打开这个文件夹。）

第 1 步：打开 Claude 面板并登录

点开 demo.py（记住，一定要打开文件），点右上角 Spark 图标，首次出现登录屏就点登录、在浏览器完成授权。

预期：右侧出现 Claude Code 对话面板，顶部不再显示「未登录」。

第 2 步：选中代码 + 让它改，看内联 diff

选中 demo.py 里 greet 函数那两行，提示框下方应显示「已选中 2 行」。这时输入：

帮我把它改成用 f-string，并加上类型注解

预期：Claude 没问你「哪个函数」（说明选中上下文喂进去了），直接弹出并排 diff——右边把 return "Hello " + name 改成 return f"Hello {name}"、签名加了类型注解，下方出现接受 / 拒绝提示。看清再点接受。

第 3 步：试一次计划模式

点提示框底部的模式指示器切到 Plan Mode，输入一个稍大的需求：

给这个文件加上命令行参数支持，让用户能从终端传入名字

预期：Claude 不直接改文件，先打开一份 Markdown 计划文档列出打算怎么做（比如引入 argparse）。你确认或在某步旁边写批注，它再执行。跑到这步，内联 diff、选中提及、计划审阅三个核心你就都用过一遍了。

07 顺手收藏：常用快捷键和「切到 CLI」

一组常用快捷键（来自官方，平台差异已标）：

macOS Tahoe+ 有个坑：系统「游戏覆盖」默认占用了 Cmd+Esc，会把它截胡。去「系统设置 → 键盘 → 键盘快捷键 → 游戏控制器」清掉那个勾，或把 Claude Code: Focus input 重新绑到别的键。

想用回 CLI 风格界面？ 打开集成终端（Cmd+` / Ctrl+`）跑 claude 即可——CLI 会自动连上 VS Code，照样能用原生 diff（外部终端则跑 /ide 手动连）；或在设置勾上 使用终端（useTerminal）让扩展直接以终端模式启动。

第三方提供商（Bedrock / Vertex AI / Foundry）：先勾 禁用登录提示（disableLoginPrompt），再按提供商指南配 ~/.claude/settings.json（以官方文档为准）。

💡 一句话总结：Cmd+Esc 切焦点最常用、Option+K 插引用，想回终端味就跑 claude 或勾 useTerminal——图形和命令行随你换。

08 小结

这一篇把 Claude Code 从终端搬进了 VS Code，核心就这几件事：

• 扩展 ≠ 替代 CLI：同一个引擎、共享历史和配置，写代码用扩展、要 CLI 专属功能就切终端。
• 装好的第一关是找图标：认准 Anthropic 发布者，Spark 图标得开着文件才出现，找不到就用右下角状态栏入口。
• 三个图形界面爽点：并排 diff（看清再点头、能当场改）、@ 提及 / 选中代码（喂准上下文）、计划审阅（先看方案、能逐条批注）。

你现在应该能独立装好扩展、用并排 diff 审阅改动、用 @ 和选中喂准上下文、大改动前切计划模式。这套流程跑顺了，日常写代码就能稳定靠它。

下一篇 09 JetBrains 集成——如果你的主力是 IntelliJ IDEA、PyCharm 这类 JetBrains 全家桶，Claude Code 同样有原生插件。我们会看看它和 VS Code 扩展有哪些一样、哪些不一样，以及 JetBrains 用户特有的几个配置点。

09 · JetBrains 集成

A：「我天天泡在 PyCharm 里，VS Code 那套扩展跟我没关系吧？」

B：「有原生插件，装一下，Cmd+Esc 就能从编辑器里把 Claude 叫出来。」

A：「那它跟 VS Code 扩展是一回事？diff、@ 提及那些都有？」

B：「内核是同一个 CLI，但界面不是同一拨人做的——有些地方一样，有些地方你得换个姿势。比如它默认是跑在 IDE 自带终端里的，不是一个独立面板。」

这是用 GoLand 写后端的人常有的疑问，很典型：JetBrains 用户总担心自己是「二等公民」，好东西都先给 VS Code。

说句实话，这担心一半对一半不对。对的地方：JetBrains 插件确实比 VS Code 扩展更轻，它是把 CLI 跟 IDE 接通、让信息在两边流动，而不是做一个大而全的图形面板。不对的地方：该有的核心体验一个没少。

这一篇就讲清楚：怎么装、怎么连、和 VS Code 比差在哪、JetBrains 专属的几个坑（ESC 键、WSL、远程开发）怎么填。

看完这一篇，你会拿到：

• 在 IntelliJ / PyCharm / WebStorm 等 JetBrains IDE 里装好 Claude Code 插件的完整步骤
• 「IDE 内置终端」和「外部终端 /ide」两种连接方式，分别什么时候用
• 一张「JetBrains 插件 vs VS Code 扩展」的对照表，外加 JetBrains 专属快捷键
• ESC 键中断失灵、WSL2「检测不到 IDE」、远程开发这三个高频坑的官方解法

01 先理清楚：插件到底做了什么

很多人装完插件一脸懵：「我装了插件，怎么没看到一个像 VS Code 那样的聊天面板？」

先给结论：JetBrains 插件不是一个独立的聊天窗口，它是一座「桥」。Claude Code 本体还是那个跑在终端里的 CLI，插件干的活是把 IDE 和 CLI 接通——你在编辑器里选中的代码、IDE 报的 lint 错误、Claude 想做的改动，能在「IDE」和「终端里的 Claude」之间自动来回传。

类比：手机和电脑之间的隔空投送（AirDrop）。 文件、剪贴板本来各待各的设备上，开了隔空投送两台设备就「认识」了——电脑上复制，手机上直接粘。插件就是 IDE 和 Claude 之间的这条通道：你在 PyCharm 里选中一段代码，终端里的 Claude 立刻就「看见」了，不用复制粘贴。

所以有个关键认知：

在 JetBrains 里，你跟 Claude 对话的地方，是 IDE 自带的集成终端——不是一个新开的侧边面板。

这是和 VS Code 最大的体感差异：VS Code 扩展给你一个图形对话面板；JetBrains 则让你在内置终端里跑 claude，插件在背后喂上下文。对话在终端、diff 弹到 IDE 原生查看器，两边好处都占着，而且几乎零学习成本——命令、快捷键、/ 斜杠命令全是终端那一套。第一次在 IntelliJ 装插件，本来还会担心要重新适应界面，结果发现就是熟悉的那个终端 Claude，只是它突然「长了眼睛」，能看到你选了什么、IDE 标红了哪里。

💡 一句话总结：JetBrains 插件是 IDE 和 CLI 之间的「隔空投送」，对话在内置终端里发生、diff 弹进 IDE，不是一个独立聊天面板。

02 支持哪些 IDE，先对个号

JetBrains 是一整个家族，不是单个软件。好消息是：Claude Code 插件覆盖了主流的几乎全部。

官方明确列出的支持名单：

官方说法是「适用于大多数 JetBrains IDE」——名单外的 JetBrains IDE（RubyMine、CLion、Rider 等）大概率也能用，但官方没背书，能装上就用、出问题以「未明确支持」对待。

类比：同一品牌的不同车型，共用一套车机系统。 IntelliJ、PyCharm、WebStorm 就像同厂家的轿车、SUV、跑车，定位不同但底层是同一个平台（都构建在 IntelliJ Platform 上）。所以一个插件通吃，这篇里所有操作步骤，不管你用 IntelliJ 还是 GoLand，菜单路径都一致。下面演示用 PyCharm。

上图把这层关系画清楚了：最上面的 Claude Code 插件只有一个，向下扇出适配每个 IDE；而 IntelliJ IDEA、PyCharm、WebStorm 等虽各管一门语言，却都坐在同一个 IntelliJ Platform 底座上——所以一个插件装一次，处处能用，安装配置步骤也处处一致。

💡 一句话总结：主流 JetBrains IDE 都支持，它们共用同一个 IntelliJ 平台底座——安装和配置步骤在哪个 IDE 里都一模一样。

03 安装：插件 + CLI，缺一不可

这步最容易出岔子，因为 JetBrains 集成需要两样东西都到位：插件，和 Claude Code CLI 本体，少哪个都不行。

类比：手机 App + 后台账号。 装了 App（插件）却没注册后台账号（CLI），打开就是个空壳——插件负责界面集成，真正干活的「后台」是 CLI。所以装插件前先确认 CLI 在。

第一步：先确认 CLI 装好了

跟着这个系列从头读的话，第 02 篇就装好 CLI 了。不确定就在任意终端跑：

claude --version

预期输出：打印出一串版本号，类似 2.x.x (Claude Code)。

如果提示 command not found，说明 CLI 还没装。回到 02 安装 那篇装一下，或者用官方安装命令（分平台）：

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

国内提示：安装 CLI、之后的登录授权、以及让 Claude 干活，全程都要连 Anthropic 的服务，需要魔法上网。这点和终端版、VS Code 版都一致。

第二步：装 JetBrains 插件

两条路都能走，推荐第一条。

方式一：IDE 里搜（推荐）

1. 打开你的 JetBrains IDE
2. 进 Settings（设置）→ Plugins（插件）（Mac 快捷键 Cmd+,，Windows/Linux Ctrl+Alt+S）
3. 切到 Marketplace（市场） 标签
4. 搜索 Claude Code
5. 点 Install（安装）
6. 装完务必重启 IDE

方式二：去插件市场官网装

直接访问 JetBrains 插件市场的 Claude Code 页面，按页面指引安装。

注意插件名带 [Beta] 后缀——说明它还在 Beta 阶段，行为可能随版本变化（以官方文档为准）。功能能用，但别当板上钉钉的稳定版。

第三步：重启 IDE（别跳过）

官方专门强调了一句：

安装插件后，你可能需要完全重启 IDE 才能让它生效。

「完全重启」是彻底退出再打开，不是关个窗口。这个坑很容易栽进去——装完在 IDE 里跑 claude，集成功能死活不激活，以为插件坏了；彻底退出 IntelliJ 重开，一切正常。这坑官方也列在「插件不工作」排查第一条，足见多常见。

💡 一句话总结：JetBrains 集成 = CLI 本体 + 插件，两样都要装；装完一定完全重启 IDE，这是最高频的「装了不生效」原因。

04 连接：两种姿势，看你从哪启动

插件装好、IDE 重启完，下一步是把 Claude Code 跟 IDE「连上」。连上后，选区共享、diff 弹进 IDE、诊断共享才会激活。 连接方式取决于你从哪里启动 Claude。

姿势一：从 IDE 内置终端启动（推荐，自动连）

最省事。打开 IDE 自带的集成终端（一般在底部，有个 Terminal 标签页），直接跑：

claude

预期：Claude Code 启动，所有集成功能自动激活，不用任何手动连接动作。因为你在 IDE 的「肚子里」启动，插件天然知道该跟哪个 IDE 接通。

类比：在自家客厅连 Wi-Fi。 在家里打开手机自动连上，不用输密码。内置终端启动 Claude 就是这体验——环境对了，连接自动完成。

姿势二：从外部终端启动，用 /ide 手动连

如果你习惯用 iTerm、Windows Terminal 这类独立终端，那就先启动 Claude，再手动接通：

claude

然后在 Claude 对话里输入：

/ide

预期：Claude 列出检测到的 JetBrains IDE，选中对应的那个，连接建立、功能激活。类比：在别人家连 Wi-Fi，得手动选网络——/ide 就是这个动作。

一个容易忽略的前提：从项目根目录启动

不管哪种姿势，官方都强调：

如果你希望 Claude 能访问和 IDE 相同的文件，请从与 IDE 项目根目录相同的目录启动 Claude Code。

说白了：IDE 打开的是哪个项目，就在那个项目的根目录下启动 claude。在 ~/Downloads 这种目录启动，Claude 看到的文件就和 IDE 里的项目对不上号了。用内置终端启动天然满足这点——这也是推荐姿势一的另一个原因。

一般全程用 IDE 内置终端就够了——连接自动完成、目录天然对齐、终端和代码同窗口，Cmd+Esc 一按就在两者间跳。除非手头已经开着外部终端在跑别的，才用 /ide 临时接一下。

💡 一句话总结：IDE 内置终端启动 = 自动连、目录天然对齐（推荐）；外部终端启动 = 跑 /ide 手动连。无论哪种，都从项目根目录启动。

05 它能干什么：五个集成功能

连上之后，插件给的「增益」官方列了五个，逐一说，重点看和 VS Code 的差异，汇总看本节末的对照表。

• ① 快速启动：编辑器里按 Cmd+Esc（Mac）/ Ctrl+Esc（Windows/Linux）直接打开 Claude，也可点 UI 里的按钮。这个用得最勤——写着代码想问一句，不用鼠标点终端标签，一个快捷键焦点就过去了。
• ② 选区上下文共享：IDE 里当前选中的代码、或打开的标签页，自动共享给 Claude。选中一段问「这段为什么报错」，它知道你指哪段。
• ③ 文件引用快捷键：按 Cmd+Option+K（Mac）/ Alt+Ctrl+K（Linux/Windows）插入一条文件引用，形如 @src/auth.ts#L1-99，带路径和行号，让 Claude 精确定位。
• ④ Diff 查看：代码改动直接在 IDE 的 diff 查看器里展示，而非终端里用文本符号画（默认不一定开，得设 auto，下节讲）。
• ⑤ 诊断共享：IDE 的 lint 警告、语法错误那些红线黄线，自动共享给 Claude，它能直接「看到」标红了哪里，不用你复述报错。

两个安全 / 易错点单独拎出来：

⚠️ 安全（和 VS Code 一致）：如果文件命中你设的 Read 拒绝规则，它的选区共享会被拦住、不发给 Claude（以官方文档为准）。.env 这类敏感文件建议加上。

⚠️ 易错：文件引用快捷键和 VS Code 不一样——VS Code 是 Option+K / Alt+K，JetBrains 多一个键，是 Cmd+Option+K / Alt+Ctrl+K，从 VS Code 切过来最容易按错。

诊断共享这点体会最深。JetBrains 的代码检查本就是业界最强之一——搁以前得把标红的报错复制给终端 Claude，现在它直接读得到。比如 PyCharm 标了一个「未使用的导入」加几个类型不匹配的黄线，只说一句「把 IDE 标出来的问题修一下」，它就照着诊断一条条修了，不用你贴一行报错。

💡 一句话总结：五大增益里选区共享、诊断共享、diff 弹进 IDE 和 VS Code 基本一致；最大差异是对话跑在内置终端，还有文件引用快捷键多按一个键。

06 配置：把 diff 调出来，再调插件

装好连上还不够，有两处配置值得花两分钟调一下，体验差很多。

配置一：把 diff 工具设成 auto（重要）

前面说过 diff 能弹进 IDE，但这取决于一个配置项。在 Claude Code 里跑 /config，找到 diff 工具（diff tool），设为 auto：

/config

这里强烈建议设 auto——既然用了 IDE，就把 JetBrains 那个好用的并排 diff 视图利用起来，终端文本 diff 在改动一多时真费眼。

配置二：插件设置（Settings → Tools → Claude Code [Beta]）

插件本身的设置藏在 Settings → Tools → Claude Code [Beta] 里。几个值得知道的：

• Claude command（Claude 命令路径）：默认 claude；如果你的 claude 不在标准 PATH 里，可填绝对路径（如 /usr/local/bin/claude）或 npx @anthropic-ai/claude-code。点 Claude 图标提示「command not found」时，多半就是这里要配。
• 抑制「Claude 命令未找到」的通知：嫌提示烦可以关掉。
• 启用 Option+Enter 多行输入（仅 macOS）：开启后提示框里 Option+Enter 插入换行。Option 键被意外捕获、影响打字就关掉它，改完需重启终端。
• 启用自动更新：自动检查并安装插件更新，重启时应用。

这几项里最该记的是最上面那行 Claude command 路径——点 Claude 图标报「command not found」，十有八九就是它要配。

💡 WSL 用户特别注意：把 Claude 命令设成 wsl -d Ubuntu -- bash -lic "claude"（把 Ubuntu 换成你的 WSL 发行版名）。

💡 一句话总结：进 Claude Code 跑 /config 把 diff 设成 auto，再去 Settings → Tools → Claude Code [Beta] 调插件——其中 Claude command 路径是排查「命令未找到」的关键。

07 JetBrains 用户专属的三个坑

下面这三个坑，是 JetBrains 用户比 VS Code 用户更容易撞上的，官方单独列了解法。

坑一：ESC 键中断失灵

JetBrains 终端有个老毛病：你想按 ESC 中断 Claude 正在跑的操作，结果焦点「啪」一下跳到编辑器去了，操作没断成。 原因是它默认把 ESC 绑成了「把焦点移到编辑器」。解法：

1. 进 Settings → Tools → Terminal
2. 二选一：取消勾选 「使用 Escape 将焦点移动到编辑器」（Move focus to the editor with Escape），或点「配置终端快捷键」删掉「切换焦点到编辑器」（Switch focus to Editor）这个绑定
3. 应用更改

改完 ESC 就能正常中断了。强烈建议装完就顺手改掉——不然某次 Claude 跑飞了你想叫停，按 ESC 没反应，那一下是真急。

坑二：WSL2 提示「未检测到可用的 IDE」

在 WSL2 上用 Claude Code + JetBrains IDE，跑 /ide 经常报 「No available IDEs detected」。根因不是插件坏了，而是 WSL2 的 NAT 网络或 Windows 防火墙，把「WSL2 里的 Claude」和「Windows 上的 IDE」的连接挡了（WSL1 不受影响）。官方给了两个方案，推荐方案一（放行防火墙），因为它不动现有网络模式：

# 第一步：在 WSL shell 里查 IP
hostname -I
# 假设输出 172.21.123.45，记下子网 172.21.0.0/16

# 第二步：以管理员身份开 PowerShell，建防火墙规则（IP 范围按你的子网改）
New-NetFirewallRule -DisplayName "Allow WSL2 Internal Traffic" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16 -LocalAddress 172.21.0.0/16

然后重启 IDE 和 Claude Code 让规则生效。

方案二是把 WSL2 切成「镜像网络」（需 Windows 11 22H2 或更高），在 Windows 用户目录的 .wslconfig 里加 [wsl2] 段、设 networkingMode=mirrored，再 wsl --shutdown 重启。用 Windows 10 的别折腾镜像网络，直接用方案一。

坑三：远程开发，插件得装在「远程主机」

如果你用 JetBrains 的 远程开发（Remote Development）——本地客户端连到远程服务器写代码——有个反直觉的点：

插件必须装在「远程主机」上，不是装在你本地的客户端机器上。

安装路径是 Settings → Plugin (Host)。常见的翻车是在本地客户端装了插件，怎么都连不上，折腾半天才发现装错地方。记住：Claude 实际在哪台机器干活，插件就装哪台。 远程开发里干活的是远程主机，插件就归它。

💡 一句话总结：ESC 失灵改终端快捷键、WSL2 检测不到放行防火墙、远程开发插件装远程主机——这三个是 JetBrains 专属高频坑，装完顺手把 ESC 那个改掉。

08 动手环节：10 分钟在 JetBrains 里跑通全流程

下面这套从零走一遍，每步都给了「你该看到什么」，照着做就能自验。用 PyCharm 演示，其他 JetBrains IDE 步骤完全一样。

第 0 步：确认 CLI 在 —— 跑 claude --version，预期打印版本号（如 2.x.x (Claude Code)）；报 command not found 就先回 02 安装。

第 1 步：装插件并重启 —— PyCharm → Settings → Plugins → Marketplace，搜 Claude Code → Install，完全退出 PyCharm 再重开。预期重启后 Settings → Tools 下能看到 Claude Code [Beta]。

第 2 步：建个最小练手项目 —— 新建文件 demo.py：

def greet(name):
    return "Hello " + name

print(greet("world"))

第 3 步：从 IDE 内置终端启动 Claude —— 打开 PyCharm 底部的 Terminal 标签跑 claude。预期集成功能自动激活（内置终端启动，无需 /ide）；首次会引导你登录 Anthropic 账户，浏览器完成授权。

第 4 步：把 diff 设成 auto —— 在 Claude 里跑 /config，把 diff 工具设为 auto，这样下一步改动会弹进 PyCharm 的 diff 查看器。

第 5 步：选中代码 + 提问，验证选区共享

在编辑器里选中 greet 函数那两行，回到 Claude 终端，输入：

这段选中的函数有什么可以改进的地方？

预期：Claude 基于你选中的两行作答（可能建议用 f-string、加类型注解）——它没反问你「哪个函数」，说明选区共享生效了。这是验证「隔空投送」通没通的关键一步。

第 6 步：让它改，看 diff 弹进 IDE

接着输入：

帮我把它改成用 f-string，并加上类型注解

预期：因为上一步设了 auto，改动在 PyCharm 的 diff 查看器里并排显示——左边原始 return "Hello " + name，右边改后 return f"Hello {name}"，签名也加了类型注解。看清楚了再接受。

跑到这步，插件装好、CLI 连通、选区共享、diff 弹进 IDE 这四件核心你就都验过一遍了。要是第 5 步它反问你哪个函数、或第 6 步 diff 没弹进 IDE，回头按第 03、04、06 节查。

09 小结

这一篇把 Claude Code 装进了 JetBrains 全家桶，核心就这几件事：

• 插件是「桥」不是「面板」：它把 IDE 和 CLI 接通，对话跑在 IDE 内置终端、diff 弹进 IDE 原生查看器，不像 VS Code 给你一个独立聊天面板。
• 装要装两样：CLI 本体 + 插件，缺一不可；装完一定完全重启 IDE，这是最高频的「装了不生效」原因。
• 连有两种姿势：IDE 内置终端启动自动连（推荐）、外部终端跑 /ide 手动连；都从项目根目录启动。
• 三个专属坑：ESC 中断失灵（改终端快捷键）、WSL2 检测不到 IDE（放行防火墙）、远程开发插件装远程主机。

你现在应该能：在自己的 JetBrains IDE 里独立装好插件、把 Claude 和 IDE 连通、用选区共享把上下文喂准、让改动弹进 IDE 的 diff 查看器审阅。JetBrains 用户不是二等公民——该有的核心体验一个没少。

到这里，VS Code 和 JetBrains 两大 IDE 阵营都覆盖了。它们的共同点是：都要先有一个 IDE，再把 Claude 接进去。 那如果你压根不想开 IDE，只想要一个独立的、开箱即用的 Claude 客户端呢？

下一篇 10 桌面 app（Desktop）——Claude Code 还有个独立的桌面应用，不依附任何编辑器，双击就能用。我们看看它适合什么人、和 IDE 集成版怎么取舍，以及它有哪些 IDE 版给不了的便利。

10 · 桌面 app（Desktop）

都说命令行才是 Claude Code 的「正统玩法」，桌面 app 顶多是给小白的简化版——说句实话，这个判断现在已经过时了。

很多人一开始也是这么想的。可一旦同时改三个互不相干的需求，在终端开三个 tab，改着改着自己就乱了：哪个 tab 在改登录、哪个在重构数据层，切来切去看错好几次。换桌面 app 重试同样的活，左边一栏列着三个会话，每个自动用 Git worktree 隔开，改动互不污染，点一下就切过去——这时候才意识到，这玩意儿不是「简化版 CLI」，它是另一种工作方式。

更关键的是：桌面 app、VS Code 扩展、命令行，跑的是同一个底层引擎，共享同一份 CLAUDE.md 和配置。所以这不是「换个弱化的工具」，而是同一个 Claude Code 换了个更适合并行、更适合可视化审阅的外壳。

什么时候该用它、什么时候老老实实回终端，这篇给你讲清楚。

看完这一篇，你会拿到：

• macOS / Windows 上装好桌面 app 的完整步骤，外加「为什么 Linux 用不了」的明确说明
• 桌面 app 三个独有的爽点：并行会话 + Git 隔离、集成终端 / 文件编辑、可视化 diff 审阅怎么用
• 一张「桌面 app vs 终端 vs IDE 扩展 该用哪个」的对照表，以及一条把终端会话一键搬进桌面的命令

01 先搞清楚：桌面 app 到底是什么

很多人一看到「桌面应用」，第一反应是：那不就是 claude.ai 的客户端、套个壳的聊天框吗？

不是。 先给结论：桌面 app 是带图形界面的完整 Claude Code，专门为「同时跑多个会话」而生。它跟终端里的 claude 跑的是同一个引擎，能直接读写你本地的文件、改代码、跑命令，只是把这些操作搬进了一个有侧边栏、有窗格布局的窗口里。

类比：同一台车，换了套仪表盘。 命令行是赛车里那种纯数字仪表——信息全、反应快，但你得自己看懂每个读数；桌面 app 是家用车的大屏中控——并行任务、改动 diff、应用预览全都摆在面上，一眼能扫完。发动机是同一台，跑出来的结果一模一样，区别只在你坐进去舒不舒服。

这里有个容易混的点：桌面 app 打开后，顶部有三个选项卡，别搞错你要去哪个。

这一篇只讲 Code 选项卡——它才是「桌面版 Claude Code」。Chat 和 Cowork 属于 Claude Desktop 的另外两块功能，跟咱们写代码这条线关系不大。

💡 一句话总结：桌面 app 不是聊天客户端套壳，它是带图形界面的完整 Claude Code，认准 Code 选项卡就对了。

02 装它：三个平台，差别很大

先把最重要的一条放最前面：Linux 没有桌面 app。

这不是漏装了什么，是官方明确不提供——Linux 用户请直接用 CLI（前面第 02 篇讲过怎么装）。所以下面只说 macOS 和 Windows。

这张流程图把从下载到发出第一条指令的整条路径串起来，并标出了两道容易卡住的关：付费订阅（免费号点 Code 会跳升级页）和 Windows 装 Git（装完要重启 app），右下角也顺带提醒了 Linux 没有桌面 app。下面分平台细说每一步。

装之前先确认：你得有付费订阅

这条很多人栽过。桌面 app 的 Code 选项卡要求 Pro、Max、Team 或 Enterprise 订阅，免费账号点进去会直接提示你升级。常见的踩坑场景是：拿免费号点 Code 一直跳升级页，还以为是装坏了——其实是订阅没到位。

macOS

去官方下载页拿 Universal 版（Intel 和 Apple Silicon 通用），下载 .dmg 安装、拖进应用程序文件夹，启动后用 Anthropic 账号登录，点顶部中间的 Code 选项卡。

macOS 一般自带 Git，桌面 app 的并行会话隔离依赖它。不放心的话，在终端跑一句确认：

git --version

预期输出类似（版本号不重要，能打印出来就行）：

git version 2.39.5 (Apple Git-154)

Windows

x64 处理器下载 .exe 安装程序；Windows ARM64 要单独下 ARM64 安装包，别拿错。

Windows 有个 macOS 没有的硬门槛：Code 选项卡的本地会话必须先装 Git for Windows。在一台新装的 Windows 上很容易踩这个坑——没装 Git 就点 Code，弹出一句红色的 Git is required，会话压根起不来。装完 Git 记得重启应用，否则它读不到。

另外 Windows 上有些库还要 Git LFS，碰到 Git LFS is required by this repository but is not installed 这种报错，就去 git-lfs.com 装上、跑一句 git lfs install，再重启应用。

一句重要提醒：桌面 app 自带 Claude Code，不用你单独装 Node.js 或 CLI。但反过来，如果你还想在终端里敲 claude，那个 CLI 得另外装（见第 02 篇）——两者是分开的两份程序，只是共享配置。

💡 一句话总结：Linux 没有、免费号用不了；macOS 拿 Universal 版即装即用，Windows 必须先装 Git 再重启。

03 爽点一：并行会话 + Git 自动隔离

这是桌面 app 最值得用的理由，没有之一。

先说问题：终端并行的痛

你肯定遇到过这种场景：手头三个任务，修个登录 bug、加一组测试、顺手重构一下工具函数。在终端里你只能开三个 tab 各跑一个 claude，但它们改的是同一份工作目录里的文件——A 会话改了 utils.js，B 会话也想动它，两边的改动就会互相打架。

桌面 app 怎么解的

桌面 app 的做法很干净：点侧边栏的 + New session 开一个新会话，如果项目是 Git 仓库，它会自动给这个会话拉一份独立的 Git worktree。

类比：图书馆的独立研究间。 你和另外两个人都在看同一套藏书（同一个仓库），但每人分到一间隔音的研究间（worktree），各看各的、各写各的笔记，互不干扰；等你整理好了（提交），成果才汇回总馆。在你提交之前，一个会话的改动绝不会污染另一个会话。

侧边栏列着你所有会话，Ctrl+Tab / Ctrl+Shift+Tab 在它们之间循环切换（这两个键所有平台都用 Ctrl，不是 Cmd）。想同时看两个会话？macOS 按住 Cmd、Windows 按住 Ctrl 点侧边栏里的另一个会话，它会在旁边分屏打开。

几个实用细节

• worktree 存哪：默认在 <项目根>/.claude/worktrees/。可以在「设置 → Claude Code → Worktree location」改成别的目录。
• 想把 .env 这类 gitignore 文件也带进 worktree：在项目根目录建一个 .worktreeinclude 文件，列出要带的文件（以官方文档为准）。
• 会话用完怎么清：鼠标悬到侧边栏的会话上，点归档图标，对应的 worktree 就删掉了。
• PR 合并后自动归档：在「设置 → Claude Code」打开 Auto-archive after PR merge or close，跑完的本地会话会自己收掉。

一个值得养成的习惯是：一个 PR 配一个会话。改完提交、开 PR、合并，会话自动归档，桌面始终干干净净，不用手动记「哪个 tab 在干嘛」。比起在终端开五六个 tab 自己数，心智负担小太多。

💡 一句话总结：每个会话自动一份 Git worktree，并行改多个需求互不污染——这是桌面 app 相对终端最实在的优势。

04 爽点二：集成终端 + 文件编辑，不用切来切去

桌面 app 的 Code 选项卡是围绕窗格（pane）搭的：聊天、diff、预览、终端、文件、计划、任务……你想怎么摆就怎么摆。拖窗格标题挪位置、拖窗格边缘改大小，跟拼积木似的。

注意：窗格布局、集成终端、文件编辑器这套需要 Claude Desktop v1.2581.0 或更高版本。版本低就先去「Check for Updates」更新（以官方文档为准，版本号可能变化）。

集成终端：和 Claude 共享同一个环境

从 Views 菜单打开终端，或者直接按 Ctrl+`（这个键也是全平台 Ctrl）。

它最妙的一点是：终端开在会话的工作目录里，跟 Claude 共享同一个环境。所以你在这个终端里跑 npm test 或 git status，看到的就是 Claude 正在改的那一份文件，不会出现「Claude 改了但我终端里看的是旧的」这种错位。

这解决了用 VS Code 扩展时的一个老麻烦：以前得自己保证终端 cd 到了对的目录，现在直接省了——它本来就在对的地方。

提醒：集成终端只在本地会话里有，远程会话用不了。

文件编辑器：点路径就能改

点聊天或 diff 里的任意文件路径，文件就在文件窗格里打开了。直接改、点 Save 写回磁盘。

如果你打开文件之后它在磁盘上被改过（比如 Claude 又动了一次），窗格会警告你，让你选覆盖还是丢弃，不会闷头把别人的改动盖掉。

一个细节：HTML、PDF、图片、视频这类路径，点了不是在文件窗格打开，而是去预览窗格——这个下一节细说。文件窗格在本地和 SSH 会话可用；远程会话改文件得直接让 Claude 动手。

顺手记一下：视图模式

聊天记录默认把工具调用折叠成摘要（Normal 模式）。想看 Claude 到底每一步干了啥，按 Ctrl+O 循环切到 Verbose；想只看最终结果和改动，切到 Summary。调试「它为什么这么干」时 Verbose 很有用，并行扫多个会话结果时 Summary 最快。

💡 一句话总结：终端共享工作目录、文件点开即改——该有的开发工具都在一个窗口里，不用满屏切应用。

05 爽点三：可视化 diff 审阅，改对没改对一眼看清

这是图形界面相对纯终端最直观的提升。

终端里 Claude 改完代码，diff 是一片绿加红的文本流；桌面 app 把它变成了能点、能批注、能让 Claude 自审的可视化界面。

diff 怎么看

Claude 改了文件后，会冒出一个 +12 -1 这样的小指示器（加了 12 行、删了 1 行）。点它就打开 diff 查看器：左边一栏列改动的文件，右边显示每个文件具体改了哪儿。

在某一行直接批注

这是整套 diff 审阅里最好用的地方：点 diff 里的任意一行，弹出批注框，输入你的反馈按 Enter。想批注多行就一行行点、一条条写，最后一次性提交所有批注：

• macOS：Cmd+Enter
• Windows：Ctrl+Enter

Claude 读完你的批注，按要求改，改完又是一份新 diff 给你审。这一来一回，比在终端里打字描述「第 23 行那个变量名改一下」精准太多——你直接戳在那行上说话。

让 Claude 先自审一遍

diff 查看器右上角有个 Review code 按钮。点它，Claude 会在你提交前先把这份改动审一遍，直接在 diff 里留批注，你可以回复或让它改。

注意它审的是高信号问题：编译错误、明显的逻辑 bug、安全漏洞这类。它不挑代码风格、格式、或者 linter 本来就能抓的东西——那些交给 linter 就好。

改完开 PR，CI 还能盯着

开了 PR 之后，会话里会冒出一条 CI 状态栏，Claude Code 用 GitHub CLI 轮询检查结果。两个开关值得知道：

• Auto-fix：CI 挂了，Claude 自动读失败日志、试着修。
• Auto-merge：所有检查通过后自动合并 PR（合并方式是 squash，且需要你在 GitHub 仓库设置里开过 auto-merge）。

前提：PR 监控需要你机器上装好并登录了 GitHub CLI（gh）。没装的话，第一次开 PR 时桌面 app 会提示你装。

实测下来，逐行批注 + Review code 这套组合，已经能替代大半的「人肉 code review 第一遍」。以前 Claude 改完得逐文件扫一遍找问题，现在让它先自审，只复核它标出来的高信号点，一轮下来省不少眼力。

💡 一句话总结：diff 能点能逐行批注、还能让 Claude 先自审高信号问题，再配 CI 自动修——「改对没改对」从靠眼力变成靠界面。

06 桌面 app vs 终端 vs IDE 扩展：到底用哪个

讲到这你可能更纠结了：手上明明有终端的 claude、有 VS Code 扩展，现在又来个桌面 app，到底该用哪个？

先给一句官方原话定调：

想在一个窗口里管理并行会话、并排摆窗格、可视化审阅改动，用 Desktop；需要脚本、自动化或更喜欢终端工作流，用 CLI。

把三者摊开对比，按「你最在意什么」来选：

看出门道了吗？三者不是替代关系，是各有主场：

• 要脚本化、跑 CI 流水线、用国产 / 第三方模型 → 老老实实用 CLI，桌面 app 干不了这些。
• 主力就在 VS Code / JetBrains 里写码 → 用 IDE 扩展，代码和 AI 在同一个窗口最顺。
• 同时推好几个独立任务、想可视化审阅 → 桌面 app 的主场。

而且它们能同时用、甚至同一个项目同时用——共享 CLAUDE.md、MCP server、hooks、skills、settings.json。一个顺手的搭配是：日常写码在 VS Code 扩展，一旦要并行铺开三四个独立需求就切桌面 app，需要批量自动化才回终端写脚本。

⚠️ 注意：像 /permissions、/config、/agents、/doctor 这种会在终端弹交互面板的命令，在 Code 选项卡里用不了，会回你一句 isn't available in this environment。要改权限规则或配置，直接编辑 settings.json，或回独立 CLI 跑。

💡 一句话总结：CLI 管自动化、IDE 扩展管写码、桌面 app 管并行 + 可视化——三者共享配置、各打各的主场，按当下需求切就行。

07 动手：装好桌面 app，跑通第一个会话

光看不练假把式。下面走一遍从装到跑通第一个会话的最小流程，每步都给你能自验的预期结果。

第一步：装好并打开 Code 选项卡

按第 02 节装好（macOS 拿 Universal 版，Windows 先装 Git）。打开应用、登录，点顶部中间的 Code 选项卡。

✅ 自验：能看到左侧有会话侧边栏、中间是提示框，说明 Code 选项卡正常。若点 Code 跳升级页 → 你是免费账号，得先订阅 Pro/Max。

第二步：选环境 + 项目文件夹

发第一条消息前，提示区要配四样东西：

• 环境：选 Local（在你本机跑、直接读写文件）。另有 Remote（云端）和 SSH（你自己的远程机器），先用 Local 最简单。
• 项目文件夹：点 Select folder，挑一个你熟的小项目——别拿祖传大仓库练手。
• 模型：发送按钮旁的下拉菜单选，Opus / Sonnet / Haiku 都行，会话中途能换。
• 权限模式：保持默认的 「询问权限」（default），新手最稳。

第三步：发第一条指令

提示框里输入一个具体的小任务，比如官方给的示例：

找一条 TODO 注释，把它修掉

或者：

给这个代码库创建一个 CLAUDE.md，写上项目说明

按 Enter 发送。

第四步：审阅并接受改动

因为是「询问权限」模式，Claude 不会直接改文件，它会先给你一份 diff。你会看到：

1. 一份 diff 视图，显示每个文件具体要改哪儿
2. 接受 / 拒绝按钮
3. Claude 处理时的实时进度

✅ 预期结果：你点接受之前，磁盘上的文件不会被动。这就是「询问权限」模式的安全感——看清楚再点头。拒绝的话，Claude 会问你想怎么改。

第五步（可选）：把终端会话搬进桌面

如果你之前在终端 claude 里聊到一半想换到桌面 app，不用重开。在终端会话里敲：

/desktop

Claude 会保存当前会话、在桌面 app 里打开它，然后退出 CLI。

注意：/desktop 仅 macOS / Windows 可用，且只在你用 Claude 订阅登录时能用——API key 登录、或 Bedrock / Vertex / Foundry 部署都不支持（以官方文档为准）。

08 小结

这一篇把 Claude Code 的第三个入口——桌面 app——讲清楚了，核心就这几条：

• 它是带图形界面的完整 Claude Code，不是聊天套壳：跟终端同一个引擎、共享 CLAUDE.md 和配置，认准 Code 选项卡。
• 装它三个平台差很大：Linux 没有；免费号用不了（要 Pro/Max 起）；Windows 必须先装 Git 再重启。
• 三个独有爽点：并行会话 + Git worktree 自动隔离、集成终端 / 文件编辑共享同一环境、可视化 diff 能逐行批注还能让 Claude 自审。
• 三者各打主场：自动化用 CLI、写码用 IDE 扩展、并行 + 可视化用桌面 app，能同时用。

你现在应该能：在 macOS / Windows 上独立装好桌面 app、开多个并行会话且明白它们靠 worktree 隔离、用可视化 diff 审阅并批注 Claude 的改动、并清楚什么时候该切回终端。把并行这套跑顺，同时推几个需求就不再手忙脚乱了。

下一篇 11 网页版与云端（Web / 手机）——桌面 app 里那个 Remote 环境、还有手机上能瞄进度的能力，到底是怎么回事？我们会看看不开电脑、甚至人不在工位时，怎么让 Claude Code 在云端接着替你干活。

11 · 网页版与云端：把 Claude Code 装进浏览器和手机

我前阵子在高铁上，临时收到一条消息——线上一个仓库的 README 里把安装命令写错了，得赶紧改。

手边没带电脑，只有一台手机，外加那种时断时续的车厢 WiFi。

放在以前，这就是「等到了再说」。但我当时掏出手机打开 claude.ai/code ，选中那个仓库，敲了一句「修正 README 里的安装命令，npm 包名应该是 xxx」，就把手机塞回兜里了。等出站的时候，一个改好的分支已经躺在 GitHub 上等我提 PR 了——前后大概十来分钟，一行命令都没敲过，电脑全程没开。

这就是这一篇要聊的两件事：网页版（在云端跑、连 GitHub）和 Remote Control（让手机 / 任意设备接管你本地的会话）。说白了，就是把「必须坐在电脑前敲命令」这个前提给拆了。

⚠️ 注意：网页版和 Remote Control 目前都处于研究预览（research preview）阶段，功能和细节可能随时变化，本篇以官方文档当前版本为准。

看完这一篇，你会拿到：

• 搞清楚网页版到底是啥：免安装、在云端沙箱跑、连你的 GitHub 仓库
• 一套从登录到提任务、再到提 PR 的完整网页版操作流程，照着走就行
• Remote Control 是怎么回事：在电脑上起个会话，用手机 / 别的浏览器接着指挥
• 一张「网页版 vs 本地 CLI vs Remote Control」的取舍对照表，知道什么时候用哪个
• deep-links 一键起会话、国内访问要点这些零碎但有用的细节

01 先把三个东西分清楚：本地、网页、远控

开篇先泼盆冷水：很多人一上来就把「桌面 app」「网页版」「Remote Control」搅成一锅粥，结果用错场景，越用越懵。咱们先花一分钟把它们掰开。

类比：同一份工作，三种到岗方式。

• 本地 CLI / 桌面 app：你亲自到办公室上班，电脑、文件、工具全在手边——上一篇讲的桌面 app 就是这种，代码跑在你自己机器上。
• 网页版（on the web）：你派了个远程同事，他在公司租的云服务器上干活，你只需要在浏览器里给他派活、看结果。代码跑在 Anthropic 的云上，不碰你的电脑。
• Remote Control（远程控制）：你人在办公室、活也在你办公室的电脑上跑，但你用手机远程遥控那台电脑。代码还是跑在你机器上，手机只是个「遥控器窗口」。

记住这条最关键的分界线：

代码到底在谁的机器上跑？ 网页版在 Anthropic 云上跑；Remote Control 和本地一样，始终在你自己机器上跑。

这条线决定了一切——能不能访问你本地的文件、要不要联网克隆仓库、断网了会不会停。后面所有取舍都从这儿派生。

💡 一句话总结：本地是「亲自到岗」、网页版是「派云端同事」、Remote Control 是「手机遥控你的电脑」；先认准代码在谁机器上跑，剩下的全好理解。

看这张图就能搞清楚：哪端只是个窗口，哪端才是真正干活的地方。

02 网页版是什么：浏览器打开就能用

先给结论：网页版就是把 Claude Code 搬到了云上，你不用装任何东西，打开网页就能让它干活，干完直接给你提 PR。

它跑在 claude.ai/code ，在 Anthropic 管理的云虚拟机（cloud VM）里运行——这是一台一次性的隔离机器，每次任务都新克隆你的仓库进去。

类比：租了台一次性的云电脑，用完即焚。 你不用自己配环境、装依赖，云端那台机器开机时已经预装好了 Python、Node、Go、Docker 一大堆工具。Claude 在那台机器上读代码、改代码、跑测试，结束后把改动以一个 GitHub 分支推给你。那台机器跟你本地电脑完全隔离，它崩了、被搞坏了，都伤不到你一根头发。

它适合这几类真实场景：

• 并行跑多个任务：每个任务一个独立会话、独立分支，互不打架。比如一口气派三个活——修一个 flaky 测试、补一份 API 文档、重构日志模块，三个云会话同时在跑，你喝着咖啡等结果就行。
• 本地没克隆的仓库：想顺手看一眼某个仓库、改个小东西，但你本地根本没 clone 它。网页版每次都帮你新克隆，省了你 git clone 再配环境那一整套。
• 不想配本地环境：换了台新电脑、或者在别人机器上，懒得装一长串依赖。

有两个前提得说清楚，免得你白忙活：

1. 它需要一个 GitHub 仓库。网页版靠克隆 GitHub 仓库来干活，没仓库它没法开工。
2. 目前是研究预览，开放给 Pro、Max、Team 用户，以及有高级席位或 Chat + Claude Code 席位的 Enterprise 用户。

还有个很爽的点：会话在设备间持久化（persist）。你在电脑浏览器上派的任务，关掉网页它照样在云端跑，回头用手机打开 Claude app 就能接着看进度。开头那个高铁上改 README 的场景，就是靠这条——派完任务锁屏，到站再看结果。

💡 一句话总结：网页版 = 云端一次性沙箱 + 连 GitHub 仓库 + 免安装，适合并行跑活、改本地没克隆的仓库、不想配环境；前提是有 GitHub 仓库、是 Pro / Max / Team 用户。

03 网页版 vs 本地 CLI：到底该用哪个

这两个不是替代关系，是分工关系。实测下来，判断标准就一句话：

这活需不需要碰我电脑上的东西？ 需要，就老老实实用本地 CLI；不需要，云端跑更省事。

为什么？因为网页版那台云机器只有你仓库里的东西——凡是你只在自己电脑上装的、配的（比如某个本地工具、你 ~/.claude/CLAUDE.md 里的全局指令、claude mcp add 加的 MCP server），云端统统看不见。要让云端用上，得把配置提交进仓库（比如写进仓库的 .claude/settings.json、.mcp.json）。

来张对照表，一眼看清取舍：

有一行我得专门点一下：网页版的权限模式只有两种——「自动接受编辑（Auto accept edits）」和「Plan 模式」，没有你在第 07 篇里熟悉的那种「每次改动都跳出来问你」的默认（default）模式。

这意味着什么？默认情况下，云端的 Claude 改完文件直接推分支，不会停下来一行行等你点同意。所以派云端任务时，任务描述一定要写清楚、写具体——它不会中途回头问你「这样改行不行」。这个亏我自己头一回用就吃了：图省事派了个模糊的「优化一下这个日志模块」，回来一看，它自作主张把整套日志重构了一遍、连接口都改了，远不是我想要的那点小改动，最后那个分支我直接弃了重派。后来我学乖了，云端任务一律写明白文件名、要改什么、预期行为。

💡 一句话总结：碰本地东西用本地 CLI，不碰本地、想并行或想随处可用就上网页版；记住网页版默认「自动接受编辑」，所以任务描述务必写具体。

04 Remote Control：让手机接管你本地的会话

网页版是「把活搬到云上」，Remote Control（远程控制）走的是另一条路：活还在你电脑上跑，但你能从手机 / 任意浏览器去指挥它。

先给结论：Remote Control 让你在办公桌上起一个本地会话，然后从沙发上的手机、或另一台电脑的浏览器接着聊——代码自始至终在你自己机器上跑，没有任何东西上云。

类比：给你的电脑装了个远程遥控器。 你的文件系统、本地 MCP server、各种工具、项目配置——全都还在、全都能用，跟你坐在电脑前没区别。网页和手机界面只是那个本地会话的一扇「窗户」，你透过窗户发指令，活在窗户后面的电脑上干。

它和网页版的根本区别，还是那条老分界线：

Remote Control 在你的机器上执行，所以你的本地 MCP server、工具和项目配置都还在。网页版在 Anthropic 云上执行。

什么时候用它？官方给的判断很清楚：你正干着本地的活，临时想换个设备接着弄，就用 Remote Control。一个很典型的场景——下班前在公司电脑上让 Claude 跑一个耗时的重构。人直接走，到家用手机打开 Claude app，会话还连着公司那台电脑，躺床上就能看它跑到哪了、给它发下一条指令。

启动也简单。在你的项目目录里跑这一行，就进入「服务器模式」，它会挂在终端等远程连接：

claude remote-control

跑起来后，终端里会显示一个会话 URL，按空格键还能调出一个二维码——手机扫一下，直接在 Claude app 里打开这个会话。

如果你已经在一个 Claude Code 会话里头了，想把当前这次对话直接转成可远程的，不用重开，直接敲：

/remote-control

（嫌长可以用别名 /rc。）它会继承你当前的对话历史，照样给你一个 URL 和二维码。

几个硬性前提记一下，不满足会连不上：

• 版本：需要 Claude Code v2.1.51 或更高，claude --version 查一下。
• 登录方式：必须用 claude.ai 账号 /login 登录，不支持 API key。
• 本地进程得一直开着：Remote Control 本质是个跑在你电脑上的本地进程，你一关终端、退出 claude，会话就结束了。

还有个挺贴心的：当 Remote Control 活着的时候，长任务跑完或者需要你拿主意时，Claude 能给你手机推送通知。你也可以在指令里直接要求，比如「测试跑完了通知我」。（推送通知需要 v2.1.110 或更高。）

💡 一句话总结：Remote Control = 本地会话 + 手机 / 浏览器当遥控器，代码全程在你机器上跑、本地配置全都在；claude remote-control 起服务、扫码即连，但本地进程不能关。

05 别搞混：--remote 和 --remote-control 是两码事

这俩长得太像了，官方文档专门反复强调过，新手一开始也很容易踩这个坑——它们干的根本是相反的方向。一行表说清：

看出门道了吧：

• --remote（带任务）= 我人在终端，但想把活甩到云上去跑，自己腾出手干别的。
• --teleport = 云上那个会话我想拽回本地接着弄（比如要用本地工具了）。注意这是单向的：你能把云会话拉回本地，但不能把一个已存在的本地终端会话推上云。
• --remote-control = 跟云一点关系没有，纯粹是把我本地这个会话开个窗口让别的设备看 / 控。

举个常见用法：复杂任务可以先在本地 Plan Mode 规划（让 Claude 出方案但不动代码），方案满意了推送到 GitHub，再一句 claude --remote "执行 docs/ 里的迁移方案" 把执行甩到云上自主跑。策略你把控，体力活云端干——这套「本地规划、远程执行」用起来很顺手。

💡 一句话总结：--remote 把活送上云、--teleport 把云会话拉回本地（单向）、--remote-control 是本地会话开远程窗口——三个方向，千万别记混。

06 deep-links：一个链接直接起会话

最后补一个小而美的功能：deep-links（深链接）。

它解决的问题是：有时候你想给别人（或给未来的自己）一个一键起点——点一下链接，Claude Code 就在对应的仓库里打开，提示词都帮你填好了。

类比：给同事发一个「点开即用」的快捷方式。 比起跟人解释「你 clone 这个仓库、cd 进去、然后敲这段话」，直接甩个链接过去，对方点一下，会话开好、提示填好，省事多了。典型用在事故处理手册、监控告警、CI 失败通知里——点开就在出问题的仓库里带着诊断提示开干。

深链接是个 claude-cli:// 开头的 URL，长这样：

claude-cli://open?repo=acme/payments&q=review%20open%20PRs

repo 指定一个 GitHub 的 owner/name 仓库，q 是预填的提示词（要 URL 编码，%20 就是空格）。点开它，你机器上会弹出一个新终端，Claude Code 在你 acme/payments 那个本地克隆里启动，提示框里已经填好了「review open PRs」。有个前提要注意：repo 只认识你至少跑过一次 claude 的路径——如果你从来没在那个克隆里启动过 Claude Code，它找不到记录，会话会回落到你的主目录，而不是仓库目录。

这里有条安全设定得记牢，挺重要：

深链接本身永远不会执行任何操作。它只是选好目录、把提示填进输入框。在你看过内容、亲手按下回车之前，没有任何东西会发给模型。

换句话说，哪怕你从一个不信任的页面点了深链接，它也只是帮你把字打进去，主动权始终在你手里。（深链接需要 v2.1.91 或更高。）

💡 一句话总结：deep-links 用一个 claude-cli:// 链接帮你「选好仓库 + 填好提示」一键起会话，但只填不发，按回车前一切可控。

07 动手：起一个本地会话，用手机接管它

光说不练没意思。下面这个最小练习，让你亲手体验一次「电脑起会话、手机接管」——不用 GitHub、不用任何项目，几分钟搞定。

第一步：确认版本够新

claude --version

预期：版本号 ≥ 2.1.51。低于这个数，先 claude update 升级，否则 Remote Control 起不来。

第二步：在任意一个文件夹里起服务器模式

随便找个目录（沿用第 07 篇那个 hello-claude 也行），敲：

claude remote-control

预期：终端不会像平时那样进入聊天，而是显示一段「等待远程连接」的状态，外加一个会话 URL。这是对的——服务器模式就是挂在这儿等手机连。

第三步：调出二维码

在那个状态界面里，按一下空格键。

预期：终端里画出一个二维码。（如果你还没装 Claude 手机 app，可以先在另开的 Claude Code 里敲 /mobile，它会给你 app 的下载二维码。）

第四步：手机扫码接管

用装好 Claude app 的手机扫这个码。

预期：手机的 Claude app 里打开了这个会话，你电脑的终端会显示连接状态变化。这时你在手机上发一句话，比如：

列出当前目录下有哪些文件

预期：活在你电脑上跑（它读的是你那台机器的目录），结果同步显示在手机上。看到手机上列出了你电脑当前目录里的文件 = 你已经成功用手机接管了本地会话，全流程跑通，恭喜！

第五步：收摊

回到电脑终端，按 Ctrl+C 停掉 claude remote-control。

预期：服务器模式退出，远程会话随之结束——记得，本地进程一关，会话就没了。

⚠️ 要是手机连不上、或报「Remote Control 需要 claude.ai 订阅」，九成是登录方式不对：Remote Control 只认 claude.ai 账号，不认 API key。先在终端 /login 用 claude.ai 账号登录，并确认环境里没设 ANTHROPIC_API_KEY。

08 国内访问：先把魔法上网备好

这一篇讲的所有功能，都绕不开一个现实门槛——它们全都连 claude.ai 这套域名：网页版在 claude.ai/code 跑，Remote Control 和手机 app 也都往 Anthropic 的服务器发请求。

所以结论很直接：国内用户用网页版、Remote Control、手机 app 之前，先把「魔法上网」准备好，否则页面打不开、手机 app 连不上、二维码扫了也没反应。这跟前面装本地 CLI 时的网络要求是一回事，只是这回连手机端也得在能正常访问的网络环境下。

一个容易忽略的细节：云会话里的 Claude 是从 Anthropic 的云基础设施访问网络的，不是从你的网络。所以云端那台机器拉 npm 包、克隆 GitHub 仓库走它自己的通道，跟你本地的魔法上网无关——你需要魔法上网的地方，只是「浏览器 / 手机怎么连上 claude.ai」这一段。

💡 一句话总结：网页版 / Remote Control / 手机 app 全都连 claude.ai ，国内用之前先备好魔法上网；但云会话内部的联网走 Anthropic 自己的网络，不归你管。

09 小结

这一篇，咱们把 Claude Code 从「必须坐在电脑前敲命令」彻底解放了出来，主要拿下两件事：浏览器免安装直接用（网页版），和用手机 / 任意设备接管本地会话（Remote Control）。

把核心区别再钉一遍：

你现在应该能： 分清本地、网页版、Remote Control 三者的根本差别（代码在谁机器上跑），知道网页版怎么连 GitHub 提任务提 PR、默认是「自动接受编辑」所以任务要写具体，会用 claude remote-control + 扫码让手机接管本地会话，也不会再把 --remote 和 --remote-control 搞混。这套「随处可用」的能力，是把 Claude Code 真正塞进你日常工作流的关键一步。

下一篇 12「项目初始化：用 /init 生成 CLAUDE.md」——不管你是在本地、网页还是手机上用 Claude Code，它干得好不好，很大程度取决于那个仓库里有没有一份像样的 CLAUDE.md 。下一篇就教你用一条 /init 命令，让 Claude 自己把项目摸一遍、生成第一版「项目说明书」。你不妨先想想：如果让一个新同事接手你的项目，你最想先告诉他哪三件事？