OpenJarvis 原生 Windows 部署指南无需 WSL2 与 Docker 的 PowerShell 安装与服务化【免费下载链接】OpenJarvisPersonal AI, On Personal Devices项目地址: https://gitcode.com/gh_mirrors/op/OpenJarvisOpenJarvis 是一个Personal AI, On Personal Devices的个人 AI 项目。本文面向 Windows 用户完整讲解如何在原生 Windows 上通过 PowerShell 安装 OpenJarvis、将其注册为开机自启的 Windows 计划任务服务并安全地决定是仅限本机loopback还是暴露到局域网LAN。文章以 deploy/windows/README.md 为主线并结合 deploy/windows/install.ps1、deploy/windows/jarvis-service.ps1 以及系统级服务定义文件给出源码级佐证。读完本文你将掌握一条命令完成安装、计划任务服务的注册/查询/卸载、以及loopback 默认免密钥 / 局域网暴露必须配 API Key的完整安全模型。背景为什么需要原生 Windows 部署OpenJarvis 在 Linux 和 macOS 上分别通过 systemddeploy/systemd/openjarvis.service与 launchddeploy/launchd/com.openjarvis.plist来管理常驻的 API 服务进程。Windows 侧的部署是其原生支持Native-Windows Support RFC的 Phase-1目标是在不依赖 WSL2、不依赖 Docker、不依赖 MSYS2的前提下用 PowerShell 提供与 Linux/macOS 对等的安装 → 服务化 → 自启 → 守护体验。从 deploy/windows/install.ps1 的头部注释可以确认它是 Linux/macOS 安装脚本 scripts/install/install.sh 的 PowerShell 对等实现二者保持相同的步骤骨架环境检查、依赖安装、仓库克隆、依赖同步、启动模型拉取、服务注册只是把systemd unit / launchd plist替换为Windows 计划任务Scheduled Task。一、一行命令安装One-liner install在普通或管理员权限的 PowerShell 中执行irm https://open-jarvis.github.io/OpenJarvis/install.ps1 | iex其中irm是Invoke-RestMethod的别名iex是Invoke-Expression的别名先远程下载脚本内容再直接在当前会话中执行。安装脚本执行的 7 个步骤对照 deploy/windows/install.ps1 的源码安装过程依次完成拒绝非 Windows 主机与过老系统通过$PSVersionTable.Platform -ne Win32NT判断平台通过[System.Environment]::OSVersion.Version.Build校验系统版本要求Windows 10 1809build 17763或更新。检查 Python 3.10 – 3.13优先探测python3回退到python若未安装会用 winget 自动安装Python.Python.3.13。值得注意Python 3.14 目前不被支持因为 numpy 尚未提供 cp314 Windows wheels见源码中的#432注释。检查git是否在 PATH缺失时用 winget 安装Git.Git。检查/安装uv若uv不在 PATH脚本会调用 Astral 官方 PowerShell 安装脚本https://astral.sh/uv/install.ps1并手动把%USERPROFILE%\.local\bin追加到当前会话 PATH以便后续步骤立即使用。克隆仓库到%LOCALAPPDATA%\OpenJarvis实际源码目录为%LOCALAPPDATA%\OpenJarvis\src可通过$env:OPENJARVIS_HOME覆盖安装根目录。若目录已存在脚本会跳过克隆-Force时改为git pull --ff-only更新。执行uv sync --extra desktop --group desktop-native安装 FastAPI 服务端、语音后端faster-whisper、sounddevice 等以及原生扩展。关于--group desktop-native的语义见 pyproject.tomlopenjarvis-rustPyO3 原生扩展被放在 PEP 735 依赖组而非desktopextra 中因此只有显式--group desktop-native才会从本地 Rust workspace 源码构建而pip install openjarvis[desktop]不会尝试从 PyPI 解析它。可选地注册计划任务注册一个登录时自动启动jarvis serve的计划任务详见第三节。此外安装脚本还会做两件 README 未展开讲但源码中明确存在的事自动安装并启动 Ollama、拉取入门模型若ollama不在 PATH会下载官方OllamaSetup.exe约 150 MB并以 NSIS 静默参数/S安装随后轮询等待 Ollama 守护进程就绪最多 60 秒期间若 5 秒仍未就绪会自动以ollama serve兜底启动再拉取入门模型qwen3.5:2b约 1.5 GB保证首次运行jarvis即可对话。生成jarvis.cmdshim在%LOCALAPPDATA%\OpenJarvis\bin\jarvis.cmd写入自定位 shim内容为uv run --project %~dp0..\src jarvis %*并把bin目录追加到用户级 PATH使任何新开的 PowerShell 都能直接敲jarvis命令。安装完成后脚本会提示模型拉取成功则直接运行jarvis失败则运行jarvis doctor查看进度。安装结束后的 PATH 注意事项安装脚本会把bin目录写入用户级PATH但当前已打开的 PowerShell 进程不会立即感知Windows 进程环境继承自父 shell。因此安装完成后请新开一个 PowerShell 窗口再执行jarvis。二、安装参数Flags 与环境变量双通道由于irm | iex的管道方式无法把param()参数传入脚本字符串install.ps1 提供了两套控制方式见 deploy/windows/install.ps1 的参数解析逻辑Flag直接运行脚本文件时作用-Service无条件注册计划任务不弹交互式询问-SkipService不询问、不注册计划任务-Force即使已完成也重新执行所有步骤含重新git pull环境变量通道irm | iex时生效与 Flag 同名语义一一对应环境变量等效 Flag说明OPENJARVIS_SKIP_SERVICE1-SkipService跳过服务注册OPENJARVIS_SERVICE1-Service强制注册服务OPENJARVIS_FORCE1-Force强制重跑源码中明确Any explicit -switch wins; env vars only fill in the gaps即显式 Flag 优先环境变量仅在 Flag 未给出时兜底。典型用法$env:OPENJARVIS_SKIP_SERVICE 1 irm https://open-jarvis.github.io/OpenJarvis/install.ps1 | iex如果需要对安装过程做更细粒度的控制例如组合-Force与-SkipService建议先把脚本保存到本地再执行irm https://open-jarvis.github.io/OpenJarvis/install.ps1 -OutFile install.ps1 .\install.ps1 -Force -SkipService交互式提示的判定细节当用户既没给-Service也没给-SkipService时脚本只在存在真实键盘会话[Environment]::UserInteractive为真且 stdin 未被重定向时才弹出Register OpenJarvis as a Windows scheduled task (auto-start at logon, loopback only)? [y/N]。对于非交互环境如 CI、管道会自动跳过服务注册并打印后续手动注册的提示。同时脚本会预先检查管理员权限——Register-ScheduledTask需要提升权限若用户显式要求-Service但当前 PowerShell 未提升会直接报错退出避免询问后再因 Access Denied 失败的糟糕体验。三、计划任务服务jarvis-service.ps1若安装时跳过了服务注册或后续需要查看/删除服务可使用 deploy/windows/jarvis-service.ps1 手动管理。该脚本是 Windows 侧对 systemd unit 与 launchd plist 的对等实现通过子命令驱动$srv $env:LOCALAPPDATA\OpenJarvis\src\deploy\windows\jarvis-service.ps1 # 安装幂等——已存在则替换 powershell -ExecutionPolicy Bypass -File $srv install # 查询状态 powershell -ExecutionPolicy Bypass -File $srv status # 卸载 powershell -ExecutionPolicy Bypass -File $srv uninstallinstall 的参数install子命令支持三个参数见 jarvis-service.ps1参数默认值说明-InstallRoot%LOCALAPPDATA%\OpenJarvis或$env:OPENJARVIS_HOME源码根目录须先运行过 install.ps1-ListenHost127.0.0.1绑定地址仅当设置了OPENJARVIS_API_KEY时才允许0.0.0.0-ListenPort8000监听端口计划任务的运行语义从 Install-Task 函数 可以看出任务的关键配置触发方式New-ScheduledTaskTrigger -AtLogOn -User $env:USERNAME即登录时启动执行主体uv run jarvis serve --host ListenHost --port ListenPort工作目录为src目录失败重启-RestartCount 3 -RestartInterval (New-TimeSpan -Minutes 1)——最多重启 3 次间隔 1 分钟无执行时限-ExecutionTimeLimit (New-TimeSpan -Seconds 0)即任务可无限期运行错过补跑-StartWhenAvailable登录被跳过时下次机会到来即补跑最低权限Principal 使用LogonType InteractiveRunLevel Limited以当前用户身份、受限权限运行电池友好-AllowStartIfOnBatteries与-DontStopIfGoingOnBatteries笔记本在电池供电下也能保持服务。install是幂等的若任务已存在会先Unregister-ScheduledTask再重新注册。status子命令会输出任务状态State、上次运行时间LastRun、上次结果LastRes十六进制错误码与下次运行时间NextRun。提示任务注册后立即手动启动可用Start-ScheduledTask -TaskName OpenJarvis。四、Loopback 与 LAN 暴露安全模型默认行为仅本机可访问默认情况下计划任务把服务绑定到127.0.0.1仅本机可访问无需 API Key。这与 macOS launchd 的对等配置一致——deploy/launchd/com.openjarvis.plist 同样默认--host 127.0.0.1并在注释中写明绑定本机回环地址即可免去 API Key 的负担。暴露到局域网必须先生成 API Key要在局域网内访问需要两步# 1. 生成 API Key。服务端拒绝在未配置 Key 的情况下绑定 0.0.0.0。 $env:OPENJARVIS_API_KEY (uv run jarvis auth generate-key) # 2. 以 -ListenHost 0.0.0.0 重新注册任务。 powershell -ExecutionPolicy Bypass -File $srv install -ListenHost 0.0.0.0这条强制规则的底层实现可以精确追溯到源码服务端在 src/openjarvis/cli/serve.py 启动前调用check_bind_safety(bind_host, api_keyapi_key)src/openjarvis/server/auth_middleware.py 中check_bind_safety的实现当绑定地址不是 loopbackipaddress.ip_address(host).is_loopback为假且 API Key 为空时直接打印错误并以SystemExit(1)拒绝启动提示语即为Run: jarvis auth generate-key同理systemd 侧通过 deploy/systemd/openjarvis.service 的EnvironmentFile/etc/openjarvis/env强制要求存在包含OPENJARVIS_API_KEY的环境文件缺失则 unit 启动失败——三者Windows / launchd / systemd在非回环必须鉴权这一安全边界上完全对齐。在 jarvis-service.ps1 中还有第二道防线install -ListenHost 0.0.0.0若发现$env:OPENJARVIS_API_KEY未设置会直接失败并给出指引而不是注册一个每次登录都会因无密钥而拒绝启动的坏任务。一个关键的 Windows 平台细节计划任务不继承环境变量jarvis-service.ps1 的注释解释了 Windows 特有的坑计划任务启动的进程不会继承注册时会话的环境变量。因此若你设置了OPENJARVIS_API_KEY来绑定0.0.0.0脚本会额外把该 Key 持久化写入用户级环境变量[System.Environment]::SetEnvironmentVariable(..., User)确保登录会话中的任务能读到它。这是只写回环地址时不需要、但 LAN 暴露时必须处理的步骤。五、与 systemd / launchd 的对等关系Parity Table关注点systemdLinuxlaunchdmacOSWindows服务定义deploy/systemd/openjarvis.servicedeploy/launchd/com.openjarvis.plistdeploy/windows/jarvis-service.ps1cmdlet 驱动默认绑定0.0.0.0配 API Key127.0.0.1无 API Key127.0.0.1无 API Key失败重启Restarton-failure RestartSec5KeepAlivetrueRestartCount3 RestartIntervalPT1M自动启动multi-user.targetRunAtLoadtrueAtLogOn触发器从上表可以看到一个有趣的设计差异systemd 默认绑定0.0.0.0但强制要求 API KeyEnvironmentFile缺失则失败而 launchd 与 Windows 默认回环绑定、无密钥即可用。三者的共同底线是任何非回环暴露都必须有鉴权只是默认是否暴露的取向不同。systemd 的 unit 还额外带了一套沙箱加固ProtectSystemstrict、PrivateTmptrue、NoNewPrivilegestrue等见 openjarvis.serviceWindows 侧则以受限权限计划任务作为对应。六、更新 OpenJarvis两种更新方式任选其一方式一git 手动更新cd $env:LOCALAPPDATA\OpenJarvis\src git pull --ff-only uv sync --extra desktop --group desktop-native--ff-only保证只做快进合并避免本地改动导致更新失败。方式二重跑安装器并加-Forceirm https://open-jarvis.github.io/OpenJarvis/install.ps1 | iex # 再以文件方式重跑并传 -Force # irm ... -OutFile install.ps1; .\install.ps1 -Force-Force会强制重新执行所有步骤包括git pull --ff-only与重新uv sync依赖变化会在此生效。注意更新后若服务依赖的命令或环境有变建议重新执行一次jarvis-service.ps1 install以刷新计划任务。七、卸载powershell -ExecutionPolicy Bypass -File $env:LOCALAPPDATA\OpenJarvis\src\deploy\windows\jarvis-service.ps1 uninstall Remove-Item -Recurse -Force $env:LOCALAPPDATA\OpenJarvis卸载分两步先通过uninstall子命令停止并注销计划任务源码中会先Stop-ScheduledTask再Unregister-ScheduledTask再删除整个安装目录。需要特别说明的是卸载不会移除uv——它是独立工具可能被你的其他 Python 项目共用同理Ollama 及其拉取的模型也不在卸载范围内如需清理请另行处理。八、常见问题与排障jarvis命令找不到安装脚本将bin目录写入了用户 PATH但当前会话不生效。请新开 PowerShell 窗口若仍不行手动确认%LOCALAPPDATA%\OpenJarvis\bin\jarvis.cmd存在且 PATH 中包含该目录。首次对话失败大概率是入门模型qwen3.5:2b未拉取完成。运行jarvis doctor查看模型与后台编排器bg-orchestrator的重试进度。install -ListenHost 0.0.0.0报错请先执行$env:OPENJARVIS_API_KEY (uv run jarvis auth generate-key)再重试。服务端与脚本的双重防线都不允许无密钥的非回环绑定。任务启动后立刻退出且日志显示拒绝绑定检查用户环境变量中是否持久化了OPENJARVIS_API_KEYLAN 场景必需以及jarvis serve依赖的引擎如 Ollama是否在运行。Python 版本不符当前仅支持 3.10–3.133.14 因 numpy 无 Windows wheels 暂不支持。可通过winget install Python.Python.3.13安装后重跑安装器。【免费下载链接】OpenJarvisPersonal AI, On Personal Devices项目地址: https://gitcode.com/gh_mirrors/op/OpenJarvis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考