如果你平时主要工作在本地 Windows 或 macOS但又需要在 Linux 服务器上跑 Claude Code那你大概率会遇到一个很现实的问题直接在服务器终端里操作虽然能用但编辑代码、查看文件、写 prompt 的效率实在太低了。我折腾了一段时间之后最终固定下来的方案是Linux 服务器装 Claude Code本地用 VS Code 的 Remote-SSH 插件连过去把远程终端和编辑器无缝变成本地体验。这套组合不光解决了“远程跑 AI 编程助手”的问题还一并把文件编辑、代码调试、日志查看这些日常操作全部统一到一个窗口里。这篇文章就把我踩过的坑、验证过的步骤、以及一些不太好查的细节全部整理出来写给同样想入坑的读者。先说清楚这套方案适合谁你手上有一台 Linux 服务器云主机或家里闲置机器都行想在上面跑 Claude Code同时又不想忍受纯终端环境下的操作别扭感希望用本地 VS Code 像操作本地项目一样去操作远程环境。整个过程不需要图形界面完全命令行可完成对新手也足够友好。我会从 Linux 端的环境准备讲起再到 VS Code SSH 连接最后覆盖 Claude Code 的使用要点和常见问题排查尽量做到拿着文章就能一步步跟下来。1. 方案拆解为什么是 Linux Claude Code VS Code SSH1.1 三个组件各自扮演什么角色Claude Code 本身是一个运行在终端里的 AI 编程助手它的核心能力是理解你的代码仓库、读取文件、执行命令、生成修改建议。它不是一个图形化软件而是一个命令行工具所以它需要的是一个能够长时间稳定运行的终端环境。Linux 服务器天然满足这个要求资源占用可控、可以7x24小时运行、权限管理体系完善尤其适合把 Claude Code 当成一个“团队里的常驻工程师”挂在那里用。VS Code 在这套方案里扮演的是“前端操作层”。它本身不直接运行 Claude Code而是通过 SSH 协议连接到远程 Linux 服务器后在你本地窗口里渲染出远程的文件树、终端、代码高亮等界面。你在这边敲的每一个命令、编辑的每一个文件实际上都在远程服务器上执行。这就是 Remote-SSH 插件的核心逻辑本地只是显示器远程才是真正的计算主体。用生活里的例子类比Claude Code 像是远程机房里的一个工程师VS Code SSH 像是你桌面上的一个监控屏幕和遥控器。你不需要真的坐在机房里面也能看到这个工程师在改什么文件、跑什么命令还能随时递一张纸条也就是你的 prompt告诉他下一步做什么。1.2 这个方案解决了哪些痛点纯终端操作用 Claude Code 不是不行但有几个明显的体验问题。第一Claude Code 在回答问题时会同时展示修改过的文件 diff纯终端里查看 diff 虽然可以用方向键翻页但对比效率远不如编辑器里的颜色标注直观。第二当 Claude Code 生成或修改代码后你通常需要立刻打开文件确认改动如果还要用 vim 或 nano 单独打开操作成本就上来了。第三多窗口协作困难一边要看日志一边要编辑配置一边还要和 Claude Code 对话纯终端下往往需要开多个 tmux 面板对新手来说是额外的学习成本。VS Code SSH 方案把这些问题全部合并解决远程文件直接以图形化目录树展示点击即可编辑内置终端可以直接唤起 Claude Code编辑器自带的 diff 视图能让你一眼看出 Claude Code 改了什么甚至可以在同一个窗口里分栏左边是代码右边是 Claude Code 对话终端。1.3 整体架构和准备清单整套系统的逻辑链路是这样的本地机器安装 VS Code安装 Remote-SSH 插件生成 SSH 密钥对。远程 Linux 服务器安装 Node.js 环境安装 Claude Code配置 API 认证开放 SSH 登录权限。连接过程本地 VS Code 通过 SSH 密钥认证登录远程服务器自动下载并启动 VS Code Server 服务端组件然后在本地窗口中渲染远程界面。动手之前建议先准备好几样东西一台能通过 SSH 访问的 Linux 服务器Ubuntu 22.04 或 Debian 12 这类主流发行版最省心、本地 Windows/macOS 电脑上的 VS Code版本不要太老、一个可用的 Claude 账号和 API 密钥。另外需要确认本地到服务器的 22 端口网络通畅这个可以通过一条简单的 telnet 命令或 ssh 命令本身来验证。2. Linux 端环境准备给 Claude Code 安一个稳固的家2.1 检查系统版本与基础环境拿到一台全新的 Linux 服务器我建议先确认系统版本和基础工具链避免后面装依赖时装到一半才发现缺东缺西。登录服务器后依次执行下面几条命令cat /etc/os-release uname -m which curl wget git第一句是看发行版名称和版本号第二句是看 CPU 架构绝大多数云服务器是 x86_64但也可能遇到 ARM 架构的机器这会影响后面 Node.js 安装包的选型。第三句是确认 curl、wget、git 这些基础工具是否已经存在如果提示 not found先用系统的包管理器补上。以 Ubuntu/Debian 为例sudo apt update sudo apt install -y curl wget git这一步看似基础但很多后续问题的根因都在环境不完整上。Claude Code 安装时要用 curl 下载脚本运行时要依赖 git 读取仓库信息缺了任何一个都会产生莫名其妙的报错。2.2 安装 Node.js版本选择有讲究Claude Code 官方要求 Node.js 版本在 18 以上我实际测试下来建议直接上 20 LTS 或 22 LTS老版本组件对 ESM 模块和异步 API 的支持不完整可能会在运行时报一些难以排查的错误。Ubuntu 自带 apt 源里的 Node.js 版本往往偏旧很多还是 18 或更早所以推荐用 NodeSource 源安装。curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs安装完成后验证版本node -v npm -v这里有一个细节值得注意不要用 sudo 去全局安装 Claude Code。原因在于 Claude Code 会读取当前用户的配置目录和密钥文件如果用 root 安装再切换到普通用户使用很容易出现“命令找不到”或者“权限被拒绝”的问题。正确的做法是让 Claude Code 安装在普通用户的用户目录下而不是系统全局。2.3 安装 Claude Code 本体环境就绪后安装本身其实只有一条命令npm install -g anthropic-ai/claude-codenpm 全局安装的默认路径一般在 /usr/lib/node_modules 或者 /usr/local/lib/node_modules具体取决于系统配置。安装完成后先验证命令是否存在且可用claude --version如果提示找不到命令最可能的原因是 npm 的全局 bin 目录没有加入 PATH。可以先执行npm prefix -g查看全局目录再把对应的 bin 目录加到 shell 配置里。以 Ubuntu 上常见的情况为例在~/.bashrc末尾追加export PATH$PATH:$(npm prefix -g)/bin然后执行source ~/.bashrc让配置生效。这条 PATH 问题的排查思路适用于几乎所有 npm 全局安装的命令行工具不只是 Claude Code。2.4 API 密钥配置与首次启动Claude Code 运行需要认证凭证。安装好后第一次执行claude程序会提示你进行登录。在较新版本中认证方式大致可以分为两类一类是通过浏览器登录 Claude 账号完成授权另一类是直接使用 API 密钥。API 密钥的方式对服务器环境更友好因为服务器上没有浏览器可用。如果选择 API 密钥方式需要在环境变量里设置export ANTHROPIC_API_KEY你的密钥为了不让密钥在每次重启 shell 后失效建议写进~/.bashrc或~/.profile中。但要注意文件权限防止其他用户读取chmod 700 ~/.bashrc首次启动claude时它会扫描当前目录的结构读取.git信息可能还会提示你允许它执行哪些类别的命令。这些权限设置在后续使用中可以通过/permissions命令随时调整不需要担心一开始选错。3. 本地 VS Code 配置SSH 远程访问全流程实操3.1 本地 VS Code 安装与 Remote-SSH 插件本地机器上安装 VS Code 没有太多门槛直接去官网下载对应系统的安装包即可。需要注意的是版本不要太老Remote-SSH 插件对 VS Code 版本有最低要求我建议保持在最新稳定版。装好 VS Code 后在扩展市场搜索“Remote - SSH”认准发布者是 Microsoft 的那个扩展。安装后左侧边栏会出现一个远程资源管理器图标所有远程连接的管理都在这里完成。另外推荐一起装两个辅助插件Remote - SSH: Editing Configuration Files用来编辑 SSH 配置文件时获得语法高亮和 Remote Explorer提供远程目录树浏览增强。这两个不是必须但能显著提升配置体验。3.2 SSH 密钥对生成与公钥部署密码登录虽然简单但每次连服务器都要输密码而且 VS Code 在密码认证模式下偶尔会出现反复弹窗的问题。建议直接用 SSH 密钥对做免密登录一劳永逸。在本地机器上执行ssh-keygen -t ed25519 -C your_emailexample.comed25519 是目前推荐的密钥算法比传统的 RSA 更短更安全性能也更好。执行后会询问保存路径和 passphrase直接回车使用默认路径~/.ssh/id_ed25519即可。passphrase 可以设置也可以不设置如果设置了每次使用密钥时都要输入该短语可以用 ssh-agent 来缓存避免频繁输入。生成完成后把公钥部署到远程服务器ssh-copy-id -i ~/.ssh/id_ed25519.pub userserver_ipssh-copy-id 会自动把公钥追加到服务器上对应用户的~/.ssh/authorized_keys文件里。如果服务器上还没有这个文件它会自动创建同时设置好权限。这里有一个关键点authorized_keys文件的权限必须是 600.ssh目录权限必须是 700否则 sshd 会拒绝使用该公钥认证。如果不小心用chmod改错了权限会出现“明明公钥已经部署但登录时还是要求密码”的情况。3.3 Remote-SSH 连接配置详解打开 VS Code点击左侧远程资源管理器图标选择“SSH Targets”然后点击齿轮图标编辑 SSH 配置文件。这个文件通常在~/.ssh/configWindows 上可能是C:\Users\你的用户名\.ssh\config。一个典型的最小配置如下Host my-ai-server HostName 192.168.1.100 User ubuntu Port 22 IdentityFile ~/.ssh/id_ed25519这里解释一下几个字段的作用。Host 是你给这台服务器起的别名之后在 VS Code 里连接时只需要选这个别名不用记 IP。HostName 是真实 IP 或域名。User 是登录用户名一定要和服务器上实际存在的用户一致。IdentityFile 指定使用的私钥路径。如果服务器 SSH 端口不是默认的 22在 Port 字段修改即可。配置保存后在远程资源管理器中点击目标服务器旁边的“Connect to Host”按钮VS Code 会在新窗口中尝试连接。第一次连接时VS Code 会自动在远程服务器上下载并安装 VS Code Server 组件这个过程需要一点时间取决于服务器和本地之间的网络状况。连接成功后窗口左下角会显示“SSH: my-ai-server”之类的标识说明你已经进入远程开发模式。3.4 连接之后的体验调优刚连上远程服务器时VS Code 是一个相对干净的界面扩展也需要区分本地和远程。你可以把常用扩展安装在远程端比如 Python、ESLint、Prettier 等。安装方法是在扩展面板中查找所需插件然后选择“Install in SSH: my-ai-server”这样插件就会部署到远程服务器上只在你连接这台远程主机时生效。终端面板是 Remote-SSH 体验的核心。按 Ctrl 打开终端此时终端默认就是 SSH 到服务器的 shell直接输入claude 就能进入 Claude Code 交互界面。如果你在本地终端和远程终端之间切换容易混可以给终端窗口改名或者在 VS Code 的终端下拉菜单里看到每个终端对应的主机标识一目了然。另一个值得调的细节是 VS Code 的remote.SSH.showLoginTerminal设置如果 SS 登录过程中遇到问题打开这个选项可以在终端中看到完整的 SSH 登录日志对排查非常有用。4. Claude Code 核心用法在远程环境里把它用出效率4.1 会话启动与工作目录选择进入远程终端后首先 cd 到你的项目目录然后再执行claude。这一点非常重要因为 Claude Code 的工作范围默认就是当前目录它会读取该目录下的文件结构、git 状态、语言配置以此为依据回答问题和修改代码。如果你在 home 目录下启动它扫描的范围很大不仅响应慢还可能产生不必要的误修改。实际工作中我通常会在项目根目录启动cd ~/projects/my-app claude启动后你会看到 Claude Code 的交互提示符直接输入自然语言指令即可。比如“帮我看一下这个项目的依赖有没有冲突”它会自己读 package.json、锁文件然后给出分析。4.2 高频命令与快捷操作速查Claude Code 的交互界面支持一些斜杠命令这些命令是高频使用的我列一个我自己常用的速查表命令作用/help显示所有可用命令和帮助/status查看当前对话的上下文、token 消耗等情况/compact压缩当前对话历史降低上下文占用/clear清空当前会话重新开始/permissions查看和修改命令执行权限/review让 Claude Code 审查最近改动或指定文件/add-dir将指定目录加入上下文范围/memory管理长期记忆配置跨会话的偏好这些命令可以在交互状态下直接输入也可以在命令行中带参数运行。除了斜杠命令每次对话中 Claude Code 有时会征求你的确认例如“是否运行 npm test”这类问题直接输入 y 或 n 即可响应。4.3 让 Claude Code 更“懂”你的项目Claude Code 的上下文理解能力很强但它默认只能看到启动时扫描到的东西。如果项目里有一些核心约定、架构设计文档建议显式告诉它。比如在项目根目录建一个 CLAUDE.md 文件里面用自然语言描述项目的目录结构、编码规范、常用命令、注意事项等Claude Code 会自动读取这个文件并作为行为参考。我的 CLAUDE.md 通常长这样# 项目说明 这是一个基于 React TypeScript 的前端项目使用 pnpm 作为包管理器。 # 编码规范 - 组件文件使用 PascalCase 命名 - 样式使用 CSS Modules - 禁止直接修改 lock 文件 # 常用命令 - 启动开发服务器pnpm dev - 运行测试pnpm test - 构建pnpm build实际体验下来加了这份文件之后Claude Code 给出的代码风格和命令建议明显更贴合项目习惯很少再出现“用 npm 而不是 pnpm”这类低级偏差。4.4 与 VS Code 文件编辑联动的技巧你可能已经发现VS Code 远程终端里跑着 Claude Code而 VS Code 的编辑器又能直接打开远程文件。这意味着 Claude Code 修改文件之后你在编辑器里可以立刻看到变化。这里有个非常实用的组合操作让 Claude Code 修改代码后自己打开对应的文件用编辑器的 diff 功能查看改动。具体做法是在 Claude Code 输出修改结果后它会报告“Modified src/utils.ts”之类的信息你在 VS Code 的文件树中找到这个文件点击打开。VS Code 底部会显示文件的 git 变更状态用 CtrlShiftG 打开源代码管理面板就能看到每个文件的 diff高亮显示改动行配合 Claude Code 的修改说明你可以在几秒钟内完成人工 review。另外Claude Code 运行时间较长时建议在 VS Code 里开启终端多会话。比如在一个终端里跑claude做代码生成在另一个终端里跑测试命令验证结果互不阻塞。VS Code 终端面板右上角的加号可以新建终端或者用 CtrlShift 直接开新终端。5. 常见问题与排查实录5.1 SSH 连接失败从日志到解决方案SSH 远程连接是整套方案里最可能出问题的环节而且问题现象往往千奇百怪。我把最常见的几类整理成一张排查表现象可能原因解决方案Connection refused服务器 SSH 服务未启动或端口不对检查 sshd 状态sudo systemctl status sshd确认端口ss -tlnpPermission denied (publickey)公钥未正确部署或权限不对重新执行 ssh-copy-id检查服务器上 ~/.ssh 权限为 700authorized_keys 为 600Host key verification failed服务器系统重装或 IP 被复用本地执行ssh-keygen -R 服务器IP清除旧指纹后重连Bad owner or permissions on .ssh/configWindows 上 SSH 配置文件权限过宽右键配置文件设置权限仅限当前用户或使用 icacls 调整Connection timed out网络不通或防火墙拦截本地执行telnet 服务器IP 22验证端口检查云安全组入站规则这里要特别说一个容易被忽略的问题云服务器的安全组。很多云厂商默认只放行 22 端口但如果你改了 SSH 端口或者服务器所在网络有额外的防火墙策略就需要同步放行。排查时优先用telnet验证 TCP 层是否通再用 SSH 的-v参数看详细认证过程这样能快速定位问题层面。5.2 VS Code Server 下载失败第一次远程连接时VS Code 会在服务器上安装一个名为 vscode-server 的组件正常情况会自动完成但网络不佳或服务器处于受限网络环境时会出现“Failed to download VS Code Server”或“Failed to fetch”的报错。这个问题的根因是 VS Code Server 的下载源在远程无法访问或访问缓慢。解决思路有这么几条按推荐顺序尝试。第一检查服务器能否访问 VS Code 的下载域名如果只是偶发超时多试几次或者换一个网络时段。第二手动在服务器上下载对应版本的 VS Code Server 压缩包解压到指定目录。具体版本号可以从本地 VS Code 的Help - About里看到“Commit”字段然后在服务器上拼出下载链接。第三如果服务器是被代理控制的网络可以检查本地与远程的网络链路是否正常或者临时改用其他网络环境下载。手动安装的步骤大致是mkdir -p ~/.vscode-server/bin/commit-id cd ~/.vscode-server/bin/commit-id # 下载对应版本的 server 压缩包并解压 tar -xzf vscode-server-linux-x64.tar.gz --strip-components1解压完成后重新在本地连接VS Code 会检测到已存在的 server 组件并跳过下载。这个方法稍微繁琐但对于网络受限的服务器环境来说是可靠的兜底方案。5.3 Claude Code 启动失败或命令找不到claude命令找不到的问题在第二节已经讲过核心是 PATH 没配好。另外还有一类常见报错是启动时提示 Node.js 版本过低这类问题只需要把 Node.js 升级到 20 LTS 以上即可。如果服务器上同时存在多个 Node.js 版本比如用 nvm 装的还要确认当前 shell 默认指向的是哪个版本。启动过程中如果提示需要登录或 API 密钥无效先检查环境变量是否生效echo $ANTHROPIC_API_KEY如果输出为空说明环境变量没有在当前 shell 中加载检查~/.bashrc里是否写入了 export 语句以及是否执行过source ~/.bashrc。另外某些 Linux 发行版的默认 shell 可能是 zsh 或其他环境变量要写入对应的 rc 文件。5.4 权限问题汇总一次理清权限问题在 Linux 上几乎无处不在我把 Claude Code SSH 场景下最常遇到的权限相关坑整理出来Claude Code 无法写文件检查项目目录归属如果目录属于 root当前用户没有写权限。用sudo chown -R 当前用户:当前用户 项目目录修正。SSH 公钥认证失效检查~/.ssh目录和authorized_keys文件权限目录 700、文件 600 是硬性要求。npm 全局安装失败用普通用户安装不要 sudo。如果目录权限有问题用sudo chown -R $(whoami) $(npm prefix -g)修复。VS Code Server 目录权限异常如果曾用 root 连接过 VS Code~/.vscode-server目录可能被 root 占用普通用户无法写入。清理后重新连接即可。权限问题的排查思路其实很简单先看报错信息里涉及的路径再用ls -la确认该路径所有者和权限最后根据实际需求用 chown/chmod 修正。不要动不动就 chmod 777那样虽然能解决问题但会留下安全隐患。6. 安全加固与长期使用体验6.1 不要用 root 直接跑 Claude Code我在实际使用中最大的教训就是不要用 root 用户来跑 Claude Code。原因有三层第一Claude Code 会执行你给的指令如果指令中有创建文件、修改配置甚至安装软件的操作root 权限下这些操作不受限制一旦 AI 判断失误后果比普通用户严重得多。第二root 用户的配置和普通用户隔离如果误在 root 下初始化了 Claude Code 的认证后续切回普通用户又要重新配置。第三VS Code Remote-SSH 如果用 root 登录vscode-server 也会装在 root 的 home 目录下后续换用户连接就要重新下载安装浪费时间。正确的做法是在服务器上创建一个专门用于开发的用户sudo useradd -m -s /bin/bash devuser sudo passwd devuser sudo usermod -aG sudo devuser然后把这个用户的公钥加到它的~/.ssh/authorized_keys中后续所有操作都用这个用户完成。6.2 密钥与敏感信息管理API 密钥是 Claude Code 运行的核心凭证一定要妥善保管。不要把它提交到 git 仓库不要写在项目目录下的普通文本文件里。推荐的做法是写在~/.bashrc或~/.profile中并确保文件权限只有自己可读。如果你使用 systemd 服务或环境变量文件来管理密钥也要把对应文件的权限设为 600。SSH 私钥同样重要。本地机器的~/.ssh/id_ed25519文件建议设置权限为 600不要随意分享给他人。如果怀疑私钥泄露立即在服务器上从authorized_keys中移除对应公钥并重新生成一对新密钥。6.3 让远程开发保持流畅的小习惯用这套方案久了我总结出几个让体验更流畅的习惯。第一每次连接后先打开终端跑一下df -h检查服务器磁盘空间因为 VS Code Server 和 Claude Code 的缓存都可能占用磁盘满了之后各种奇怪问题就来了。第二Claude Code 对话历史较长时及时用 /compact 压缩上下文避免 token 消耗过快。第三大项目建议在 CLAUDE.md 里明确指定哪些目录不需要 Claude Code 扫描可以通过 .claudeignore 或类似机制排除 node_modules、dist 等目录加快启动速度并减少误操作。还有一个小技巧在本地 VS Code 里给远程终端配置多个预设配置比如一个默认的 bash 终端一个专门跑 Claude Code 的终端。这样每次打开远程窗口直接点对应配置就能进入工作状态省去重复输入的麻烦。7. 写在最后我踩过坑之后的几点体会整套方案从最初在纯终端里勉强使用 Claude Code到现在本地 VS Code 一键连接远程服务器流畅开发中间经历了不少折腾。最值得强调的一点是先把 SSH 链路打通再谈 Claude Code 的使用这个顺序不能反。SSH 连接是地基地基不稳后面所有的优化都白搭。另一个体会是Claude Code 的能力上限很大程度上取决于你给它多少上下文。通过 CLAUDE.md 把项目的约定、目录结构、常用命令写清楚它给出的结果质量会有质的提升。这个文件不需要写得多华丽把关键信息说清楚就行你会发现 AI 编程助手的表现直接上了一个台阶。最后如果你在实操中遇到文章里没覆盖到的问题不妨先从日志入手。无论是 SSH 的-v参数还是 Claude Code 的/status输出日志里通常都藏着真正的线索。远程开发这条路本质上就是不断和环境、权限、网络斗争的过程但只要把基础打牢后续的开发效率提升是实打实的。 Linux服务器上运行Claude Code的VS Code远程开发指南
如果你平时主要工作在本地 Windows 或 macOS但又需要在 Linux 服务器上跑 Claude Code那你大概率会遇到一个很现实的问题直接在服务器终端里操作虽然能用但编辑代码、查看文件、写 prompt 的效率实在太低了。我折腾了一段时间之后最终固定下来的方案是Linux 服务器装 Claude Code本地用 VS Code 的 Remote-SSH 插件连过去把远程终端和编辑器无缝变成本地体验。这套组合不光解决了“远程跑 AI 编程助手”的问题还一并把文件编辑、代码调试、日志查看这些日常操作全部统一到一个窗口里。这篇文章就把我踩过的坑、验证过的步骤、以及一些不太好查的细节全部整理出来写给同样想入坑的读者。先说清楚这套方案适合谁你手上有一台 Linux 服务器云主机或家里闲置机器都行想在上面跑 Claude Code同时又不想忍受纯终端环境下的操作别扭感希望用本地 VS Code 像操作本地项目一样去操作远程环境。整个过程不需要图形界面完全命令行可完成对新手也足够友好。我会从 Linux 端的环境准备讲起再到 VS Code SSH 连接最后覆盖 Claude Code 的使用要点和常见问题排查尽量做到拿着文章就能一步步跟下来。1. 方案拆解为什么是 Linux Claude Code VS Code SSH1.1 三个组件各自扮演什么角色Claude Code 本身是一个运行在终端里的 AI 编程助手它的核心能力是理解你的代码仓库、读取文件、执行命令、生成修改建议。它不是一个图形化软件而是一个命令行工具所以它需要的是一个能够长时间稳定运行的终端环境。Linux 服务器天然满足这个要求资源占用可控、可以7x24小时运行、权限管理体系完善尤其适合把 Claude Code 当成一个“团队里的常驻工程师”挂在那里用。VS Code 在这套方案里扮演的是“前端操作层”。它本身不直接运行 Claude Code而是通过 SSH 协议连接到远程 Linux 服务器后在你本地窗口里渲染出远程的文件树、终端、代码高亮等界面。你在这边敲的每一个命令、编辑的每一个文件实际上都在远程服务器上执行。这就是 Remote-SSH 插件的核心逻辑本地只是显示器远程才是真正的计算主体。用生活里的例子类比Claude Code 像是远程机房里的一个工程师VS Code SSH 像是你桌面上的一个监控屏幕和遥控器。你不需要真的坐在机房里面也能看到这个工程师在改什么文件、跑什么命令还能随时递一张纸条也就是你的 prompt告诉他下一步做什么。1.2 这个方案解决了哪些痛点纯终端操作用 Claude Code 不是不行但有几个明显的体验问题。第一Claude Code 在回答问题时会同时展示修改过的文件 diff纯终端里查看 diff 虽然可以用方向键翻页但对比效率远不如编辑器里的颜色标注直观。第二当 Claude Code 生成或修改代码后你通常需要立刻打开文件确认改动如果还要用 vim 或 nano 单独打开操作成本就上来了。第三多窗口协作困难一边要看日志一边要编辑配置一边还要和 Claude Code 对话纯终端下往往需要开多个 tmux 面板对新手来说是额外的学习成本。VS Code SSH 方案把这些问题全部合并解决远程文件直接以图形化目录树展示点击即可编辑内置终端可以直接唤起 Claude Code编辑器自带的 diff 视图能让你一眼看出 Claude Code 改了什么甚至可以在同一个窗口里分栏左边是代码右边是 Claude Code 对话终端。1.3 整体架构和准备清单整套系统的逻辑链路是这样的本地机器安装 VS Code安装 Remote-SSH 插件生成 SSH 密钥对。远程 Linux 服务器安装 Node.js 环境安装 Claude Code配置 API 认证开放 SSH 登录权限。连接过程本地 VS Code 通过 SSH 密钥认证登录远程服务器自动下载并启动 VS Code Server 服务端组件然后在本地窗口中渲染远程界面。动手之前建议先准备好几样东西一台能通过 SSH 访问的 Linux 服务器Ubuntu 22.04 或 Debian 12 这类主流发行版最省心、本地 Windows/macOS 电脑上的 VS Code版本不要太老、一个可用的 Claude 账号和 API 密钥。另外需要确认本地到服务器的 22 端口网络通畅这个可以通过一条简单的 telnet 命令或 ssh 命令本身来验证。2. Linux 端环境准备给 Claude Code 安一个稳固的家2.1 检查系统版本与基础环境拿到一台全新的 Linux 服务器我建议先确认系统版本和基础工具链避免后面装依赖时装到一半才发现缺东缺西。登录服务器后依次执行下面几条命令cat /etc/os-release uname -m which curl wget git第一句是看发行版名称和版本号第二句是看 CPU 架构绝大多数云服务器是 x86_64但也可能遇到 ARM 架构的机器这会影响后面 Node.js 安装包的选型。第三句是确认 curl、wget、git 这些基础工具是否已经存在如果提示 not found先用系统的包管理器补上。以 Ubuntu/Debian 为例sudo apt update sudo apt install -y curl wget git这一步看似基础但很多后续问题的根因都在环境不完整上。Claude Code 安装时要用 curl 下载脚本运行时要依赖 git 读取仓库信息缺了任何一个都会产生莫名其妙的报错。2.2 安装 Node.js版本选择有讲究Claude Code 官方要求 Node.js 版本在 18 以上我实际测试下来建议直接上 20 LTS 或 22 LTS老版本组件对 ESM 模块和异步 API 的支持不完整可能会在运行时报一些难以排查的错误。Ubuntu 自带 apt 源里的 Node.js 版本往往偏旧很多还是 18 或更早所以推荐用 NodeSource 源安装。curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs安装完成后验证版本node -v npm -v这里有一个细节值得注意不要用 sudo 去全局安装 Claude Code。原因在于 Claude Code 会读取当前用户的配置目录和密钥文件如果用 root 安装再切换到普通用户使用很容易出现“命令找不到”或者“权限被拒绝”的问题。正确的做法是让 Claude Code 安装在普通用户的用户目录下而不是系统全局。2.3 安装 Claude Code 本体环境就绪后安装本身其实只有一条命令npm install -g anthropic-ai/claude-codenpm 全局安装的默认路径一般在 /usr/lib/node_modules 或者 /usr/local/lib/node_modules具体取决于系统配置。安装完成后先验证命令是否存在且可用claude --version如果提示找不到命令最可能的原因是 npm 的全局 bin 目录没有加入 PATH。可以先执行npm prefix -g查看全局目录再把对应的 bin 目录加到 shell 配置里。以 Ubuntu 上常见的情况为例在~/.bashrc末尾追加export PATH$PATH:$(npm prefix -g)/bin然后执行source ~/.bashrc让配置生效。这条 PATH 问题的排查思路适用于几乎所有 npm 全局安装的命令行工具不只是 Claude Code。2.4 API 密钥配置与首次启动Claude Code 运行需要认证凭证。安装好后第一次执行claude程序会提示你进行登录。在较新版本中认证方式大致可以分为两类一类是通过浏览器登录 Claude 账号完成授权另一类是直接使用 API 密钥。API 密钥的方式对服务器环境更友好因为服务器上没有浏览器可用。如果选择 API 密钥方式需要在环境变量里设置export ANTHROPIC_API_KEY你的密钥为了不让密钥在每次重启 shell 后失效建议写进~/.bashrc或~/.profile中。但要注意文件权限防止其他用户读取chmod 700 ~/.bashrc首次启动claude时它会扫描当前目录的结构读取.git信息可能还会提示你允许它执行哪些类别的命令。这些权限设置在后续使用中可以通过/permissions命令随时调整不需要担心一开始选错。3. 本地 VS Code 配置SSH 远程访问全流程实操3.1 本地 VS Code 安装与 Remote-SSH 插件本地机器上安装 VS Code 没有太多门槛直接去官网下载对应系统的安装包即可。需要注意的是版本不要太老Remote-SSH 插件对 VS Code 版本有最低要求我建议保持在最新稳定版。装好 VS Code 后在扩展市场搜索“Remote - SSH”认准发布者是 Microsoft 的那个扩展。安装后左侧边栏会出现一个远程资源管理器图标所有远程连接的管理都在这里完成。另外推荐一起装两个辅助插件Remote - SSH: Editing Configuration Files用来编辑 SSH 配置文件时获得语法高亮和 Remote Explorer提供远程目录树浏览增强。这两个不是必须但能显著提升配置体验。3.2 SSH 密钥对生成与公钥部署密码登录虽然简单但每次连服务器都要输密码而且 VS Code 在密码认证模式下偶尔会出现反复弹窗的问题。建议直接用 SSH 密钥对做免密登录一劳永逸。在本地机器上执行ssh-keygen -t ed25519 -C your_emailexample.comed25519 是目前推荐的密钥算法比传统的 RSA 更短更安全性能也更好。执行后会询问保存路径和 passphrase直接回车使用默认路径~/.ssh/id_ed25519即可。passphrase 可以设置也可以不设置如果设置了每次使用密钥时都要输入该短语可以用 ssh-agent 来缓存避免频繁输入。生成完成后把公钥部署到远程服务器ssh-copy-id -i ~/.ssh/id_ed25519.pub userserver_ipssh-copy-id 会自动把公钥追加到服务器上对应用户的~/.ssh/authorized_keys文件里。如果服务器上还没有这个文件它会自动创建同时设置好权限。这里有一个关键点authorized_keys文件的权限必须是 600.ssh目录权限必须是 700否则 sshd 会拒绝使用该公钥认证。如果不小心用chmod改错了权限会出现“明明公钥已经部署但登录时还是要求密码”的情况。3.3 Remote-SSH 连接配置详解打开 VS Code点击左侧远程资源管理器图标选择“SSH Targets”然后点击齿轮图标编辑 SSH 配置文件。这个文件通常在~/.ssh/configWindows 上可能是C:\Users\你的用户名\.ssh\config。一个典型的最小配置如下Host my-ai-server HostName 192.168.1.100 User ubuntu Port 22 IdentityFile ~/.ssh/id_ed25519这里解释一下几个字段的作用。Host 是你给这台服务器起的别名之后在 VS Code 里连接时只需要选这个别名不用记 IP。HostName 是真实 IP 或域名。User 是登录用户名一定要和服务器上实际存在的用户一致。IdentityFile 指定使用的私钥路径。如果服务器 SSH 端口不是默认的 22在 Port 字段修改即可。配置保存后在远程资源管理器中点击目标服务器旁边的“Connect to Host”按钮VS Code 会在新窗口中尝试连接。第一次连接时VS Code 会自动在远程服务器上下载并安装 VS Code Server 组件这个过程需要一点时间取决于服务器和本地之间的网络状况。连接成功后窗口左下角会显示“SSH: my-ai-server”之类的标识说明你已经进入远程开发模式。3.4 连接之后的体验调优刚连上远程服务器时VS Code 是一个相对干净的界面扩展也需要区分本地和远程。你可以把常用扩展安装在远程端比如 Python、ESLint、Prettier 等。安装方法是在扩展面板中查找所需插件然后选择“Install in SSH: my-ai-server”这样插件就会部署到远程服务器上只在你连接这台远程主机时生效。终端面板是 Remote-SSH 体验的核心。按 Ctrl 打开终端此时终端默认就是 SSH 到服务器的 shell直接输入claude 就能进入 Claude Code 交互界面。如果你在本地终端和远程终端之间切换容易混可以给终端窗口改名或者在 VS Code 的终端下拉菜单里看到每个终端对应的主机标识一目了然。另一个值得调的细节是 VS Code 的remote.SSH.showLoginTerminal设置如果 SS 登录过程中遇到问题打开这个选项可以在终端中看到完整的 SSH 登录日志对排查非常有用。4. Claude Code 核心用法在远程环境里把它用出效率4.1 会话启动与工作目录选择进入远程终端后首先 cd 到你的项目目录然后再执行claude。这一点非常重要因为 Claude Code 的工作范围默认就是当前目录它会读取该目录下的文件结构、git 状态、语言配置以此为依据回答问题和修改代码。如果你在 home 目录下启动它扫描的范围很大不仅响应慢还可能产生不必要的误修改。实际工作中我通常会在项目根目录启动cd ~/projects/my-app claude启动后你会看到 Claude Code 的交互提示符直接输入自然语言指令即可。比如“帮我看一下这个项目的依赖有没有冲突”它会自己读 package.json、锁文件然后给出分析。4.2 高频命令与快捷操作速查Claude Code 的交互界面支持一些斜杠命令这些命令是高频使用的我列一个我自己常用的速查表命令作用/help显示所有可用命令和帮助/status查看当前对话的上下文、token 消耗等情况/compact压缩当前对话历史降低上下文占用/clear清空当前会话重新开始/permissions查看和修改命令执行权限/review让 Claude Code 审查最近改动或指定文件/add-dir将指定目录加入上下文范围/memory管理长期记忆配置跨会话的偏好这些命令可以在交互状态下直接输入也可以在命令行中带参数运行。除了斜杠命令每次对话中 Claude Code 有时会征求你的确认例如“是否运行 npm test”这类问题直接输入 y 或 n 即可响应。4.3 让 Claude Code 更“懂”你的项目Claude Code 的上下文理解能力很强但它默认只能看到启动时扫描到的东西。如果项目里有一些核心约定、架构设计文档建议显式告诉它。比如在项目根目录建一个 CLAUDE.md 文件里面用自然语言描述项目的目录结构、编码规范、常用命令、注意事项等Claude Code 会自动读取这个文件并作为行为参考。我的 CLAUDE.md 通常长这样# 项目说明 这是一个基于 React TypeScript 的前端项目使用 pnpm 作为包管理器。 # 编码规范 - 组件文件使用 PascalCase 命名 - 样式使用 CSS Modules - 禁止直接修改 lock 文件 # 常用命令 - 启动开发服务器pnpm dev - 运行测试pnpm test - 构建pnpm build实际体验下来加了这份文件之后Claude Code 给出的代码风格和命令建议明显更贴合项目习惯很少再出现“用 npm 而不是 pnpm”这类低级偏差。4.4 与 VS Code 文件编辑联动的技巧你可能已经发现VS Code 远程终端里跑着 Claude Code而 VS Code 的编辑器又能直接打开远程文件。这意味着 Claude Code 修改文件之后你在编辑器里可以立刻看到变化。这里有个非常实用的组合操作让 Claude Code 修改代码后自己打开对应的文件用编辑器的 diff 功能查看改动。具体做法是在 Claude Code 输出修改结果后它会报告“Modified src/utils.ts”之类的信息你在 VS Code 的文件树中找到这个文件点击打开。VS Code 底部会显示文件的 git 变更状态用 CtrlShiftG 打开源代码管理面板就能看到每个文件的 diff高亮显示改动行配合 Claude Code 的修改说明你可以在几秒钟内完成人工 review。另外Claude Code 运行时间较长时建议在 VS Code 里开启终端多会话。比如在一个终端里跑claude做代码生成在另一个终端里跑测试命令验证结果互不阻塞。VS Code 终端面板右上角的加号可以新建终端或者用 CtrlShift 直接开新终端。5. 常见问题与排查实录5.1 SSH 连接失败从日志到解决方案SSH 远程连接是整套方案里最可能出问题的环节而且问题现象往往千奇百怪。我把最常见的几类整理成一张排查表现象可能原因解决方案Connection refused服务器 SSH 服务未启动或端口不对检查 sshd 状态sudo systemctl status sshd确认端口ss -tlnpPermission denied (publickey)公钥未正确部署或权限不对重新执行 ssh-copy-id检查服务器上 ~/.ssh 权限为 700authorized_keys 为 600Host key verification failed服务器系统重装或 IP 被复用本地执行ssh-keygen -R 服务器IP清除旧指纹后重连Bad owner or permissions on .ssh/configWindows 上 SSH 配置文件权限过宽右键配置文件设置权限仅限当前用户或使用 icacls 调整Connection timed out网络不通或防火墙拦截本地执行telnet 服务器IP 22验证端口检查云安全组入站规则这里要特别说一个容易被忽略的问题云服务器的安全组。很多云厂商默认只放行 22 端口但如果你改了 SSH 端口或者服务器所在网络有额外的防火墙策略就需要同步放行。排查时优先用telnet验证 TCP 层是否通再用 SSH 的-v参数看详细认证过程这样能快速定位问题层面。5.2 VS Code Server 下载失败第一次远程连接时VS Code 会在服务器上安装一个名为 vscode-server 的组件正常情况会自动完成但网络不佳或服务器处于受限网络环境时会出现“Failed to download VS Code Server”或“Failed to fetch”的报错。这个问题的根因是 VS Code Server 的下载源在远程无法访问或访问缓慢。解决思路有这么几条按推荐顺序尝试。第一检查服务器能否访问 VS Code 的下载域名如果只是偶发超时多试几次或者换一个网络时段。第二手动在服务器上下载对应版本的 VS Code Server 压缩包解压到指定目录。具体版本号可以从本地 VS Code 的Help - About里看到“Commit”字段然后在服务器上拼出下载链接。第三如果服务器是被代理控制的网络可以检查本地与远程的网络链路是否正常或者临时改用其他网络环境下载。手动安装的步骤大致是mkdir -p ~/.vscode-server/bin/commit-id cd ~/.vscode-server/bin/commit-id # 下载对应版本的 server 压缩包并解压 tar -xzf vscode-server-linux-x64.tar.gz --strip-components1解压完成后重新在本地连接VS Code 会检测到已存在的 server 组件并跳过下载。这个方法稍微繁琐但对于网络受限的服务器环境来说是可靠的兜底方案。5.3 Claude Code 启动失败或命令找不到claude命令找不到的问题在第二节已经讲过核心是 PATH 没配好。另外还有一类常见报错是启动时提示 Node.js 版本过低这类问题只需要把 Node.js 升级到 20 LTS 以上即可。如果服务器上同时存在多个 Node.js 版本比如用 nvm 装的还要确认当前 shell 默认指向的是哪个版本。启动过程中如果提示需要登录或 API 密钥无效先检查环境变量是否生效echo $ANTHROPIC_API_KEY如果输出为空说明环境变量没有在当前 shell 中加载检查~/.bashrc里是否写入了 export 语句以及是否执行过source ~/.bashrc。另外某些 Linux 发行版的默认 shell 可能是 zsh 或其他环境变量要写入对应的 rc 文件。5.4 权限问题汇总一次理清权限问题在 Linux 上几乎无处不在我把 Claude Code SSH 场景下最常遇到的权限相关坑整理出来Claude Code 无法写文件检查项目目录归属如果目录属于 root当前用户没有写权限。用sudo chown -R 当前用户:当前用户 项目目录修正。SSH 公钥认证失效检查~/.ssh目录和authorized_keys文件权限目录 700、文件 600 是硬性要求。npm 全局安装失败用普通用户安装不要 sudo。如果目录权限有问题用sudo chown -R $(whoami) $(npm prefix -g)修复。VS Code Server 目录权限异常如果曾用 root 连接过 VS Code~/.vscode-server目录可能被 root 占用普通用户无法写入。清理后重新连接即可。权限问题的排查思路其实很简单先看报错信息里涉及的路径再用ls -la确认该路径所有者和权限最后根据实际需求用 chown/chmod 修正。不要动不动就 chmod 777那样虽然能解决问题但会留下安全隐患。6. 安全加固与长期使用体验6.1 不要用 root 直接跑 Claude Code我在实际使用中最大的教训就是不要用 root 用户来跑 Claude Code。原因有三层第一Claude Code 会执行你给的指令如果指令中有创建文件、修改配置甚至安装软件的操作root 权限下这些操作不受限制一旦 AI 判断失误后果比普通用户严重得多。第二root 用户的配置和普通用户隔离如果误在 root 下初始化了 Claude Code 的认证后续切回普通用户又要重新配置。第三VS Code Remote-SSH 如果用 root 登录vscode-server 也会装在 root 的 home 目录下后续换用户连接就要重新下载安装浪费时间。正确的做法是在服务器上创建一个专门用于开发的用户sudo useradd -m -s /bin/bash devuser sudo passwd devuser sudo usermod -aG sudo devuser然后把这个用户的公钥加到它的~/.ssh/authorized_keys中后续所有操作都用这个用户完成。6.2 密钥与敏感信息管理API 密钥是 Claude Code 运行的核心凭证一定要妥善保管。不要把它提交到 git 仓库不要写在项目目录下的普通文本文件里。推荐的做法是写在~/.bashrc或~/.profile中并确保文件权限只有自己可读。如果你使用 systemd 服务或环境变量文件来管理密钥也要把对应文件的权限设为 600。SSH 私钥同样重要。本地机器的~/.ssh/id_ed25519文件建议设置权限为 600不要随意分享给他人。如果怀疑私钥泄露立即在服务器上从authorized_keys中移除对应公钥并重新生成一对新密钥。6.3 让远程开发保持流畅的小习惯用这套方案久了我总结出几个让体验更流畅的习惯。第一每次连接后先打开终端跑一下df -h检查服务器磁盘空间因为 VS Code Server 和 Claude Code 的缓存都可能占用磁盘满了之后各种奇怪问题就来了。第二Claude Code 对话历史较长时及时用 /compact 压缩上下文避免 token 消耗过快。第三大项目建议在 CLAUDE.md 里明确指定哪些目录不需要 Claude Code 扫描可以通过 .claudeignore 或类似机制排除 node_modules、dist 等目录加快启动速度并减少误操作。还有一个小技巧在本地 VS Code 里给远程终端配置多个预设配置比如一个默认的 bash 终端一个专门跑 Claude Code 的终端。这样每次打开远程窗口直接点对应配置就能进入工作状态省去重复输入的麻烦。7. 写在最后我踩过坑之后的几点体会整套方案从最初在纯终端里勉强使用 Claude Code到现在本地 VS Code 一键连接远程服务器流畅开发中间经历了不少折腾。最值得强调的一点是先把 SSH 链路打通再谈 Claude Code 的使用这个顺序不能反。SSH 连接是地基地基不稳后面所有的优化都白搭。另一个体会是Claude Code 的能力上限很大程度上取决于你给它多少上下文。通过 CLAUDE.md 把项目的约定、目录结构、常用命令写清楚它给出的结果质量会有质的提升。这个文件不需要写得多华丽把关键信息说清楚就行你会发现 AI 编程助手的表现直接上了一个台阶。最后如果你在实操中遇到文章里没覆盖到的问题不妨先从日志入手。无论是 SSH 的-v参数还是 Claude Code 的/status输出日志里通常都藏着真正的线索。远程开发这条路本质上就是不断和环境、权限、网络斗争的过程但只要把基础打牢后续的开发效率提升是实打实的。