PilotDeck

面向生产力的智能体开源平台

根据你的操作系统与使用方式，选择桌面应用、一键安装或源码安装。按指引完成环境检查、启动与日常维护，并查阅常见安装和连接问题。

一、环境要求

项目	要求
操作系统	Windows 10 及以上 / macOS 14 及以上 / Ubuntu 22.04 及以上，均提供桌面客户端；一键安装脚本覆盖 macOS / Linux / Windows
LLM API Key	至少一个可通过 API 调用的大语言模型（协议支持 openai、openai-responses、anthropic、google 等，兼容 DeepSeek、Qwen、Kimi、MiniMax、OpenRouter 等服务商）
端口	3001（Web UI）、18789（Gateway）需未被占用；Web 端口被占用时启动器会自动尝试其他端口

二、安装

方式一：桌面应用安装（推荐）

Platform	File
macOS (arm64)	PilotDeck-2026.1013.0-mac-arm64.dmg
macOS (Intel / x64)	PilotDeck-2026.1013.0-mac-x64.dmg
Windows (x64)	PilotDeck-2026.1013.0-win-x64-setup.exe

最新安装包可查看：https://github.com/OpenBMB/PilotDeck/releases

平台	系统版本要求	处理器架构	安装包格式
Windows	Windows 10 及以上	x64、ARM64	.exe
macOS	macOS 14 及以上	Intel（x64）、Apple Silicon（ARM64）	.dmg
Linux（DEB）	Ubuntu 22.04 及以上	x64、ARM64	.deb
Linux（RPM）	Rocky Linux 9 及以上	x64、ARM64	.rpm

安装方法：

Windows：双击下载的 .exe 安装程序，按照安装向导提示完成安装。
macOS：双击下载的 .dmg 安装镜像，将 PilotDeck 拖入"应用程序"（Applications）文件夹，随后从"应用程序"启动。
Linux（DEB）：在安装包所在文件夹打开终端，使用 APT 安装（可自动处理依赖）：sudo apt install ./PilotDeck-VERSION-linux-x64.deb
Linux（RPM）：在安装包所在文件夹打开终端，使用 DNF 安装（可自动处理依赖）：sudo dnf install ./PilotDeck-VERSION-linux-x64.rpm

上述命令以 x64 安装包为例，请将 VERSION 替换为实际版本号；ARM64 设备请将文件名中的 x64 替换为 arm64。Linux 安装完成后，可从应用菜单启动 PilotDeck。

方式二：一键安装（macOS / Linux / Windows）

Bash

curl -fsSL https://raw.githubusercontent.com/OpenBMB/PilotDeck/main/install.sh | bash

安装脚本会检查 Git 和受支持的 Node.js 22 运行时，安装依赖并构建 Web 前端。若终端要求输入密码，输入 Mac 登录密码即可（输入时不可见，属正常现象）。

安装路径：~/.pilotdeck/app/
配置文件：~/.pilotdeck/pilotdeck.yaml
命令入口：pilotdeck

Windows：打开普通用户权限的 PowerShell，执行：

PowerShell

powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/OpenBMB/PilotDeck/main/install.ps1 | iex"

脚本会在 %USERPROFILE%\.pilotdeck 下安装 PilotDeck，检查 Node.js 22.13+ 和 node:sqlite，在可用时通过 winget 补充依赖，并在 %USERPROFILE%\.pilotdeck\bin 中生成 pilotdeck.cmd 启动器。Git LFS 的拉取失败可以无视。

安装完成后，脚本会启动 PilotDeck 并显示 Web UI 地址，但不会自动打开浏览器。可复制终端显示的地址，或运行：

PowerShell

Start-Process "http://localhost:3001"

以后再次使用时，请新开一个 PowerShell 窗口并运行：

PowerShell

pilotdeck

如果提示找不到 pilotdeck，可直接运行启动器：

PowerShell

& "$HOME\.pilotdeck\bin\pilotdeck.cmd"

默认访问地址为 http://localhost:3001，端口被占用时启动器会尝试其他端口，请以启动终端输出的地址为准。pilotdeck status 可查看运行状态。使用结束后，回到运行服务的 PowerShell 窗口按 Ctrl+C 正常关闭。

一键安装使用 GitHub main 分支，重新运行安装命令会获取当前版本。

如果默认 Web 端口已被占用，可以换用其他端口启动，例如：

Bash

pilotdeck --port 8080

此时应访问终端实际显示的地址。Web 界面端口与 AI 代理的内部端口不同，不要混用。

方式三：源码安装（开发者）

所有系统都需要 Node.js >=22.13.0 <23、Git、Python 3、系统编译工具和 ripgrep。Git LFS 只用于下载大型演示媒体，不是核心功能的必要条件。

macOS

第一步：安装系统工具。

安装 Xcode Command Line Tools：

Bash

xcode-select --install

如果使用 Homebrew，可安装 Git LFS 和 ripgrep：

Bash

brew install git-lfs ripgrep

再通过你常用的 Node.js 版本管理器安装 Node.js 22。例如使用 fnm：

Bash

curl -fsSL https://fnm.vercel.app/install | bash
# 重新打开终端后执行
fnm install 22
fnm use 22
node --version

node --version 必须显示 v22.13.0 或更高的 v22.x。Intel Mac 还应运行 node -p "process.arch"，确认输出为 x64。

第二步：拉取源码。

在准备存放代码的目录中执行：

Bash

GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/OpenBMB/PilotDeck.git
cd PilotDeck

第三步：启用 pnpm。

Bash

node --version
corepack enable

如果当前 Node.js 环境没有 Corepack，可安装官方源码指南指定的 pnpm 版本：

Bash

npm install -g pnpm@10.32.1
pnpm --version

第四步：安装项目依赖。

仍在 PilotDeck 仓库根目录中执行：

Bash

corepack pnpm install --frozen-lockfile --filter pilotdeck --filter pilotdeck-ui

如果上一步使用了全局 pnpm，则改为执行：

Bash

pnpm install --frozen-lockfile --filter pilotdeck --filter pilotdeck-ui

如果安装原生依赖时提示 Python 缺少 distutils，可尝试指定系统 Python 后重新安装：

Bash

PYTHON=/usr/bin/python3 corepack pnpm install --frozen-lockfile --filter pilotdeck --filter pilotdeck-ui

第五步：启动 Web 服务。

源码安装不会生成全局 pilotdeck 命令。在仓库根目录中选择一种模式启动。

开发模式支持热更新，适合修改和调试源码：

Bash

cd ui
npm run dev

浏览器访问终端输出的开发地址，默认为 http://localhost:5173。端口被占用时，开发启动器会尝试其他端口。

生产模式适合正常体验和持续运行：

Bash

cd ui
npm run start

浏览器访问 http://localhost:3001。两种模式选择一种即可；保持启动终端运行，关闭服务时按 Ctrl+C。

Windows

Windows 源码安装有两条路径：推荐使用 WSL2 Ubuntu，也可选择原生 PowerShell。

WSL2 Ubuntu（推荐）

第一步：安装 WSL2 和 Ubuntu。

在管理员 PowerShell 中执行：

PowerShell

wsl --install -d Ubuntu

如果系统要求重启，请先重启并完成 Ubuntu 的首次用户设置。后续命令都在 Ubuntu 终端中执行，不是在 PowerShell 中执行。

第二步：在 Ubuntu 中安装系统工具和 Node.js。

Bash

sudo apt-get update
sudo apt-get install -y git git-lfs ripgrep build-essential python3
curl -fsSL https://fnm.vercel.app/install | bash
# 重新打开 Ubuntu 终端后执行
fnm install 22
fnm use 22
node --version

确认 Node.js 为 v22.13.0 或更高的 v22.x。

第三步：在 Ubuntu 中拉取源码。

Bash

GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/OpenBMB/PilotDeck.git
cd PilotDeck

第四步：启用 pnpm 并安装依赖。

Bash

corepack enable
corepack pnpm install --frozen-lockfile --filter pilotdeck --filter pilotdeck-ui

如果没有 Corepack，可改用：

Bash

npm install -g pnpm@10.32.1
pnpm install --frozen-lockfile --filter pilotdeck --filter pilotdeck-ui

第五步：在 Ubuntu 中启动 Web 服务。

在仓库根目录中选择一种模式。开发模式支持热更新：

Bash

cd ui
npm run dev

浏览器访问终端输出的开发地址，默认为 http://localhost:5173。端口被占用时，开发启动器会尝试其他端口。

生产模式适合正常体验和持续运行：

Bash

cd ui
npm run start

浏览器访问 http://localhost:3001。两种模式选择一种即可；保持 Ubuntu 终端运行，关闭服务时按 Ctrl+C。

原生 Windows PowerShell

第一步：安装系统工具。

在 PowerShell 中逐行执行：

PowerShell

winget install OpenJS.NodeJS.LTS
winget install Git.Git
winget install GitHub.GitLFS
winget install Python.Python.3.12
winget install BurntSushi.ripgrep.MSVC
winget install Microsoft.VisualStudio.2022.BuildTools --override "--wait --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"

安装完成后关闭并重新打开 PowerShell，再检查环境：

PowerShell

git lfs install
node --version
node -p "process.arch"
npm --version
git --version
python --version
rg --version

node --version 必须显示 v22.13.0 或更高的 v22.x，process.arch 应输出 x64。如果 winget 安装的 Node.js LTS 已经不是 v22.x，请先通过 Node.js 版本管理器或官方 x64 Node.js 22 压缩包切换版本。

第二步：拉取源码。

PowerShell

$env:GIT_LFS_SKIP_SMUDGE = "1"
git clone https://github.com/OpenBMB/PilotDeck.git
Set-Location PilotDeck

第三步：启用 pnpm。

PowerShell

corepack enable

如果当前环境没有 Corepack：

PowerShell

npm.cmd install -g pnpm@10.32.1
pnpm --version

第四步：安装项目依赖。

PowerShell

corepack pnpm install --frozen-lockfile --filter pilotdeck --filter pilotdeck-ui

如果使用的是全局 pnpm，则改为执行：

PowerShell

pnpm install --frozen-lockfile --filter pilotdeck --filter pilotdeck-ui

PowerShell 如果提示 npm.ps1 或 pnpm.ps1 因执行策略而无法加载，可分别改用 npm.cmd 或 pnpm.cmd。

第五步：启动 Web 服务。

在仓库根目录中选择一种模式。开发模式支持热更新：

PowerShell

Set-Location ui
npm.cmd run dev

浏览器访问终端输出的开发地址，默认为 http://localhost:5173。端口被占用时，开发启动器会尝试其他端口。

生产模式适合正常体验和持续运行：

PowerShell

Set-Location ui
npm.cmd run start

浏览器访问 http://localhost:3001。两种模式选择一种即可；保持 PowerShell 窗口运行，关闭服务时按 Ctrl+C。

Linux

以下以 Debian/Ubuntu 为例；Fedora/RHEL 和 Arch Linux 的系统依赖命令也列在本步骤中。

第一步：安装系统工具。

Debian/Ubuntu：

Bash

sudo apt-get update
sudo apt-get install -y git git-lfs ripgrep build-essential python3

Fedora/RHEL：

Bash

sudo dnf install -y git git-lfs ripgrep gcc gcc-c++ make python3

Arch Linux：

Bash

sudo pacman -Sy --needed git git-lfs ripgrep base-devel python

再安装 Node.js 22。例如使用 fnm：

Bash

curl -fsSL https://fnm.vercel.app/install | bash
# 重新打开终端后执行
fnm install 22
fnm use 22
node --version

确认输出为 v22.13.0 或更高的 v22.x，不要使用 Node.js 23 或更高版本。

第二步：拉取源码。

Bash

GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/OpenBMB/PilotDeck.git
cd PilotDeck

第三步：启用 pnpm。

Bash

corepack enable

如果当前环境没有 Corepack：

Bash

npm install -g pnpm@10.32.1
pnpm --version

第四步：安装项目依赖。

Bash

corepack pnpm install --frozen-lockfile --filter pilotdeck --filter pilotdeck-ui

如果使用的是全局 pnpm，则改为执行：

Bash

pnpm install --frozen-lockfile --filter pilotdeck --filter pilotdeck-ui

第五步：启动 Web 服务。

在仓库根目录中选择一种模式。开发模式支持热更新：

Bash

cd ui
npm run dev

浏览器访问终端输出的开发地址，默认为 http://localhost:5173。端口被占用时，开发启动器会尝试其他端口。

生产模式适合正常体验和持续运行：

Bash

cd ui
npm run start

浏览器访问 http://localhost:3001。两种模式选择一种即可；保持启动终端运行，关闭服务时按 Ctrl+C。

以上各系统的拉取命令都通过 GIT_LFS_SKIP_SMUDGE=1 跳过大型演示媒体，不影响 PilotDeck 核心功能。之后如需这些文件，可在仓库根目录执行：

Bash

git lfs pull

依赖安装命令会按照仓库提交的 pnpm-lock.yaml 安装 Gateway 和 Web UI，并排除 Web 部署不需要的 Electron 打包依赖。不要用 npm install 替换。

源码方式首次启动时，如果没有找到有效的 ~/.pilotdeck/pilotdeck.yaml，Web UI 会先进入 Onboarding。保存模型服务商、API Key 和模型后，PilotDeck 会写入配置并自动启动 Gateway。

三、网页端日常使用

操作	方法
启动	终端运行 `pilotdeck`
使用	浏览器访问 `http://localhost:3001`
停止	终端按 `Ctrl + C`
更新	再次运行一键安装命令（不覆盖已有配置）

CLI 命令

Bash

pilotdeck "分析当前项目结构"     # 一次性对话
pilotdeck server                 # 启动 Gateway 长驻服务（默认端口 18789）
pilotdeck tui                    # 交互式终端 UI
pilotdeck cron list              # 列出定时任务
pilotdeck cron create --session <key> --message <text> --cron "<表达式>"  # 创建定时任务

四、常见问题

Q：测试连接失败

A：检查 API Key 是否正确、网络是否可达、Provider 余额是否充足、API Base URL 是否包含 /v1。

Q：终端中输入 pilotdeck 提示命令未找到

A：

检查是否在 PATH 中：

Bash

which pilotdeck
ls -la /usr/local/bin/pilotdeck
ls -la ~/.local/bin/pilotdeck

如果链接到了 ~/.local/bin，确保该目录在 PATH 中：

Bash

# 添加到 ~/.zshrc 或 ~/.bashrc
export PATH="$HOME/.local/bin:$PATH"
source ~/.zshrc

手动创建链接：

Bash

ln -sf ~/.pilotdeck/app/ui/server/cli.js /usr/local/bin/pilotdeck

Q：端口冲突（Port 3001/18080 already in use）

A：

Bash

lsof -i :3001 && kill -9 <PID>

Q：Node.js 版本不对

A：

Bash

# 使用 fnm
curl -fsSL https://fnm.vercel.app/install | bash
fnm install 22
fnm use 22

# 或使用 nvm
nvm install 22
nvm use 22

# 验证版本
node --version

Q：npm install 失败

A：清理缓存后重试

Bash

npm cache clean --force
cd ~/.pilotdeck/app
rm -rf node_modules package-lock.json
npm install

如果是网络问题，可以设置 npm 镜像：

Bash

npm config set registry https://registry.npmmirror.com
npm install

Q：桌面应用无法启动（macOS）/ 闪退

A：经飞书、微信等沙盒 IM 接收的 DMG 会带 com.apple.provenance 扩展属性，导致 Gatekeeper 拒绝执行；从浏览器直接下载或通过 AirDrop 传输的 DMG 不会有此问题。

Bash

# 方法一：运行修复脚本
bash install-pilotdeck.sh

# 方法二：手动清除扩展属性
xattr -cr /Applications/PilotDeck.app
open /Applications/PilotDeck.app

或前往 系统设置 → 隐私与安全性，允许 PilotDeck 运行。

Q：安装脚本报错 git is not installed？

A：安装 Xcode 命令行工具：xcode-select --install

安装、配置、使用过程中如遇到其他问题，可在飞书社群提出，技术团队会帮忙解答～

五、相关资源

主题	入口
源码仓库	OpenBMB/PilotDeck
桌面应用安装包	GitHub Releases
官方网站	pilotdeck.openbmb.cn
教程文档	PilotDeck Docs

开发者精选

查看全部 →

PilotDeck 智能体PilotDeck 千图百炼：AI 生图监工让 Agent 盯着文生图模型干活，自动评图、重试直到达标 PilotDeck 智能体Later：长期生活记忆 Agent基于 PilotDeck App 的私人管家，跨会话记住你的生活偏好 PilotDeck 智能体PilotDeck 开发在线智能数据系统基于 PilotDeck 构建智能数据管理系统的实践分享 PilotDeck 智能体PilotDeck 数据分析：考勤、报销与资产盘点三个高频办公场景：从原始记录一键生成统计报表与审计结论 PilotDeck 智能体PilotDeck Word 文件生成与编辑批量生成合同文稿、按审阅意见逐条修改，修订可追溯 PilotDeck 智能体PilotDeck PPT 制作一句话到一份大纲、模板、逐页成稿的完整 PPT 生产线

一、环境要求​

二、安装​

方式一：桌面应用安装（推荐）​

方式二：一键安装（macOS / Linux / Windows）​

方式三：源码安装（开发者）​

macOS​

Windows​

WSL2 Ubuntu（推荐）​

原生 Windows PowerShell​

Linux​

三、网页端日常使用​

CLI 命令​

四、常见问题​

五、相关资源​

开发者精选

一、环境要求

二、安装

方式一：桌面应用安装（推荐）

方式二：一键安装（macOS / Linux / Windows）

方式三：源码安装（开发者）

macOS

Windows

WSL2 Ubuntu（推荐）

原生 Windows PowerShell

Linux

三、网页端日常使用

CLI 命令

四、常见问题

五、相关资源