这段时间我一直在折腾一件事让 Claude Code 不要只窝在主控机里而是能通过 SSH 被远程调度跑在同一套网络下的 Linux、Windows、NAS 上。起因很简单项目要同时验证三套平台的兼容性手动开三个终端逐个 SSH 过去敲 claude 命令密钥过期、权限不对、输出乱码来回折腾了一个多小时才跑通一遍。后来我把 Hermes Agent 接进来用它做多机编排把这些机器统一收编成一个节点组再以任务的方式批量下发指令才算是真正解放了双手。这篇文章就记录一下整个落地过程包括 Hermes Agent 的安装、SSH 免密配置、任务编排写法以及远程调度 Claude Code 时容易踩的各种坑。1. 为什么我必须把 Claude Code 拆到多台机器上跑1.1 单机方案的天花板在哪里我们先说清楚问题。Claude Code 本身是一个跑在终端里的 AI 编程助手它最大的优势是能直接读写当前机器上的文件、执行命令、运行测试。但这恰恰也是单机方案最尴尬的地方Claude Code 只能操作它所在的这台机器的环境。我手上的项目包含一个后端服务、一个 Windows 客户端和一个需要在 Linux 服务器上跑测试的模块。如果我只在 Windows 主控机上装 Claude Code它确实能帮我写后端代码但它没法真正在 Linux 上执行 pytest也没法验证 Windows 客户端的编译依赖是否完整。就算我远程把代码同步过去每次还是要手动 SSH 到目标机器上再拉起一个 Claude Code 会话才能让 AI 在正确的环境里干活。单机方案的另一个瓶颈是并行。一个任务跑完才出结果另一个任务排队等三台机器本来可以同时开工硬生生被我玩成了串行。对于个人开发者来说这可能只是多等几分钟的事但当你需要同时验证多平台兼容性、跑多组回归测试的时候这等待就很痛了。1.2 引入 Hermes Agent 后整个开发链路变成了什么样子Hermes Agent 在我的理解里更像是一个“遥控器 接线板”的组合。它本身不替代 Claude Code也不替代 SSH而是把原本需要你手动去每台机器上执行命令的过程抽象成一次可以批量分发、统一回收结果的任务调度。我在配置里定义了一个节点组Hermes Agent 内部叫它pantheon万神殿意思是一个受控的机器集合。每个节点有名字、IP、SSH 用户名、端口。主控机只要针对这个节点组发起一条hermes run命令它就会自动连到组内所有机器上把我要执行的 Claude Code 指令送过去然后把每一台机器返回的 stdout、stderr、退出码统一收集回来。这样整个链路就变成了主控机 - Hermes Agent - SSH 通道 - 各节点 - 各节点上的 Claude Code - 执行结果原路返回。我只需要关心两个核心问题节点怎么连进组任务怎么定义。至于 Claude Code 在远端是不是处于非交互模式、Shell 环境变量对不对、输出格式怎么解析这是后话我会在第 4 章和第 6 章详细展开。2. 环境准备主控机、工作节点和软件清单2.1 主控机与节点的系统选型我主控机用的是 Windows 11另外加入了三个节点一台 Ubuntu 22.04 用于跑后端测试一台 Windows 10 用于验证客户端构建一台群晖 NAS 用于产物归档。为什么选这三个角色因为每台机器都代表一种典型的跨平台环境而且它们的 SSH 服务形态差异很大正好可以把常见问题都覆盖到。主控机上需要准备的软件不多一个现代终端我用的 Windows Terminal PowerShell)、Git、Node.js 18 及以上版本以及后面要装的 Hermes Agent。Claude Code 依赖 Node.jsHermes Agent 在 Windows 下可以直接用便携版解压后加入 PATH 就能用不需要额外编译。各节点的软件准备要分平台处理。Linux 和 Windows 节点都需要安装 Node.js 和 Claude CodeNAS 节点比较特殊往往没有 Node.js 环境所以我通常只让它承担文件归档这类轻量任务不强行在上面跑 Claude Code。这是我的一个建议不要把所有机器都塞进编排脚本先想清楚每台机器适合做什么。2.2 Claude Code 的安装与跨平台差异Claude Code 的安装本身不复杂在 Linux 和 macOS 上一条 npm 命令搞定npm install -g anthropic-ai/claude-code claude --versionWindows 上建议用 PowerShell 执行同样的 npm 安装命令安装完以后如果claude命令无法直接识别最常见的原因是 npm 全局目录没有加入 PATH检查一下npm config get prefix指向的路径把对应的 bin 目录加进去就行。注意一点Claude Code 在全新环境下第一次启动时会进入交互式引导要求你登录或设置 API Key。在远程非交互式场景下这个引导是跑不起来的。所以我在正式接入 Hermes Agent 之前会先在每台机器上手动执行一次claude完成登录和默认配置确认可以正常对话后再让它参与编排。另外Claude Code 有桌面版但我们在多机编排场景里用的是命令行模式桌面版反而帮不上忙。自动化调度要求的是稳定的 CLI 接口和可解析的输出格式这一点 CLI 比桌面版靠谱得多。2.3 Hermes Agent 安装Windows 便携版与 Linux 本地部署Hermes Agent 的安装方式在不同平台上有差别。我在 Windows 主控机上用的是便携版下载对应压缩包后解压到一个目录里比如D:\tools\hermes-agent然后把目录加入系统 PATH。验证方式hermes --versionLinux 节点上我采用的是本地部署方式把二进制或脚本放到/opt/hermes-agent然后注册一个 systemd 服务确保机器重启后代理也能自动起来。这样做的原因是 Linux 节点更多是作为被调度端存在有一个稳定的常驻进程后续做日志采集和定时任务都会方便很多。这里有个很容易踩的坑便携版解压后如果当前终端还是旧 PATH需要新开一个终端窗口才能识别hermes命令。另外Hermes Agent 的配置目录默认放在用户目录下的.hermes文件夹如果你的主控机用户名包含中文或空格个别版本的路径处理会有兼容性问题。我当时把配置目录显式指向了英文路径比如D:\hermes-conf问题就消失了。3. SSH 免密登录是这套系统的地基3.1 密钥生成与分发别再用密码硬刚Hermes Agent 要跨节点执行任务第一个前提就是主控机能免密登录所有节点。每次都用密码不仅慢而且自动化场景下密码会暴露在脚本和日志里非常不安全。我统一采用 ed25519 密钥来做认证。在主控机上生成密钥ssh-keygen -t ed25519 -C hermesmain -f ~/.ssh/id_ed25519 -N -N 表示空口令这样 Hermes Agent 在执行 SSH 连接时不需要交互输入。如果你对安全要求更高也可以给私钥设置口令然后用 ssh-agent 托管但考虑到编排任务可能分布在多个会话里我建议自动化专用密钥不设口令权限控制靠文件系统和节点上的用户权限来保证。公钥分发这一步Linux 节点可以直接用ssh-copy-idssh-copy-id -i ~/.ssh/id_ed25519.pub ubuntu192.168.1.10如果你的主控机是 WindowsPowerShell 里没有ssh-copy-id可以手动把公钥追加到目标机器的~/.ssh/authorized_keys。这和配置 GitLab SSH 密钥的思路完全一样公钥给服务端私钥留在本地服务端校验通过后免密登录。3.2 Windows 节点用 Bitvise 还是 OpenSSHWindows 节点的 SSH 服务有两种常见选择系统自带的 OpenSSH Server 和第三方工具 Bitvise SSH Server。如果你只需要基础的命令执行和文件传输Windows 自带的 OpenSSH Server 就够用。在“设置 - 可选功能”里添加 OpenSSH 服务器然后启动服务Start-Service sshd Set-Service -Name sshd -StartupType AutomaticBitvise SSH Server 的优势在于图形化管理界面可以更细粒度地控制账户权限、密钥和虚拟目录映射适合需要精细权限隔离的场景。但它默认的默认 Shell 设置和 OpenSSH 不太一样有时候从远端执行命令会出现 PATH 不一致的问题。我当时为了省事直接在 Windows 节点上装了 Bitvise结果一条claude --version在远程执行时报“命令找不到”排查了半天才发现是 Bitvise 默认 Shell 用的是受限环境后来在 Bitvise 设置里把登录 Shell 改成系统默认的 PowerShell 并勾选了继承环境变量才恢复正常。所以我的建议是如果你对 Windows SSH 服务不太熟悉优先用系统自带的 OpenSSH踩坑成本更低。Bitvise 更适合以后需要管理大量 Windows 节点再做统一控制时引入。3.3 那些导致连不上的细节权限、防火墙、shellSSH 免密配置看似简单真正出问题的地方往往很琐碎。我遇到过几次典型的“ubuntu ssh 无法连接”和“ssh服务器拒绝了密码”根因各不相同。第一个是权限。Linux 节点上~/.ssh目录权限必须是 700~/.ssh/authorized_keys文件权限必须是 600。如果权限过于宽松sshd 出于安全策略会直接忽略这个公钥文件表现就是你密码输对了也连不上公钥也认证失败。修正命令chmod 700 ~/.ssh chmod 600 ~/.ssh/authorized_keys第二个是 sshd 配置。如果你希望只允许特定用户组登录可以在/etc/ssh/sshd_config里加AllowGroups wheel这样只有 wheel 组的用户才能 SSH 登录。反过来如果之前为了调试开了 root 登录我建议关掉。用普通用户登录需要提权时再通过 sudo 切换比直接暴露 root 安全得多。出于同样考虑我会在 sshd_config 里设置PasswordAuthentication no只保留公钥认证。这一步做完之后那些“网络攻击 SSH 大量连接”的告警会明显减少因为暴力破解的前提是密码认证密码认证关了攻击面就小了很多。第三个是 Windows Defender 防火墙。Windows 节点上即使 OpenSSH 服务已经启动防火墙没有放行 22 端口从外部连进来一样会超时。在管理员 PowerShell 里执行New-NetFirewallRule -Name OpenSSH-Server -DisplayName OpenSSH Server -Enabled True -Direction Inbound -Protocol TCP -Action Allow -LocalPort 22不要嫌这些步骤基础它们就是整个多机编排系统的地基。地基本来就应该是枯燥且重复的。4. 用 Hermes Agent 定义多机编排任务4.1 节点配置文件怎么组织Hermes Agent 的节点配置我放在~/.hermes/nodes.yaml。它做的事情很简单给每一台要调度的机器定义一个符号名然后记录 SSH 连接参数。以我的环境为例pantheon: dev-cluster nodes: - name: linux-build host: 192.168.1.10 user: ubuntu port: 22 - name: win-verify host: 192.168.1.20 user: admin port: 22 - name: nas-archive host: 192.168.1.30 user: nasuser port: 22配置里值得注意的一个字段是pantheon这是我的节点组名称。你可以把它理解成一个命名的机器池以后发起任务时可以指定只发给某一个节点也可以指定发给整个组。这和给服务器打标签的思路很像方便在任务定义里做分组调度。有了这个文件我可以先跑一条基础的连通性检查hermes ping --pantheon dev-cluster这条命令会逐个 SSH 连上去执行一个简单的 echo然后返回每个节点的时延和状态。这一步能快速确认前面的免密配置有没有问题。SSH 通不过的节点不要硬塞进编排池否则后面跑任务时会拖慢整个批次而且日志会很难看。4.2 任务调度的两种姿势命令直通与脚本分发Hermes Agent 支持两种任务下发方式。第一种是命令直通适合执行短命令比如我想在 linux-build 节点上看一下磁盘占用hermes exec --node linux-build -- df -h第二种是脚本分发适合执行多步骤任务。先把本地写好的脚本推送到目标节点再在远端执行。Hermes Agent 内部封装了类似 scp 的文件推送能力你只需要在任务配置里声明script和remote_pathhermes run --node linux-build --script ./scripts/run_tests.sh --remote-path /tmp/run_tests.sh脚本分发的好处是逻辑可以集中在主控机维护不用在每台机器上都保存一份。而且脚本本身可以写成跨平台的运行时通过判断操作系统执行不同命令。我的习惯是把复杂的编排逻辑写成脚本简单的探测命令直接用命令直通。4.3 远程调度 Claude Code 时的参数设计现在到了关键环节让 Hermes Agent 在远程节点上运行 Claude Code。先看一个实际例子hermes run --node linux-build -- \ claude -p 检查当前仓库的测试覆盖率定位失败的用例并给出修复建议 \ --allowedTools Bash,Read,Write \ --output-format json这里的claude -p是 Claude Code 的非交互打印模式适合在脚本和 CI 里调用。--allowedTools限制 AI 可以使用的工具范围避免它在远程机器上乱执行命令。--output-format json让输出变成结构化 JSONHermes Agent 收集结果以后我可以用 jq 直接提取关键字段。这里有一个非常重要的前置条件在每台节点上Claude Code 必须先完成登录。因为 SSH 远程执行时没有交互式终端如果第一次运行claude -p时它弹出一个登录引导整个命令就会被挂起Hermes Agent 等不到结果只能超时。解决办法是在节点本地上提前手动执行一次claude让它在用户目录下生成好凭据配置文件或者显式设置环境变量ANTHROPIC_API_KEY但不要把真实密钥写在命令里而是配置在节点的用户环境变量里。另外Claude Code 默认会读取当前工作目录下的项目文件所以远程调度时最好先cd到正确的目录。我用的是hermes exec --node linux-build -- \ cd /workspace/myapp claude -p ...Hermes 的exec会保留引号内的整体命令这样 cd 和 claude 实际是在同一个 Shell 会话里执行的。如果你把 cd 和 claude 拆成两个独立任务Claude Code 启动时可能还在用户主目录根本看不到项目文件。5. 一次真实的跨平台开发调度5.1 场景设定一个需要三端联调的小项目为了让整个方案更落地我拿一个实际项目来说。项目是一个命令行工具要求同时在 Linux 和 Windows 上运行编译结果还需要归档到 NAS。这个项目平时我是在 Windows 主控机上开发的代码放在同一个仓库里。需求拆解下来有三件事在 Ubuntu 节点上运行完整的测试套件定位环境相关的失败用例在 Windows 节点上检查项目能否通过交叉编译并运行一次打包命令把两个节点生成的测试报告和构建产物同步到 NAS。在没有 Hermes Agent 之前我必须开三个 SSH 窗口切换目录输入不同命令再手动收集输出。现在我用一个编排配置文件把三个阶段串起来一次性跑完。5.2 三台机器各自承担什么、怎么跑我在主控机上写了三个任务分别对应一个节点。先看第一个任务的命令hermes run --node linux-build -- \ cd /workspace/cli-tool claude -p \运行 pytest 并输出失败用例摘要给出修复建议\ --output-format json /tmp/linux-test.json这里我把claude的输出重定向到了节点本地的 JSON 文件。为什么不用 Hermes 直接收集因为测试报告可能很长直接往主控机回传会撑爆命令行。更好的做法是让结果先落在节点本地再由 Hermes 通过后续的文件拉取任务把关键产物拿回来。第二个任务在 Windows 节点上hermes run --node win-verify -- \ cd C:\\workspace\\cli-tool claude -p \检查项目在 Windows 环境下的编译依赖然后执行打包命令\ --allowedTools \Bash,Read,Write,Edit\ --output-format json D:\\logs\\win-build.jsonWindows 节点命令里的反斜杠和引号转义要比 Linux 节点更小心。我的经验是遇到过于复杂的命令直接写成一个 PowerShell 脚本然后通过--script分发比在命令行里硬拼转义要省心得多。第三个任务负责把前两个节点生成的报告和产物拉回主控机再推送到 NAShermes exec --node nasal-archive -- \ mkdir -p /volume1/build-archive/$(date %Y%m%d) hermes pull --node linux-build --remote /tmp/linux-test.json --local ./reports/ hermes push --node nas-archive --local ./reports/ --remote /volume1/build-archive/5.3 结果回收与日志核对任务跑完后Hermes Agent 会在主控机上打印一个汇总表包含每个节点的状态、命令耗时和退出码。我习惯把汇总输出存成文件然后用 jq 提取关键字段hermes run --pantheon dev-cluster --batch tasks.json --save-report report.json cat report.json | jq .tasks[] | {node: .node, status: .status, exit_code: .exit_code}这一步的价值在于三台机器并行工作中间没有任何一个人手动介入。Claude Code 在 Linux 上分析测试用例在 Windows 上分析编译依赖NAS 乖乖收文件整个过程是自动化的。而且因为每一条指令都有明确的退出码我可以写一个简单的检查规则任何一台机器返回非零退出码就立刻在终端标红提醒。后续我把这个流程挂到了 cron 上每天凌晨自动跑一次第二天早上打开报告就知道三端的状态。跨平台开发从“手动三窗口”变成了“定时任务 报告查看”效率提升非常明显。6. 跨平台排障与性能调整6.1 SSH 批量连接被重置怎么办多机编排跑起来以后第一个遇到的高频问题是 SSH 连接被重置。表现为某个节点任务执行到一半报Connection reset by peer其他节点正常。这种情况往往不是因为密钥配置错而是因为短时间内建立了大量 SSH 连接触发了服务端的连接频率限制或者网络中间设备掐断了长连接。我的处理方案是启用 SSH 连接复用。在主控机的~/.ssh/config里配置Host 192.168.1.* ControlMaster auto ControlPath ~/.ssh/cm-%r%h:%p ControlPersist 600这样同一时间段内多个任务如果连的是同一个节点会复用同一条 SSH 连接而不是每次都重新握手。实际测试下来批量任务的总耗时能缩短至少三分之一连接被重置的次数也少了很多。如果网络环境比较复杂还可以在节点侧检查journalctl -u ssh或者 Windows 事件查看器里的 OpenSSH 日志确认是不是有人在扫描端口。我的建议是尽快关掉密码认证只留公钥认证从源头减少攻击流量。6.2 Claude Code 会话状态在远程机上怎么保持Claude Code 在远程非交互模式下每次claude -p都是一个独立的新会话。它不会保留上一次对话的上下文也不会自动记住你在某个目录下的偏好设置。这意味着你在编排任务时每一次都要把上下文描述得足够完整。另一个容易忽视的问题是 API Key 和配置。我在把一台新机器接入编排池时会在节点本地上先手动运行一次 Claude Code确认它能正常对话然后检查一下~/.claude/settings.json是否存在。遇到过一次your limits are temporarily boosted. your weekly claude code limit is 50%这样的限流提示不是在本次输错了什么而是因为并发任务太多把同一个账号的额度瞬间打满了。解决并发限流有三种路径一是降低同一时刻下发到节点的任务数Hermes 的--parallel参数可以限制并发量二是把几个用时较长的任务错峰执行三是切换到本地模型或第三方兼容接口这个我放在下一节说。6.3 本地模型接管Claude Code cc-switch Ollama如果你不想被云端 API 限流卡脖子一个很实用的补充方案是用 cc-switch 配合 Ollama让 Claude Code 切换到本地模型后端。cc-switch 是一个 Claude Code 配置切换工具可以快速切换不同的 API 供应商Ollama 则负责跑本地模型比如 Qwen 或 DeepSeek 系列。整个过程并不复杂。先在节点上安装 Ollama并拉取一个支持工具调用的模型ollama pull qwen2.5-coder:7b然后用 cc-switch 添加一个本地供应商配置把 API 地址指向 Ollama 的兼容端点再切换到该配置。之后在这个节点上执行claude -p实际打交道的模型就变成了本地 Ollama 而不是云端 API。这样做的好处是断网也能跑适合做批量代码检查和格式修正也没有额度焦虑。代价是本地模型的能力上限摆在那里复杂的架构设计、深度的代码推理还是要切回云端模型。我的用法是日常的代码审查、注释补全、测试用例生成交给本地模型关键的方案设计和高风险重构交给云端 Claude。两个后端通过 cc-switch 切换互不干扰。7. 一点个人体会折腾完这套多机编排之后我最深的感触是工具链的复杂度是逐渐叠加的每一步都有它存在的理由。SSH 免密配置很枯燥但它决定了后面的自动化能不能真正落地Claude Code 的登录和凭据管理很琐碎但它决定了远程非交互式任务会不会卡死Hermes Agent 的节点分组设计很灵活但它只有在前面这些基础都打牢之后才有意义。我现在养成的习惯是新接入一台机器时先手动检查一遍 SSH 连通性再手动跑一次 Claude Code最后才把它加进节点的云配置。宁可前面多花五分钟验证也不要让一台没准备好的节点拖垮整个任务批次。另外我建议把 Hermes 的配置文件和所有秘密信息放到一个独立目录里管理这个目录不进入任何公开仓库。毕竟编排系统的权限等同于所有节点的管理员权限这个边界一定要守住。如果你也准备在团队里引入类似的多机编排方案可以先从两台机器开始试水主控机加一台 Linux 节点跑通一个最简单的hermes ping和claude -p任务再逐步扩展节点数量和任务复杂度。这条路走通以后你会发现跨平台开发这件事比想象中要顺手得多。 用Hermes Agent实现Claude Code多机远程调度与编排实践
这段时间我一直在折腾一件事让 Claude Code 不要只窝在主控机里而是能通过 SSH 被远程调度跑在同一套网络下的 Linux、Windows、NAS 上。起因很简单项目要同时验证三套平台的兼容性手动开三个终端逐个 SSH 过去敲 claude 命令密钥过期、权限不对、输出乱码来回折腾了一个多小时才跑通一遍。后来我把 Hermes Agent 接进来用它做多机编排把这些机器统一收编成一个节点组再以任务的方式批量下发指令才算是真正解放了双手。这篇文章就记录一下整个落地过程包括 Hermes Agent 的安装、SSH 免密配置、任务编排写法以及远程调度 Claude Code 时容易踩的各种坑。1. 为什么我必须把 Claude Code 拆到多台机器上跑1.1 单机方案的天花板在哪里我们先说清楚问题。Claude Code 本身是一个跑在终端里的 AI 编程助手它最大的优势是能直接读写当前机器上的文件、执行命令、运行测试。但这恰恰也是单机方案最尴尬的地方Claude Code 只能操作它所在的这台机器的环境。我手上的项目包含一个后端服务、一个 Windows 客户端和一个需要在 Linux 服务器上跑测试的模块。如果我只在 Windows 主控机上装 Claude Code它确实能帮我写后端代码但它没法真正在 Linux 上执行 pytest也没法验证 Windows 客户端的编译依赖是否完整。就算我远程把代码同步过去每次还是要手动 SSH 到目标机器上再拉起一个 Claude Code 会话才能让 AI 在正确的环境里干活。单机方案的另一个瓶颈是并行。一个任务跑完才出结果另一个任务排队等三台机器本来可以同时开工硬生生被我玩成了串行。对于个人开发者来说这可能只是多等几分钟的事但当你需要同时验证多平台兼容性、跑多组回归测试的时候这等待就很痛了。1.2 引入 Hermes Agent 后整个开发链路变成了什么样子Hermes Agent 在我的理解里更像是一个“遥控器 接线板”的组合。它本身不替代 Claude Code也不替代 SSH而是把原本需要你手动去每台机器上执行命令的过程抽象成一次可以批量分发、统一回收结果的任务调度。我在配置里定义了一个节点组Hermes Agent 内部叫它pantheon万神殿意思是一个受控的机器集合。每个节点有名字、IP、SSH 用户名、端口。主控机只要针对这个节点组发起一条hermes run命令它就会自动连到组内所有机器上把我要执行的 Claude Code 指令送过去然后把每一台机器返回的 stdout、stderr、退出码统一收集回来。这样整个链路就变成了主控机 - Hermes Agent - SSH 通道 - 各节点 - 各节点上的 Claude Code - 执行结果原路返回。我只需要关心两个核心问题节点怎么连进组任务怎么定义。至于 Claude Code 在远端是不是处于非交互模式、Shell 环境变量对不对、输出格式怎么解析这是后话我会在第 4 章和第 6 章详细展开。2. 环境准备主控机、工作节点和软件清单2.1 主控机与节点的系统选型我主控机用的是 Windows 11另外加入了三个节点一台 Ubuntu 22.04 用于跑后端测试一台 Windows 10 用于验证客户端构建一台群晖 NAS 用于产物归档。为什么选这三个角色因为每台机器都代表一种典型的跨平台环境而且它们的 SSH 服务形态差异很大正好可以把常见问题都覆盖到。主控机上需要准备的软件不多一个现代终端我用的 Windows Terminal PowerShell)、Git、Node.js 18 及以上版本以及后面要装的 Hermes Agent。Claude Code 依赖 Node.jsHermes Agent 在 Windows 下可以直接用便携版解压后加入 PATH 就能用不需要额外编译。各节点的软件准备要分平台处理。Linux 和 Windows 节点都需要安装 Node.js 和 Claude CodeNAS 节点比较特殊往往没有 Node.js 环境所以我通常只让它承担文件归档这类轻量任务不强行在上面跑 Claude Code。这是我的一个建议不要把所有机器都塞进编排脚本先想清楚每台机器适合做什么。2.2 Claude Code 的安装与跨平台差异Claude Code 的安装本身不复杂在 Linux 和 macOS 上一条 npm 命令搞定npm install -g anthropic-ai/claude-code claude --versionWindows 上建议用 PowerShell 执行同样的 npm 安装命令安装完以后如果claude命令无法直接识别最常见的原因是 npm 全局目录没有加入 PATH检查一下npm config get prefix指向的路径把对应的 bin 目录加进去就行。注意一点Claude Code 在全新环境下第一次启动时会进入交互式引导要求你登录或设置 API Key。在远程非交互式场景下这个引导是跑不起来的。所以我在正式接入 Hermes Agent 之前会先在每台机器上手动执行一次claude完成登录和默认配置确认可以正常对话后再让它参与编排。另外Claude Code 有桌面版但我们在多机编排场景里用的是命令行模式桌面版反而帮不上忙。自动化调度要求的是稳定的 CLI 接口和可解析的输出格式这一点 CLI 比桌面版靠谱得多。2.3 Hermes Agent 安装Windows 便携版与 Linux 本地部署Hermes Agent 的安装方式在不同平台上有差别。我在 Windows 主控机上用的是便携版下载对应压缩包后解压到一个目录里比如D:\tools\hermes-agent然后把目录加入系统 PATH。验证方式hermes --versionLinux 节点上我采用的是本地部署方式把二进制或脚本放到/opt/hermes-agent然后注册一个 systemd 服务确保机器重启后代理也能自动起来。这样做的原因是 Linux 节点更多是作为被调度端存在有一个稳定的常驻进程后续做日志采集和定时任务都会方便很多。这里有个很容易踩的坑便携版解压后如果当前终端还是旧 PATH需要新开一个终端窗口才能识别hermes命令。另外Hermes Agent 的配置目录默认放在用户目录下的.hermes文件夹如果你的主控机用户名包含中文或空格个别版本的路径处理会有兼容性问题。我当时把配置目录显式指向了英文路径比如D:\hermes-conf问题就消失了。3. SSH 免密登录是这套系统的地基3.1 密钥生成与分发别再用密码硬刚Hermes Agent 要跨节点执行任务第一个前提就是主控机能免密登录所有节点。每次都用密码不仅慢而且自动化场景下密码会暴露在脚本和日志里非常不安全。我统一采用 ed25519 密钥来做认证。在主控机上生成密钥ssh-keygen -t ed25519 -C hermesmain -f ~/.ssh/id_ed25519 -N -N 表示空口令这样 Hermes Agent 在执行 SSH 连接时不需要交互输入。如果你对安全要求更高也可以给私钥设置口令然后用 ssh-agent 托管但考虑到编排任务可能分布在多个会话里我建议自动化专用密钥不设口令权限控制靠文件系统和节点上的用户权限来保证。公钥分发这一步Linux 节点可以直接用ssh-copy-idssh-copy-id -i ~/.ssh/id_ed25519.pub ubuntu192.168.1.10如果你的主控机是 WindowsPowerShell 里没有ssh-copy-id可以手动把公钥追加到目标机器的~/.ssh/authorized_keys。这和配置 GitLab SSH 密钥的思路完全一样公钥给服务端私钥留在本地服务端校验通过后免密登录。3.2 Windows 节点用 Bitvise 还是 OpenSSHWindows 节点的 SSH 服务有两种常见选择系统自带的 OpenSSH Server 和第三方工具 Bitvise SSH Server。如果你只需要基础的命令执行和文件传输Windows 自带的 OpenSSH Server 就够用。在“设置 - 可选功能”里添加 OpenSSH 服务器然后启动服务Start-Service sshd Set-Service -Name sshd -StartupType AutomaticBitvise SSH Server 的优势在于图形化管理界面可以更细粒度地控制账户权限、密钥和虚拟目录映射适合需要精细权限隔离的场景。但它默认的默认 Shell 设置和 OpenSSH 不太一样有时候从远端执行命令会出现 PATH 不一致的问题。我当时为了省事直接在 Windows 节点上装了 Bitvise结果一条claude --version在远程执行时报“命令找不到”排查了半天才发现是 Bitvise 默认 Shell 用的是受限环境后来在 Bitvise 设置里把登录 Shell 改成系统默认的 PowerShell 并勾选了继承环境变量才恢复正常。所以我的建议是如果你对 Windows SSH 服务不太熟悉优先用系统自带的 OpenSSH踩坑成本更低。Bitvise 更适合以后需要管理大量 Windows 节点再做统一控制时引入。3.3 那些导致连不上的细节权限、防火墙、shellSSH 免密配置看似简单真正出问题的地方往往很琐碎。我遇到过几次典型的“ubuntu ssh 无法连接”和“ssh服务器拒绝了密码”根因各不相同。第一个是权限。Linux 节点上~/.ssh目录权限必须是 700~/.ssh/authorized_keys文件权限必须是 600。如果权限过于宽松sshd 出于安全策略会直接忽略这个公钥文件表现就是你密码输对了也连不上公钥也认证失败。修正命令chmod 700 ~/.ssh chmod 600 ~/.ssh/authorized_keys第二个是 sshd 配置。如果你希望只允许特定用户组登录可以在/etc/ssh/sshd_config里加AllowGroups wheel这样只有 wheel 组的用户才能 SSH 登录。反过来如果之前为了调试开了 root 登录我建议关掉。用普通用户登录需要提权时再通过 sudo 切换比直接暴露 root 安全得多。出于同样考虑我会在 sshd_config 里设置PasswordAuthentication no只保留公钥认证。这一步做完之后那些“网络攻击 SSH 大量连接”的告警会明显减少因为暴力破解的前提是密码认证密码认证关了攻击面就小了很多。第三个是 Windows Defender 防火墙。Windows 节点上即使 OpenSSH 服务已经启动防火墙没有放行 22 端口从外部连进来一样会超时。在管理员 PowerShell 里执行New-NetFirewallRule -Name OpenSSH-Server -DisplayName OpenSSH Server -Enabled True -Direction Inbound -Protocol TCP -Action Allow -LocalPort 22不要嫌这些步骤基础它们就是整个多机编排系统的地基。地基本来就应该是枯燥且重复的。4. 用 Hermes Agent 定义多机编排任务4.1 节点配置文件怎么组织Hermes Agent 的节点配置我放在~/.hermes/nodes.yaml。它做的事情很简单给每一台要调度的机器定义一个符号名然后记录 SSH 连接参数。以我的环境为例pantheon: dev-cluster nodes: - name: linux-build host: 192.168.1.10 user: ubuntu port: 22 - name: win-verify host: 192.168.1.20 user: admin port: 22 - name: nas-archive host: 192.168.1.30 user: nasuser port: 22配置里值得注意的一个字段是pantheon这是我的节点组名称。你可以把它理解成一个命名的机器池以后发起任务时可以指定只发给某一个节点也可以指定发给整个组。这和给服务器打标签的思路很像方便在任务定义里做分组调度。有了这个文件我可以先跑一条基础的连通性检查hermes ping --pantheon dev-cluster这条命令会逐个 SSH 连上去执行一个简单的 echo然后返回每个节点的时延和状态。这一步能快速确认前面的免密配置有没有问题。SSH 通不过的节点不要硬塞进编排池否则后面跑任务时会拖慢整个批次而且日志会很难看。4.2 任务调度的两种姿势命令直通与脚本分发Hermes Agent 支持两种任务下发方式。第一种是命令直通适合执行短命令比如我想在 linux-build 节点上看一下磁盘占用hermes exec --node linux-build -- df -h第二种是脚本分发适合执行多步骤任务。先把本地写好的脚本推送到目标节点再在远端执行。Hermes Agent 内部封装了类似 scp 的文件推送能力你只需要在任务配置里声明script和remote_pathhermes run --node linux-build --script ./scripts/run_tests.sh --remote-path /tmp/run_tests.sh脚本分发的好处是逻辑可以集中在主控机维护不用在每台机器上都保存一份。而且脚本本身可以写成跨平台的运行时通过判断操作系统执行不同命令。我的习惯是把复杂的编排逻辑写成脚本简单的探测命令直接用命令直通。4.3 远程调度 Claude Code 时的参数设计现在到了关键环节让 Hermes Agent 在远程节点上运行 Claude Code。先看一个实际例子hermes run --node linux-build -- \ claude -p 检查当前仓库的测试覆盖率定位失败的用例并给出修复建议 \ --allowedTools Bash,Read,Write \ --output-format json这里的claude -p是 Claude Code 的非交互打印模式适合在脚本和 CI 里调用。--allowedTools限制 AI 可以使用的工具范围避免它在远程机器上乱执行命令。--output-format json让输出变成结构化 JSONHermes Agent 收集结果以后我可以用 jq 直接提取关键字段。这里有一个非常重要的前置条件在每台节点上Claude Code 必须先完成登录。因为 SSH 远程执行时没有交互式终端如果第一次运行claude -p时它弹出一个登录引导整个命令就会被挂起Hermes Agent 等不到结果只能超时。解决办法是在节点本地上提前手动执行一次claude让它在用户目录下生成好凭据配置文件或者显式设置环境变量ANTHROPIC_API_KEY但不要把真实密钥写在命令里而是配置在节点的用户环境变量里。另外Claude Code 默认会读取当前工作目录下的项目文件所以远程调度时最好先cd到正确的目录。我用的是hermes exec --node linux-build -- \ cd /workspace/myapp claude -p ...Hermes 的exec会保留引号内的整体命令这样 cd 和 claude 实际是在同一个 Shell 会话里执行的。如果你把 cd 和 claude 拆成两个独立任务Claude Code 启动时可能还在用户主目录根本看不到项目文件。5. 一次真实的跨平台开发调度5.1 场景设定一个需要三端联调的小项目为了让整个方案更落地我拿一个实际项目来说。项目是一个命令行工具要求同时在 Linux 和 Windows 上运行编译结果还需要归档到 NAS。这个项目平时我是在 Windows 主控机上开发的代码放在同一个仓库里。需求拆解下来有三件事在 Ubuntu 节点上运行完整的测试套件定位环境相关的失败用例在 Windows 节点上检查项目能否通过交叉编译并运行一次打包命令把两个节点生成的测试报告和构建产物同步到 NAS。在没有 Hermes Agent 之前我必须开三个 SSH 窗口切换目录输入不同命令再手动收集输出。现在我用一个编排配置文件把三个阶段串起来一次性跑完。5.2 三台机器各自承担什么、怎么跑我在主控机上写了三个任务分别对应一个节点。先看第一个任务的命令hermes run --node linux-build -- \ cd /workspace/cli-tool claude -p \运行 pytest 并输出失败用例摘要给出修复建议\ --output-format json /tmp/linux-test.json这里我把claude的输出重定向到了节点本地的 JSON 文件。为什么不用 Hermes 直接收集因为测试报告可能很长直接往主控机回传会撑爆命令行。更好的做法是让结果先落在节点本地再由 Hermes 通过后续的文件拉取任务把关键产物拿回来。第二个任务在 Windows 节点上hermes run --node win-verify -- \ cd C:\\workspace\\cli-tool claude -p \检查项目在 Windows 环境下的编译依赖然后执行打包命令\ --allowedTools \Bash,Read,Write,Edit\ --output-format json D:\\logs\\win-build.jsonWindows 节点命令里的反斜杠和引号转义要比 Linux 节点更小心。我的经验是遇到过于复杂的命令直接写成一个 PowerShell 脚本然后通过--script分发比在命令行里硬拼转义要省心得多。第三个任务负责把前两个节点生成的报告和产物拉回主控机再推送到 NAShermes exec --node nasal-archive -- \ mkdir -p /volume1/build-archive/$(date %Y%m%d) hermes pull --node linux-build --remote /tmp/linux-test.json --local ./reports/ hermes push --node nas-archive --local ./reports/ --remote /volume1/build-archive/5.3 结果回收与日志核对任务跑完后Hermes Agent 会在主控机上打印一个汇总表包含每个节点的状态、命令耗时和退出码。我习惯把汇总输出存成文件然后用 jq 提取关键字段hermes run --pantheon dev-cluster --batch tasks.json --save-report report.json cat report.json | jq .tasks[] | {node: .node, status: .status, exit_code: .exit_code}这一步的价值在于三台机器并行工作中间没有任何一个人手动介入。Claude Code 在 Linux 上分析测试用例在 Windows 上分析编译依赖NAS 乖乖收文件整个过程是自动化的。而且因为每一条指令都有明确的退出码我可以写一个简单的检查规则任何一台机器返回非零退出码就立刻在终端标红提醒。后续我把这个流程挂到了 cron 上每天凌晨自动跑一次第二天早上打开报告就知道三端的状态。跨平台开发从“手动三窗口”变成了“定时任务 报告查看”效率提升非常明显。6. 跨平台排障与性能调整6.1 SSH 批量连接被重置怎么办多机编排跑起来以后第一个遇到的高频问题是 SSH 连接被重置。表现为某个节点任务执行到一半报Connection reset by peer其他节点正常。这种情况往往不是因为密钥配置错而是因为短时间内建立了大量 SSH 连接触发了服务端的连接频率限制或者网络中间设备掐断了长连接。我的处理方案是启用 SSH 连接复用。在主控机的~/.ssh/config里配置Host 192.168.1.* ControlMaster auto ControlPath ~/.ssh/cm-%r%h:%p ControlPersist 600这样同一时间段内多个任务如果连的是同一个节点会复用同一条 SSH 连接而不是每次都重新握手。实际测试下来批量任务的总耗时能缩短至少三分之一连接被重置的次数也少了很多。如果网络环境比较复杂还可以在节点侧检查journalctl -u ssh或者 Windows 事件查看器里的 OpenSSH 日志确认是不是有人在扫描端口。我的建议是尽快关掉密码认证只留公钥认证从源头减少攻击流量。6.2 Claude Code 会话状态在远程机上怎么保持Claude Code 在远程非交互模式下每次claude -p都是一个独立的新会话。它不会保留上一次对话的上下文也不会自动记住你在某个目录下的偏好设置。这意味着你在编排任务时每一次都要把上下文描述得足够完整。另一个容易忽视的问题是 API Key 和配置。我在把一台新机器接入编排池时会在节点本地上先手动运行一次 Claude Code确认它能正常对话然后检查一下~/.claude/settings.json是否存在。遇到过一次your limits are temporarily boosted. your weekly claude code limit is 50%这样的限流提示不是在本次输错了什么而是因为并发任务太多把同一个账号的额度瞬间打满了。解决并发限流有三种路径一是降低同一时刻下发到节点的任务数Hermes 的--parallel参数可以限制并发量二是把几个用时较长的任务错峰执行三是切换到本地模型或第三方兼容接口这个我放在下一节说。6.3 本地模型接管Claude Code cc-switch Ollama如果你不想被云端 API 限流卡脖子一个很实用的补充方案是用 cc-switch 配合 Ollama让 Claude Code 切换到本地模型后端。cc-switch 是一个 Claude Code 配置切换工具可以快速切换不同的 API 供应商Ollama 则负责跑本地模型比如 Qwen 或 DeepSeek 系列。整个过程并不复杂。先在节点上安装 Ollama并拉取一个支持工具调用的模型ollama pull qwen2.5-coder:7b然后用 cc-switch 添加一个本地供应商配置把 API 地址指向 Ollama 的兼容端点再切换到该配置。之后在这个节点上执行claude -p实际打交道的模型就变成了本地 Ollama 而不是云端 API。这样做的好处是断网也能跑适合做批量代码检查和格式修正也没有额度焦虑。代价是本地模型的能力上限摆在那里复杂的架构设计、深度的代码推理还是要切回云端模型。我的用法是日常的代码审查、注释补全、测试用例生成交给本地模型关键的方案设计和高风险重构交给云端 Claude。两个后端通过 cc-switch 切换互不干扰。7. 一点个人体会折腾完这套多机编排之后我最深的感触是工具链的复杂度是逐渐叠加的每一步都有它存在的理由。SSH 免密配置很枯燥但它决定了后面的自动化能不能真正落地Claude Code 的登录和凭据管理很琐碎但它决定了远程非交互式任务会不会卡死Hermes Agent 的节点分组设计很灵活但它只有在前面这些基础都打牢之后才有意义。我现在养成的习惯是新接入一台机器时先手动检查一遍 SSH 连通性再手动跑一次 Claude Code最后才把它加进节点的云配置。宁可前面多花五分钟验证也不要让一台没准备好的节点拖垮整个任务批次。另外我建议把 Hermes 的配置文件和所有秘密信息放到一个独立目录里管理这个目录不进入任何公开仓库。毕竟编排系统的权限等同于所有节点的管理员权限这个边界一定要守住。如果你也准备在团队里引入类似的多机编排方案可以先从两台机器开始试水主控机加一台 Linux 节点跑通一个最简单的hermes ping和claude -p任务再逐步扩展节点数量和任务复杂度。这条路走通以后你会发现跨平台开发这件事比想象中要顺手得多。