最近帮团队从零搭了一套 Claude Code 开发辅助环境Windows 笔记本上一装就撞出红字报错claudes workspace requires the virtual machine platform on windows. enable。这台机器配置不低可 Claude 就是起不来。折腾了一下午之后我索性把服务端全量部署到 Red Hat Enterprise Linux 8 上回头再处理 Windows 客户端的虚拟化开关最后整理成了一套跨平台方案项目代号就叫 Claude-Red。这篇文章不聊高大上的架构只讲我在这个过程中踩过的坑、排查的链路以及最终能稳定复现的部署步骤。刚接触 Claude Code、准备在公司里推广 AI 辅助开发的团队可以照着这份笔记走一遍。1. 为什么叫“Claude-Red”项目背景与整体选型思路1.1 团队为什么从一票 AI 编程助手里选中了 Claude Code选型这件事最初其实是在对比 GitHub Copilot、Cursor 和 Claude Code 三兄弟。Copilot 强在 IDE 内补全Cursor 强在编辑器交互但 Claude Code 最不一样的地方在于它不是网页聊天框也不是纯粹的编辑器插件而是一个跑在终端里的 agent。它可以直接读项目文件、执行命令、调用编译器、批量修改代码。这意味着同样一个“给这段逻辑写单测”的请求Claude Code 可以在无人盯着的情况下自己完成“读源码 → 生成测试 → 跑测试 → 修复失败”一整条链路。团队里我最看重的是它可以被脚本化调用。Claude Code 支持非交互式参数运行这意味着它不仅能给单个开发者在终端里用还能挂在 cron、systemd timer 甚至 CI 流水线上每天定时跑代码审查、批量重构巡检、自动整理 CHANGELOG。这种“把 AI 变成可编排的自动化流程”的能力才是它区别于其他交互式助手的核心价值。另外它的权限模型比较清晰可以定义哪些命令允许执行、哪些目录允许读取适合多人共用一套部署环境。基于这些理由我们把它定为团队 AI 辅助开发的统一底座。1.2 Windows 开发机 RHEL 服务端的分工逻辑整个方案的架构其实很简单开发人员日常在 Windows 上用 VSCode 写代码通过 Remote-SSH 连到 RHEL 8 服务器上的 Claude Code 环境做代码解释、单测生成、提交信息生成等交互式操作同时 RHEL 8 上挂着 systemd timer每天凌晨定时跑一次仓库巡检自动审查当天的提交并输出报告到固定目录。为什么要把日常编码环境和服务端任务分开三个原因。第一Windows 桌面端交互体验好但无人值守的长期稳定性一般一个自动更新或驱动问题就可能中断整晚的定时任务而 RHEL 8 设计上就是干这个的生命周期长安全补丁和运维工具链都成熟。第二Claude Code 在 Windows 上走的是虚拟化沙箱配置门槛高换成 Linux 之后很多发行版开箱即用省掉整条虚拟化链路。第三服务端部署在 Linux 上之后团队成员只要 SSH 连上来就是同一个环境、同一套配置不再出现“我本机跑得好好的怎么到你机器就报错”的扯皮。这个项目名就叫 Claude-Red。Red 有两层意思一是 Red Hat 的 Red因为服务端最终落在 RHEL 8 上二是初期那排红色报错的 Red提醒我们这个坑是怎么踩出来的。等整套流程跑通之后我顺手把部署步骤沉淀成了团队笔记也就是下面这份。2. Windows 侧卡点Workspace 与虚拟机平台报错的根因定位2.1 报错里的“workspace”和“virtual machine platform”到底指什么先别急着看命令把原理搞明白后面排查才有方向。Claude Code 在 Windows 上需要创建一个隔离的 workspace 沙箱用来执行命令、读写临时文件、跑测试和编译。这个沙箱不是随便开个文件夹而是基于 Windows 的虚拟化层构建的受控环境目的是防止 agent 误操作整个操作系统。这个虚拟化底座在微软的体系里叫“虚拟机平台”Virtual Machine Platform它是 WSL2、Windows Sandbox、Hyper-V 这些功能共同的底层依赖。所以那句报错claudes workspace requires the virtual machine platform on windows. enable翻译成人话就是你的 Windows 缺一块虚拟化底座Claude 的沙箱起不来于是整个应用拒绝启动。很多人的第一反应是重装 Node.js、重复装 Claude Code甚至换 Python 环境但这些操作全部无效因为问题发生在系统功能层面还没到应用层你重装一百遍 Claude 也不可能自己把系统功能打开。2.2 我按顺序执行的完整排查链路这里给出我踩完坑后沉淀的标准排查顺序按步骤走不要跳。一次只改一个变量不然出了问题很难回头定位。第一步用 PowerShell 确认系统虚拟化状态打开管理员 PowerShell执行systeminfo拉到输出最下面的“Hyper-V 要求”部分。如果显示“检测到虚拟机监控程序。将不显示 Hyper-V 所需的功能。”说明虚拟化已经启用问题不大。如果显示“以下项目 4 项中只有 0 项符合要求”类似字样那就要继续往下看缺少的是哪几项最常见的缺项就是“已在固件中启用虚拟化”和“虚拟机监控程序平台”。第二步启用 Windows 可选功能控制面板 → 程序和功能 → 启用或关闭 Windows 功能在弹出的窗口里勾选这几项虚拟机平台、Windows 虚拟机监控程序平台、适用于 Linux 的 Windows 子系统、Hyper-V如果系统版本支持。如果你更习惯命令行也可以管理员身份跑Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform, Microsoft-Windows-Subsystem-Linux, HypervisorPlatform -All -NoRestart然后重启系统。这一步做完80% 的“workspace 起不来”问题就已经解决了。第三步确认 WSL 版本并更新内核重启后打开 PowerShell执行wsl --status如果默认版本显示 1.x需要切到 2wsl --set-default-version 2 wsl --updateClaude Code 的 workspace 在 Windows 上要跑得顺底层 WSL2 内核不能太老。wsl --update这个命令很多人会漏掉导致后续启动依旧失败。第四步检查 BIOS 虚拟化开关打开任务管理器切到“性能”选项卡看 CPU 那一栏右下角“虚拟化”是否显示“已启用”。如果显示“已禁用”需要重启进 BIOS把 Intel VT-x笔记本上一般叫 Intel Virtualization Technology或 AMD SVM 打开。这一步在品牌机和公司统一采购的机器上特别容易踩因为很多 OEM 出厂默认关闭虚拟化。第五步强制 Hypervisor 随系统启动如果以上全部完成Claude 还是报同样的错最后一步是用管理员 PowerShell 执行bcdedit /set hypervisorlaunchtype auto这个命令的作用是把 Hyper-V 的 Hypervisor 设置为随系统自动启动。Claude Code 的 workspace 沙箱依赖这一层虚拟机监控程序有时候功能面板里都勾选了但 Hypervisor 本身没有处于运行状态手动设置一下就能解决。第六步再次启动验证重新打开终端运行claude如果能看到 workspace 初始化成功的输出并且进入正常交互提示符说明 Windows 侧已经通了。如果还是失败直接看下面一节对照典型场景。2.3 功能开完还是失败几种典型场景对照我整理了实际遇到过的几类情况以及对应的处理方式。现象根因处理方式启用 WSL2 时提示无法安装Windows 10 版本过旧升级到 21H2 以上或直接换 Windows 11安装 WSL 报 0x80370102BIOS 虚拟化没开重启进 BIOS 开启 VT-x 或 AMD SVM与 VMware Workstation 冲突第三方虚拟化占用关闭 Hyper-V或在 VMware 中启用嵌套虚拟化Docker Desktop 提示 WSL 内核过期内核版本没更新执行wsl --update后重启功能全部开启但启动依旧失败Hypervisor 未随系统启动执行bcdedit /set hypervisorlaunchtype auto还有一个容易被忽略的点Windows 家庭版默认没有 Hyper-V 组件虽然虚拟机平台和 WSL2 可以用但有些依赖 Hyper-V 管理功能的报错会比较诡异。如果公司给的标准镜像里包含这类限制建议优先升级到专业版或企业版或者直接走后面章节的 RHEL 方案不要让 Windows 这一层成为团队的公共瓶颈。3. 服务端落点在 Red Hat Enterprise Linux 8 上部署 Claude Code3.1 装 RHEL 8 时的三个先决判断Windows 侧只是解决“能用”的问题真正让 Claude Code 发挥自动化威力的地方是 RHEL 8 服务端。装系统这一步看起来基础但后面踩的坑往往都是安装阶段埋下的。第一个判断是订阅和软件源。RHEL 8 安装完第一件事是用订阅账号注册注册后才能拿到 BaseOS 和 AppStream 的软件源。等你dnf install的时候如果提示找不到包先回来检查这一步。没有订阅的情况下你也可以配置一个本地镜像源选一个能满足团队内网要求的就好。第二个判断是安装场景。我强烈建议做最小化安装不需要图形界面。Claude Code 跑在终端里图形界面除了占用内存没有任何用处。安装过程中勾选“开发工具”组Development Tools后面编译一些原生依赖时不需要再手动补 gcc、make。第三个判断是分区。不要把所有空间都压给根分区单独分一个/srv/claude-workspace目录挂载点。这个目录用于存放临时生成的文件、测试产物和 Claude 创建的沙箱工作区。独立分区的好处是后续清理容易就算 Claude 生成了一堆垃圾文件也不会把根分区塞满影响系统稳定性。我给这个目录分配了至少 50GB跑大型仓库的代码审查完全够用。3.2 Node.js 版本坑与 Claude Code 安装命令RHEL 8 自带软件源里的 Node.js 模块流版本比较老直接用dnf install nodejs装出来的版本大概率满足不了 Claude Code 的运行时要求我当时就栽在这里。装完之后npm install -g各种报语法错误查下来发现是 Node.js 版本太旧ESM 模块解析方式已经变了。我的处理方式是先用 nvm 装一个 Node.js 20 LTScurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm alias default 20 node -v这里补充一句如果公司内网访问不到 GitHub 的原始安装脚本你可以换成手动下载 nvm 的 release 包或者直接使用内部 Node.js 版本管理工具。关键是最终node -v输出的版本要在 18 以上最好 20 LTSClaude Code 才能稳定跑。Node.js 就绪后全局安装 Claude Codenpm install -g anthropic-ai/claude-code claude --version如果npm install阶段网络拉包慢可以给 npm 配置镜像源这个根据团队网络情况来不做强制要求。安装完成能正常输出版本号说明服务端的基础环境已经通了。3.3 API 鉴权与配置文件权限Claude Code 首次启动需要认证。交互式场景直接执行claude login它会生成一个授权链接在浏览器里完成授权。这种方式适合开发人员个人使用。但服务端跑定时任务不能依赖人工登录我建议直接用 API Key 做非交互式认证。把 Key 写入环境变量export ANTHROPIC_API_KEY你的key为了让这个 Key 能随 Claude Code 每次启动自动生效我把它放进了~/.claude/settings.json的env字段{ permissions: { allow: [ Bash(git status:*), Bash(git diff:*), Read(~/.claude/*) ], deny: [ Bash(rm -rf /), Bash(shutdown:*) ] }, env: { EDITOR: vim } }注意这个文件里如果写入了 Key权限必须收紧chmod 600 ~/.claude/settings.json否则同机器上的其他用户能直接读到你的 Key。这一点在多人共用的开发机上尤其重要我在生产环境里就见过因为配置文件是 644 权限导致 Key 泄露的前车之鉴。3.4 把 Claude Code 变成无人值守服务systemd 定时任务实测服务端部署的最后一环是把 Claude Code 变成可以无人值守调度的服务。我用的工具是 systemd timer比 cron 更可控日志可以交给 journald 统一管理。先建一个专门运行 Claude 任务的用户避免拿 root 身份直接跑sudo useradd -r -m -s /bin/bash claudebot然后在/etc/systemd/system/claude-review.service写服务单元[Unit] DescriptionClaude Code Daily Review Afternetwork-online.target [Service] Userclaudebot WorkingDirectory/srv/git/myproject EnvironmentANTHROPIC_API_KEY你的key ExecStart/usr/bin/env claude -p 检查最近的提交输出 review 报告并保存到 docs/review-$(date %F).md --output-format text再建一个 timer 文件/etc/systemd/system/claude-review.timer[Unit] DescriptionRun Claude Review Daily at 02:00 [Timer] OnCalendar*-*-* 02:00:00 Persistenttrue [Install] WantedBytimers.target启动并验证sudo systemctl daemon-reload sudo systemctl enable --now claude-review.timer sudo systemctl list-timers | grep claude这里有几条经验值得重点讲。第一用专门的系统用户跑即使 Claude 生成的命令有误操作影响范围也限定在这个用户权限内不会把整个服务器干掉。第二WorkingDirectory必须指向 Git 仓库根目录Claude 才能正确识别项目上下文和版本历史。第三非交互模式下一定要加-p参数否则它会在那里等一个永远不会来的交互输入定时任务直接卡死。4. 日常开发接入VSCode 远程连接 RHEL 配置 Claude Code 的实践4.1 为什么最终推荐 Remote-SSH 方案Windows 侧的虚拟化问题解决之后Claude Code 确实能本地跑了但实际使用了一段时间体验上还是很别扭。最主要的问题是文件系统割裂代码库在 Linux 服务器上本地 Windows 访问要走网络映射或 SMBClaude 读写文件时频繁受到路径和权限差异的干扰。另外一个问题是环境不一致有人在 Windows 上用有人在 Mac 上用还有人在 Linux 上用每个人都需要单独配置一遍维护成本很高。所以我把日常开发工作流改成了Windows 本地 VSCode 通过 Remote-SSH 扩展连接到 RHELClaude Code 直接跑在服务器上。这样本地只是薄薄一层图形界面实际计算、文件读写、git 操作全部发生在服务器上团队每个成员看到的是完全相同的环境。4.2 Remote-SSH 的配置步骤与常见失败点先在 Windows 的 VSCode 里安装扩展搜索 “Remote - SSH” 安装。然后在用户主目录下的.ssh/config里添加主机配置Host claude-rhel8 HostName 192.168.1.20 User claudebot IdentityFile ~/.ssh/claude_rhel8 ServerAliveInterval 30生成密钥并拷贝公钥到服务器ssh-keygen -t ed25519 -f ~/.ssh/claude_rhel8 -N ssh-copy-id -i ~/.ssh/claude_rhel8.pub claudebot192.168.1.20VSCode 里按 F1执行 “Remote-SSH: Connect to Host”选择claude-rhel8即可连接。这里有两个常见的失败点。第一个是首次连接时 VSCode 需要往服务器下载并安装远程服务端如果服务器防火墙没放行 22 端口或者 DNS 解析有问题会一直卡在 “Setting up SSH Host” 阶段。第二个是.ssh/config文件的权限不能太宽松Windows 上 OpenSSH 会拒绝加载权限过大的配置文件客户端会莫名其妙提示 “Bad owner or permissions”。我当时因为在迁移过程中复制了 NTFS 的访问控制列表排查了快一个小时才发现是权限问题。4.3 在 VSCode 集成终端里跑 Claude Code 的典型工作流连接上服务器后在 VSCode 的集成终端里进入项目目录直接运行claude进入交互模式后我最常做的是三类操作。第一类是解释代码选中一段晦涩的业务逻辑让 Claude 结合上下文分析它到底在干什么。第二类是生成单测输入“给 src/utils.ts 写一组单元测试”它会在仓库里自动找依赖、生成测试文件、跑测试并修复报错。第三类是提交辅助输入“看一下当前变更帮我写一个规范的 commit message”它会自动执行git diff并输出摘要。如果觉得每次都打同样的 prompt 很啰嗦可以把常用指令做成 slash command 存进.claude/commands/目录。比如创建.claude/commands/review.md请审查当前分支相对 main 的全部变更关注 1. 潜在的空指针和边界条件 2. 错误处理是否完整 3. 是否有明显性能问题 输出一份简洁的 review 要点之后在 claude 交互窗口里输入/review就能直接调用效果稳定很多。4.4 配置文件入库与密钥隔离多人协作最重要的一条规则~/.claude/里的用户级配置不能入库项目仓库里的.claude/目录要入库。前者包含本机专属的 Key、代理设置和个人偏好后者承载的是团队共享的权限策略、自定义 slash command 和项目上下文说明。我在团队仓库里维护的.claude/结构大概长这样.claude/ ├── settings.json ├── commands/ │ ├── review.md │ └── commit.md └── CLAUDE.mdCLAUDE.md是给 Claude Code 看的项目说明写清楚项目的技术栈、构建命令、测试命令和目录结构约定。Claude Code 在启动时会自动读取这个文件作为项目上下文相当于给 agent 一份团队知识手册。权限策略里要特别注意不要把Bash(*)这类通配符全部放行根据日常使用情况逐条允许。我把git、npm test、deno test这类常规命令放进 allow 列表把危险操作或者需要人工确认的操作放进 deny 列表让异常行为在发生前就被拦住。5. 跨平台部署最容易踩的坑与最终验证清单5.1 换行符、路径分隔符与 Git 配置差异跨平台方案里最隐蔽的坑不是 Claude Code 本身的安装而是代码仓库在不同操作系统间流转时产生的换行符问题。Windows 下git checkout默认会把文件转成 CRLF 结尾linux 下默认保留 LF。当 Claude 生成一个 shell 脚本后直接尝试执行很可能因为行尾多了个\r报出 “command not found” 或 “syntax error near unexpected token”排查起来非常费劲。我的建议是在仓库根目录放一个.gitattributes文件* textauto eollf *.sh text eollf *.bat text eolcrlf把 shell 脚本强制成 LFWindows 批处理保持 CRLF其他文本文件统一 LF。这样不管开发者在什么平台上提交最终进入 Linux 服务器工作区的文件都是 LFClaude 生成的脚本和服务端的定时任务都能顺利执行。路径问题同理给 Claude 的 prompt 里不要出现 Windows 盘符路径C:\Users\...在 RHEL 上统一使用 Linux 路径。如果确实要访问 Windows 上的某个文件通过挂载或同步的方式拉到服务器目录里再让 Claude 操作。5.2 SELinux 和 firewalld 拦路的判断与放行RHEL 8 默认启用 SELinux 和 firewalld这两道关卡在安全上是好事但对 Claude Code 这类需要频繁读写文件、执行命令的 agent 来说也是报错重灾区。一个典型现象是SSH 能正常连接仓库目录也能ls但 Claude Code 启动后读取项目时报 Permission denied。这种时候不要急着setenforce 0先查 SELinux 审计日志sudo ausearch -m avc -ts recent如果日志里出现node_t或某个目录上下文相关的 AVC 拒绝记录说明确实是 SELinux 拦截。此时有两种优雅的处理方式一是调整目标目录的文件上下文让 Claude 的运行用户能读取二是如果 Claude 需要访问网络接口用布尔值放行而不关闭整体强制模式sudo setsebool -P httpd_can_network_connect 1防火墙层面如果只需要 SSH 远程连接放行服务即可sudo firewall-cmd --permanent --add-servicessh sudo firewall-cmd --reload如果后续打算让 Claude 通过 HTTP 回调推送通知再按需放行对应端口。千万别图省事把整个防火墙关掉我见过不少团队在生产服务器上把 firewalld stop 了结果系统下线排查安全隐患时才发现问题这种教训不值得重复。5.3 最终验收清单以下是我在 Claude-Red 整套环境跑通之后整理的验收清单每一条都是实际验证过的通过标准。检查项操作/命令预期结果Windows 本地启动终端运行claude不再报 workspace 错误进入交互界面RHEL 服务端版本claude --version正常输出版本号无依赖报错API 鉴权claude -p 返回ok非交互模式能拿到响应VSCode 远端连接Remote-SSH 连接claude-rhel8集成终端内可运行 claude 并访问项目定时任务可用sudo systemctl start claude-review.service服务正常退出日志无 AVC 拒绝配置文件权限stat -c %a ~/.claude/settings.json输出 600 或更严格换行符统一file scripts/*.sh显示 ASCII text 而不是 CRLF这套清单也推荐你每次升级 Claude Code 或迁移服务器后跑一遍五分钟就能排查掉 90% 的环境问题。最后再分享一点我的个人体会。这套东西跑了两周之后我回头看那个折磨了我一下午的 Windows 虚拟化报错反而觉得它帮了团队一个忙它逼着我们把自动化任务从“开发者各自的笔记本”挪到了“真正该跑的地方”——服务器。现在 Claude-Red 这个名字里的 Red我更多是理解成红帽子的红而不是红灯的红。如果你也在琢磨怎么在团队里推广 AI 辅助开发建议先用一台 Linux 机器把 Claude Code 服务端跑通再回头处理 Windows 客户端的虚拟化开关这个顺序能省掉一连串无效操作。
