从Windows 10连接远程Linux安装Claude Code完整教程

最近帮朋友把一台远程 Linux 服务器上的 Claude Code 环境完整搭起来了，我这边的工作机是 Windows 10。这类需求现在越来越多：代码和构建产物在远程 Linux 上，本地 Windows 10 只当一个操作终端，然后通过 Claude Code 这个终端里的 AI 编程助手，直接在远程环境里读代码、跑命令、写改动。整个流程说难不难，但牵扯到 SSH 连接、Node.js 运行时、npm 全局安装、登录认证、VS Code 联动好几层，单看任何一篇教程都不够完整，实际动手处处是坑。这篇文章就把我从 Windows 10 入手、往远程 Linux 装 Claude Code 的完整过程写清楚，每步为什么这么做、遇到问题怎么排查，给同样需要跨平台搭建环境的开发者一个能直接照着做的版本。

1. 整体思路与准备工作：远程环境怎么选、先确认什么

1.1 为什么要装在远程 Linux 上，而不是 Windows 本机

Claude Code 本质上是一个用 Node.js 写的命令行工具，通过 CLI 的方式在终端里和 AI 对话，AI 能读取当前项目文件、执行 shell 命令、帮用户改代码。它官方主推的运行环境是 macOS 和 Linux，Windows 上要么走 WSL，要么用实验性的原生支持。如果你手里已经有一台远程 Linux 服务器，把 Claude Code 装在那边是更可靠的选择，理由有三点。

第一，环境一致性。你开发的项目就在远程服务器上，Claude Code 装在同环境里，它读文件、跑测试、执行 git 操作时面对的就是真实运行环境，不会出现"本地能跑、远程跑不了"的割裂。第二，随时在线。远程服务器 7×24 小时开着，你在 Windows 10 上断网、关机、换电脑都不影响对端环境，重新连上 SSH 就能接着干。第三，权限和工具链完整。Linux 下的 bash、grep、systemctl、docker 这些命令在 Claude Code 的自动执行场景里都是常用工具，比在 Windows 的 PowerShell 里硬跑顺畅得多。

我也见过有人在本机 WSL 里装 Claude Code，不是不行，但本机资源要一直被占用，而且如果团队协作、多人共用一台开发机，远程 Linux 的天然多用户隔离优势还是很明显。几种方案的取舍可以简单对照一下：

1.2 动手前必须确认的三件事

我在这上面栽过跟头，所以强烈建议任何人在安装之前，先花五分钟确认下面几件事，别上来就一股脑装。

第一，SSH 能不能通。你需要知道服务器 IP、SSH 端口（默认是 22）、用户名，以及密码或者密钥。在 Windows 10 的 PowerShell 里先测一下端口：Test-NetConnection -ComputerName 192.168.1.100 -Port 22。如果 TcpTestSucceeded 显示 True 再继续，否则先排查网络和防火墙，别等装到一半才发现连不上。

第二，Node.js 版本。Claude Code 要求 Node.js 18 及以上，推荐 20 LTS。登录远程服务器后先执行node -v，如果没输出或者版本太低，先按后面第三章的方法把 Node 环境搞定再说。

第三，权限和空间。确认当前用户有 sudo 权限，用df -h看一眼根分区有没有足够空间。npm 全局安装本身占不了太多，但 Claude Code 运行时拉依赖、缓存都吃一点磁盘，所以还是那句老话：磁盘几百 MB 剩余是底线。这三件事都确认了，整个安装过程基本就是一路绿灯。

2. 从 Windows 10 接入远程 Linux：三种连接方式

2.1 最基础的方案：Windows Terminal 加自带 OpenSSH

Windows 10 系统自带 OpenSSH 客户端，不需要装任何额外软件。打开 PowerShell 或者 Windows Terminal，先确认 ssh 可用：ssh -V。

接着直接连接：ssh 用户名@服务器地址。第一次连接会提示确认主机指纹，输入 yes，然后输入密码就进去了。如果服务器只允许密钥登录，或者你想省去每次输密码的麻烦，就在 Windows 10 上生成密钥对：ssh-keygen -t ed25519，一路回车默认生成到C:\Users\你的用户名\.ssh\下。然后把公钥放到服务器上。Linux 上常见的 ssh-copy-id 在 Windows 上不一定有，我常用的写法是这样：

type $env:USERPROFILE\.ssh\id_ed25519.pub | ssh 用户名@服务器地址 "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 700 ~/.ssh && chmod 600 ~/.ssh/authorized_keys"

原理很简单，就是把本地的公钥内容通过管道送过去，追加到远程服务器的 authorized_keys 文件里，同时收紧权限。做完这步，再 ssh 登录就不用输密码了。

长期用的话，我建议在C:\Users\你的用户名\.ssh\config里配置一个主机别名：

Host mylinux HostName 192.168.1.100 User root IdentityFile ~/.ssh/id_ed25519 ServerAliveInterval 60 ServerAliveCountMax 3

其中 ServerAliveInterval 60 的意思是每 60 秒发一次心跳包，能有效避免长时间没操作被服务端断开。配好之后，一条ssh mylinux就能连上，比每次敲全地址舒服太多。

2.2 首选方案：VS Code Remote-SSH，边看代码边敲命令

如果你要操作的是真实项目，强烈建议用 VS Code 的 Remote-SSH 扩展。装好扩展后，按 Ctrl+Shift+P 输入Remote-SSH: Connect to Host，选刚才配置的 mylinux，VS Code 会自动打开一个连接窗口，左下角会显示远程主机名。

这个方案带来的体验差距是巨大的。远程服务器的文件树直接出现在 VS Code 左侧，你可以正常浏览、编辑、搜索所有文件，集成终端（Ctrl+`）打开的就是远程 Linux 的 bash，而不是本地 PowerShell。更关键的是，后面要把 Claude Code 接到 VS Code 里，这个连接方式本身就是基础。

这个方案有一个容易踩的坑：Windows 10 自带的 OpenSSH 客户端版本不能太老。如果 Remote-SSH 一直卡在 "Resolved SSH remote host" 或者提示找不到 ssh，去"设置 → 应用 → 可选功能"里把 OpenSSH 客户端更新到最新版，或者直接重装一次。

2.3 备用方案：PuTTY 和 MobaXterm 适合什么场景

如果你的 Windows 10 比较老，或者你习惯了图形化的会话管理，PuTTY 也能用。需要提醒的是，PuTTY 不识别 OpenSSH 的密钥格式，要把 .ppk 格式的密钥通过 PuTTYgen 转换，Session 里保存主机地址、端口，还要在 Connection → SSH → Auth 里指定密钥路径。

MobaXterm 就更省心了，左边是会话列表，右边是终端，自带 SFTP 面板，拖文件上传下载都很方便，对新手友好很多。我的建议是：SSH 直连适合临时登录，VS Code Remote-SSH 适合正经干开发活，PuTTY 和 MobaXterm 属于传统备选。三选一即可，长期开发别绕开 VS Code 那条路。

3. Claude Code 在远程 Linux 上的安装与配置

3.1 先把 Node.js 运行时装明白

Claude Code 官方要求 Node.js 18 以上。很多 Linux 发行版默认不带 node，或者通过 apt 装的版本很旧。我不推荐直接apt install nodejs，因为你永远不知道装出来的版本是几，而且系统包管理带的 Node 经常比官方节奏慢一大截。更可靠的做法是用 nvm 安装。

在远程服务器上执行：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

装完 nvm 后，重新登录或者source ~/.bashrc让配置生效，然后执行：

nvm install 20 nvm alias default 20 node -v npm -v

nvm 的好处是它把 Node 装在你自己的用户目录下（~/.nvm），不需要 sudo，也不会污染系统目录。打个比方，nvm 相当于在你自己家里给 Node 安排了一个独立房间，系统包管理则是让 Node 住进集体宿舍，以后你想换版本、挪位置都麻烦。这一步直接决定了后面全局安装 Claude Code 时会不会遇到 EACCES 权限报错，可以说省掉一大半麻烦。

如果服务器上已经有 Node 了，先确认node -v输出的版本号不低于 18。低于 18 的，一定要升级，不然 Claude Code 装完运行时行为会很诡异，甚至直接报错。

3.2 全局安装 Claude Code 并正确升级

Node 环境就绪后，安装其实就是一条命令的事：

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

这里要强调一下，因为有 nvm 在，全局安装会落到~/.nvm/versions/node/目录下，不需要 sudo。但如果你用的是系统级 Node，npm 全局安装时很可能会报 EACCES，这时千万别图省事直接sudo npm install -g，这样会把权限问题埋得更深，claude 命令可能被装到 root 的目录里，你当前用户根本调不起来。处理权限问题的正确姿势是退回去用 nvm。

安装完成后验证一下：

claude --version

看到版本号就说明安装本身成功了。之后升级也很简单：

npm update -g @anthropic-ai/claude-code

如果网络拉取 npm 官方源比较慢，可以临时指定镜像源，只对这一次生效：

npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

装完之后记得把 registry 切回默认，免得以后装别的包都被镜像源设置的地址影响。npm config set registry https://registry.npmjs.org是切回官方源的方法。

3.3 登录认证：浏览器 OAuth 和 API Key 两种方式

安装完成后，直接在终端输入claude启动。第一次启动会进入登录流程：选择用 Claude 订阅账号登录，或者输入 API Key。

用订阅账号登录时，终端会打印一个授权链接，你在任意一台电脑的浏览器（包括你本地 Windows 10 的浏览器）打开链接，完成账号登录后，把浏览器里显示的授权码填回终端即可。这个流程走的是 OAuth，授权码是一次性的，不需要在服务器上装浏览器，本质上也不存在"服务器没有图形界面就登不了"的问题。

如果用 API Key，方式更直接：

export ANTHROPIC_API_KEY=你的key claude

启动后输入/status可以查看当前登录账号和计费模式，确认登录成功再继续。我建议把 API Key 写进~/.bashrc或者一个单独的环境变量文件里，注意别写进项目仓库，也别复制到聊天工具里，这东西泄露了等于别人能拿你的额度跑任务。

这里补一句：如果你在公司账号下使用，终端提示类似 your organization has disabled claude subscription access 的信息，说明当前订阅在组织策略层面不允许使用 Claude Code。这种情况一般两个处理方向：一是用自己的个人订阅或 API Key 计费来跑，二是找管理员确认订阅权限。这是账号层面的配置问题，跟环境安装无关，不用反复重装排查。

3.4 启动后先做一轮冒烟测试

环境装完不要急着干大活，先用简单任务验证整条链路。比如让 Claude Code 列出当前目录下的文件：claude 启动后，输入"看下当前目录有什么文件"。正常情况下它会调用 ls 或者 bash 工具，然后给出文件列表和简短说明。

如果这一步没问题，说明从 Windows 10 到远程 Linux 的网络链路、Node 环境、Claude Code 认证全部打通了。冒烟测试阶段我建议只做只读操作，不要让它改动文件，先把交互节奏适应了再放开手脚。另外，/help可以查到所有斜杠命令，/clear可以清空当前对话上下文，这两个命令在高频场景里几乎每天都要用到。

4. 高频扩展场景：VS Code 联动、本地模型和第三方 API 接入

4.1 在 VS Code 里用 Claude Code：终端和扩展面板两条路

装完 Claude Code 后，你有两种方式在 VS Code 里用它。

方式一是最推荐的：保持 Remote-SSH 连接状态，在 VS Code 的集成终端里直接输入claude。因为集成终端就是远程 Linux 的 bash，Claude Code 的自动命令执行、文件读取、git 操作都发生在远程真实项目里，本地 VS Code 只负责显示，体验上和直接在服务器上操作完全一致。

方式二是安装 Claude Code 的 VS Code 扩展，通过图形化面板和 Claude Code 对话。扩展的底层还是需要远程主机上有 CLI，它的价值在于把对话和代码编辑区域分屏展示，看变更 diff 更直观。我个人用下来的感受是：日常写代码、跑任务我用集成终端，需要大范围代码审查和修改时用扩展面板，两个入口互补，按自己的习惯选就好。

4.2 把请求指向本地模型或第三方 API 的原理与配置

Claude Code 默认把请求发到 Anthropic 官方的 API 服务，但它本身是支持自定义端点的。原理很简单：客户端启动时会读取ANTHROPIC_BASE_URL环境变量，把这个地址作为请求的根地址，发往兼容的/v1/messages这类接口。所以只要你有一个兼容口，Claude Code 就能把请求发过去。

先讲本地模型场景。如果你在远程 Linux 上用 LM Studio 这类工具跑本地模型，启动本地推理服务后，假设服务监听127.0.0.1:1234，那么配置就是：

export ANTHROPIC_BASE_URL=http://127.0.0.1:1234 export ANTHROPIC_API_KEY=lm-studio

这里的 key 可以随便填，本地服务一般不做鉴权，但格式必须满足客户端要求。有一个很容易忽略的点：如果模型跑在你的 Windows 10 本机上，而 Claude Code 跑在远程 Linux 上，那就不能写 127.0.0.1，要改成 Windows 10 在局域网里的 IP，比如http://192.168.1.50:1234，同时确认本机防火墙放行了对应端口。我因为这个 IP 写错排查了快半小时，先说清楚，免得大家踩同样的坑。

第三方模型场景更常见。像 DeepSeek、Qwen、GLM 这些模型服务，不少已经提供了 Anthropic 兼容的接入端点，或者可以通过网关做协议转换。接入方法本质一样：把ANTHROPIC_BASE_URL指向对应服务的兼容地址，再把ANTHROPIC_AUTH_TOKEN或ANTHROPIC_API_KEY设置为服务方给的鉴权信息。需要注意，不同模型方要求的模型名称字段不同，可能要配合ANTHROPIC_MODEL环境变量做映射，具体值以服务方接入文档为准。

如果你想在多个服务之间来回切换，cc switch 这类配置切换工具的思路就很有参考价值：它本质上是管理多组环境变量配置，快速切换 BASE_URL、Key、模型名，避免你每次手动改 export。我建议所有接第三方端的同学都把配置做成长效环境变量文件，一份一份保存好，切换时 source 对应文件即可，别在终端里手敲，容易漏。

4.3 Claude Code 直接执行终端命令的权限机制

很多人第一次用 Claude Code 会被吓一跳：它不只是给你代码，而是真的会在终端里执行命令。背后是 Bash 工具和文件编辑工具，AI 在对话中会提议运行某条命令，等用户授权后再执行。

它的交互逻辑大概是这样：AI 给出建议的命令和说明，用户按 Enter 允许一次，或者按 Esc 拒绝，也可以设置成自动允许某些安全命令。我实际用的技巧是，在/config的权限设置里把 ls、pwd、git status、cat 这类只读命令加进白名单，写入类命令保留每次确认，这样既能少弹确认框，又不会让 AI 乱改文件。

至于完全不确认的模式，命令行参数里有对应的跳过权限选项，但我强烈不建议在真实服务器上这么干。我自己的原则是：跳过权限模式只在一次性容器或者临时环境里用，在放着代码和数据的服务器上，永远保留确认环节。这跟车技再好也要系安全带是一个道理，你永远不知道 AI 哪一步会出现误判。

5. 踩坑实录：安装和使用中的常见问题排查

5.1 SSH 连接层的问题

最常见的现象是连接超时。先别急着怀疑 SSH 配置，用 Test-NetConnection 确认端口通不通。如果端口不通，去服务器上看防火墙：ufw status看有没有放行 22 端口，systemctl status sshd看 SSH 服务是不是活着。很多时候是服务器重启后 sshd 没起来，或者是云平台安全组没放行，跟客户端一点关系都没有。

第二个高频问题是主机指纹变更导致连不上。服务器重装系统或换了 IP 后，Windows 会提示 Host key verification failed，因为本地记录的主机指纹对不上。解决办法是在 Windows 10 上执行ssh-keygen -R 服务器地址，把旧指纹删掉，重新连接时再确认一次新指纹就行。

第三个是连接频繁断开。这个我在配置 SSH config 时已经提过，加ServerAliveInterval 60和ServerAliveCountMax 3能解决大部分"放着不动就被踢"的情况。如果是网络本身质量较差，那属于网络层面的问题，不在 SSH 软件能解决的范围内。

5.2 Node 与安装层的问题

如果安装完 claude 后提示 command not found，多半是 nvm 的路径没有进 PATH。检查方式：echo $PATH，看看有没有~/.nvm/versions/node/v20.x.x/bin这个路径，没有就重新source ~/.bashrc，或者彻底退出当前会话重新登录。

npm install -g报 EACCES 权限错误，几乎都是因为没用 nvm 而用了系统 Node。不要sudo npm install -g，正确做法是切到 nvm 管理的 Node 下再装。如果已经装坏了，找到 claude 命令被装到的目录删掉，重装。

还有一个容易被忽略的点：npm 安装卡住不动。多半是网络问题，网络较慢时会一直卡在 fetch 阶段。可以用--registry参数指到镜像源装一次，装完再切回官方源，前面在 3.2 已经给过命令了。

5.3 认证与运行层的问题

浏览器授权流程打不开链接是新手常见困惑。其实授权链接在任意一台电脑的浏览器里都能打开，你用本地 Windows 10 的浏览器完全没问题。把整个链接复制过来打开即可，不需要服务器上有图形界面。

如果启动后提示订阅相关限制，前面提过这是账号或组织策略问题，换成个人订阅或者 API Key 计费。这里有个常见误区：很多人以为是环境变量没配好，反复重装，其实跟环境一点关系没有，先把账号权限和计费方式确认了。

终端里中文乱码的话，Windows Terminal 一般默认 UTF-8 没有这个问题，如果是老版 cmd，执行chcp 65001切换编码。远程 Linux 侧也要确认LANG环境变量设置正确，不然中文文件名会显示异常。这个跟 Claude Code 本身无关，但很影响使用心情。

5.4 常见问题速查表

这趟从 Windows 10 到远程 Linux 装 Claude Code 走下来，我个人最大的体会是：步骤本身不值钱，值钱的是顺序和耐心。先把 SSH 连通性验证了，再装 Node，再装 Claude Code，最后才考虑 VS Code 和模型接入，一层一层往上叠，每层验证通过再进下一步，基本不会翻车。还有一个我后来才养成的习惯：在远程服务器上用 tmux 建一个常驻会话，把 Claude Code 跑在里面，这样即使本地 SSH 断开，远程的对话和任务也不会中断，重新连上后 tmux attach 就能回到原现场。最后多说一句，Claude Code 在远程 Linux 上的可用性比 Windows 本机好不少，既然你已经决定用它，就别在环境上省功夫，一次性把 Node、认证、权限、模型接入都理顺，后面每天用起来会非常顺手。