网页版安装
本页面向第一次使用 PilotDeck 网页版的用户。推荐先走一键安装路径，源码安装后续会放到开发指南中。
准备工作
开始前请确认你有：
- 目前一键安装脚本仅支持 macOS/Linux（Windows 目前仅支持开发者模式）。
- 可用网络。
- 一个可用的 LLM API Key。
安装脚本会检查 Git 和 Node.js。如果没有合适的 Node.js，会尝试通过 fnm (Fast Node Manager) 自动安装 Node.js 22。
一键安装
打开终端，复制下面的命令并回车：
curl -fsSL https://raw.githubusercontent.com/OpenBMB/PilotDeck/main/install.sh | bash
如果终端要求输入密码，输入 Mac 开机密码并回车。输入时屏幕不会显示字符，这是终端的正常行为。通常这是为了创建 /usr/local/bin/pilotdeck 命令链接。
脚本会安装到：
~/.pilotdeck/app/
配置文件位置：
~/.pilotdeck/pilotdeck.yaml
命令行入口：
pilotdeck
配置 LLM 服务商
安装完成后，浏览器会打开配置页面。如果没有自动打开，手动访问：
http://localhost:3001
你会看到 LLM Provider Setup 页面。配置流程如下：
第一步：选择预设
页面上方提供常见服务商预设：
- Anthropic
- OpenRouter
- MiniMax
- OpenAI
点击对应服务商后，API Base URL、Model ID 和 Protocol Type 会自动填入。
如果你的服务商不在预设里，例如 DeepSeek，可以跳过预设，手动填写下面几个字段。
第二步：填写 API 信息
| 字段 | 说明 | 示例 |
|---|---|---|
| API Base URL | 服务商 API 地址 | https://api.deepseek.com/v1 |
| API Key | 你的服务商密钥 | sk-xxxxxxxx |
| Model ID | 模型名称或标识符 | deepseek-chat |
| Protocol Type | 协议类型 | OpenAI 兼容服务通常选择 openai-chat |
第三步：测试连接
点击 Test Connection。
- 如果出现
Connected successfully，说明连接成功。 - 如果出现红色错误，优先检查 API Key、网络、服务商余额和 API Base URL。
第四步：保存
测试通过后点击 Save。配置会写入：
~/.pilotdeck/pilotdeck.yaml
之后页面会进入主界面。
验证安装成功
进入主界面后，在底部输入框发送一条消息。如果 AI 正常回复，说明安装和配置已经完成。
日常使用
| 操作 | 方法 |
|---|---|
| 启动 | 在终端输入 pilotdeck |
| 使用 | 浏览器访问 http://localhost:3001 |
| 关闭 | 在运行服务的终端按 Ctrl + C |
| 更新 | 重新运行一键安装命令 |
重新运行安装命令会更新 ~/.pilotdeck/app/ 中的代码，不会覆盖已有配置。
常见问题
Test Connection 失败
常见原因包括 API Key 错误、网络不可达、服务商余额不足、API Base URL 缺少 /v1。
输入 pilotdeck 提示 command not found
安装时可能将命令放到了 ~/.local/bin/。将路径加入 shell 配置：
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
# 然后重新启动
pilotdeck
端口冲突
错误信息示例：
[CONFLICT] Port 3001 already in use by PID 12345.
或
[CONFLICT] Port 18080 (proxy) already in use by PID 76286.
原因：之前的 PilotDeck 没有完全退出，或者有其他程序占用了同一端口。PilotDeck 使用两个端口：
| 端口 | 用途 |
|---|---|
| 3001 | 主服务（Web 界面） |
| 18080 | AI 代理（转发请求到 LLM 服务商） |
解决方法：
# 强制终止端口的进程（推荐）
kill -9 $(lsof -i :3001 -t) 2>/dev/null
kill -9 $(lsof -i :18080 -t) 2>/dev/null
# 然后重新启动
pilotdeck
或
# 用其他端口启动（只能改主服务端口）
pilotdeck --port 8080
# 然后浏览器访问 http://localhost:8080
每次用完 PilotDeck 后，在终端按 Ctrl + C 正常退出，不要直接强制关闭终端，可以避免端口冲突。
浏览器没有自动打开
手动访问：
http://localhost:3001
卸载
只删除程序和命令链接：
rm -rf ~/.pilotdeck/app
rm -f /usr/local/bin/pilotdeck
rm -f ~/.local/bin/pilotdeck
如果也要删除配置：
rm -f ~/.pilotdeck/pilotdeck.yaml
如果删除整个 ~/.pilotdeck/ 目录，会清除配置、数据和历史记录。执行前请确认你不再需要这些数据。