多平台部署与容器化

前面的章节默认你在 macOS 或 Linux 上操作。但 pi 本身是跨平台的，Windows、Android 也能跑。只是每个平台都有自己的”脾气”——路径不对、权限不对、终端不对，都可能踩坑。

本章把四个主流平台的安装差异、注意事项和容器化方案一次性讲明白。

本章基于 pi v0.84.1。

---

平台支持概览

pi 的核心运行时是 Node.js。只要系统能装 Node.js，理论上就能跑 pi。官方验证过的平台是：

平台	支持程度	终端推荐
macOS	一等公民	iTerm2、Kitty、Warp
Linux	一等公民	任何支持 True Color 的终端
Windows	通过 Git Bash 或 WSL	Windows Terminal
Android	通过 Termux	Termux 内置终端

macOS 和 Linux 是开发主力，体验最完整。Windows 需要额外折腾一下 shell，Android 偏向”能用就行”。

---

macOS：开箱即用，但终端值得讲究

macOS 是 pi 开发者的主力平台，功能最完整。

终端选择

系统自带的 Terminal.app 也能用，但三款第三方终端体验好得多：

终端	安装	亮点
iTerm2	brew install --cask iterm2	原生 True Color、图片显示好、功能丰富
Kitty	brew install --cask kitty	GPU 加速、飞快、协议先进
Warp	brew install --cask warp	现代化 UI、内置 AI 功能

选哪个都行，看你偏好。我个人习惯 iTerm2——稳定、社区大、出问题搜一下就有解答。

验证 True Color

pi 的终端界面依赖 True Color（24 位色）渲染。确认你的终端支持：

echo $COLORTERM

输出 truecolor 就对了。没输出说明终端不支持，换个上面推荐的终端就行。

Shell 别名

往 ~/.zshrc 加几个别名，日常操作快很多：

# pi 常用别名
alias pic='pi -c'     # 继续最近会话
alias pir='pi -r'     # 恢复历史会话
alias piq='pi -p'     # 快速一次性问答
alias pin='pi --name' # 命名会话

---

Linux：最灵活，但注意 Node.js 版本

Linux 几乎没有平台层面的限制。核心就两条：

Node.js 版本

pi 0.84.x 要求 Node ≥ 22。Ubuntu/Debian 的默认 apt 源经常是 Node 18，直接装会翻车。

用 NodeSource 或 nvm 装高版本：

# 用 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
nvm install 22
nvm use 22

# 验证
node --version

然后全局安装 pi：

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

tmux 集成

服务器上跑 pi，经常要 SSH 连着。tmux 能让 pi 在你断开 SSH 后继续跑：

# 安装 tmux
sudo apt install tmux   # Debian/Ubuntu
sudo dnf install tmux   # Fedora

# 启动新会话
tmux new -s pi-session

在 tmux 里跑 pi，不小心断网了重连 tmux attach -t pi-session 就能回来。

~/.tmux.conf 加点配置：

# True Color 支持
set -g default-terminal "tmux-256color"
set -ag terminal-overrides ",*:Tc"

# 回滚缓冲区加大（AI 输出经常很长）
set -g history-limit 50000

---

Windows：能跑，但需要绕个弯

Windows 上的 pi 依赖 bash shell。它不会直接用 PowerShell 或 CMD 执行命令，而是检测系统中的 bash 环境。

Shell 检测顺序

pi 在 Windows 上按以下顺序找 bash：

1. ~/.pi/agent/settings.json 中自定义的 shellPath
2. Git Bash（C:\Program Files\Git\bin\bash.exe）
3. PATH 上的 bash.exe（Cygwin、MSYS2、WSL）

绝大多数用户装个 Git for Windows 就够了——它自带 Git Bash，pi 自动检测到。

自定义 Shell 路径

如果你想用 WSL 里的 bash 或者 Cygwin：

{
  "shellPath": "C:\\cygwin64\\bin\\bash.exe"
}

写进 C:\Users\你的用户名\.pi\agent\settings.json。

安装流程

# 用 winget 装 Node.js
winget install OpenJS.NodeJS.LTS

# 全局安装 pi（--ignore-scripts 跳过 native 编译）
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

Windows 特有的快捷键差异

功能	Windows	macOS/Linux
粘贴图片	Alt+V	Ctrl+V
多行输入	Ctrl+Enter	Shift+Enter
发送追加消息	需重映射	Alt+Enter

Windows Terminal 里 Alt+Enter 默认是全屏快捷键。如果你想让 pi 用这个发送追加消息，得去终端的设置里搜 toggleFullscreen，把它的快捷键换成别的组合。

WSL 推荐

说实话，如果你在 Windows 上做开发，装个 WSL2 是性价比最高的方案。WSL 里跑的就是纯 Linux，pi 的行为和 Linux 下完全一致——没有 shell 兼容问题、快捷键统一、Ctrl+Z 挂起也能用。

# PowerShell 管理员
wsl --install -d Ubuntu

装完后在 WSL 里按 Linux 那一节的流程走就行。

---

Termux：把 pi 塞进 Android 手机

Termux 是 Android 上的 Linux 终端模拟器。pi 在手机上跑，听起来有点离谱，但确实能用——前提是你接个蓝牙键盘，或者只是临时查点东西。

安装

千万不要用 Google Play 的 Termux，那个版本已经废弃。去 GitHub 或 F-Droid 下载。

# 更新包
pkg update && pkg upgrade

# 装依赖
pkg install nodejs git

# 安装 pi
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

# 创建配置目录
mkdir -p ~/.pi/agent

# 运行
pi

剪贴板支持

装上 Termux:API 应用（同样从 GitHub/F-Droid 获取），然后在 Termux 里装命令行工具：

pkg install termux-api

剪贴板操作就能用了——termux-clipboard-set 复制、termux-clipboard-get 粘贴。但图片剪贴板不支持，Ctrl+V 贴图功能在 Termux 上没效果。

存储访问

Android 的权限体系比较严格。要访问手机的共享存储（下载、文档等目录），先跑一次：

termux-setup-storage

然后通过 ~/storage/shared/ 访问你手机里的文件。

Termux 版 AGENTS.md

给 pi 写一份 Termux 环境说明，帮它理解自己在手机上跑：

# Agent Environment: Termux on Android

## Location
- **OS**: Android (Termux)
- **Home**: `/data/data/com.termux/files/home`
- **Shared storage**: `/storage/emulated/0`

## Useful Commands
- `termux-open-url "https://..."` - 打开网址
- `termux-open file.pdf` - 用默认应用打开文件
- `termux-clipboard-set "text"` - 复制到剪贴板
- `termux-notification -t "Title" -c "Content"` - 发通知

Termux 的局限性

• 无图片剪贴板：Termux 的剪贴板 API 只有文本
• 无 native 二进制：部分可选的 native 依赖在 ARM64 Android 上不可用，安装时 --ignore-scripts 跳过了这些
• 存储权限：需要手动授权才能访问共享存储
• 性能：手机 SoC 的性能肯定不如桌面，大任务跑起来慢是正常的

---

Docker：一键隔离，干净利落

pi 默认以你的用户权限运行，能读写整个文件系统。如果你想让 pi 只碰特定的目录、网络隔离、或者在不同环境下跑多个实例，Docker 是最简单的方案。

方案一：整个 pi 进程放进容器

最直接的方式——pi 连进程带工具都在容器里跑。写一个 Dockerfile.pi：

FROM node:24-bookworm-slim

RUN apt-get update \
  && apt-get install -y --no-install-recommends bash ca-certificates git ripgrep \
  && rm -rf /var/lib/apt/lists/*
RUN npm install -g --ignore-scripts @earendil-works/pi-coding-agent

WORKDIR /workspace
ENTRYPOINT ["pi"]

构建并运行：

# 构建镜像
docker build -t pi-sandbox -f Dockerfile.pi .

# 运行容器
docker run --rm -it \
  -e ANTHROPIC_API_KEY \
  -v "$PWD:/workspace" \
  -v pi-agent-home:/root/.pi/agent \
  pi-sandbox

几个关键参数说明：

• -e ANTHROPIC_API_KEY：把宿主机的环境变量传入容器，pi 用这个鉴权
• -v "$PWD:/workspace"：把当前目录挂载进容器的 /workspace，pi 读写容器内的 /workspace 就是在操作你宿主机上的项目文件
• -v pi-agent-home:/root/.pi/agent：用 Docker 命名卷存 pi 的配置和会话，容器销毁后数据还在

方案二：Gondolin 微虚拟机扩展

如果你不想把整个 pi 进程放进容器，只想把工具执行隔离起来（保留宿主机上的认证），可以用 Gondolin——一个本地 Linux 微虚拟机。pi 通过扩展把 read、write、edit、bash、grep、find、ls 这些内置工具全部路由到 VM 里执行。

# 复制扩展
cp -R packages/coding-agent/examples/extensions/gondolin ~/.pi/agent/extensions/gondolin
cd ~/.pi/agent/extensions/gondolin
npm install --ignore-scripts

# 在项目目录下启动
cd /path/to/project
pi -e ~/.pi/agent/extensions/gondolin

Gondolin 的前提是装了 QEMU，Node ≥ 23.6。它把宿主机的当前工作目录挂载为 VM 里的 /workspace，文件读写会写穿到宿主机。

方案三：OpenShell 策略控制沙箱

如果你需要更细粒度的控制——文件系统访问、网络策略、进程权限——NVIDIA OpenShell 提供了策略驱动的沙箱：

# 注册网关
openshell gateway add <gateway-url> --name my-gateway
openshell gateway select my-gateway

# 在沙箱里启动 pi
openshell sandbox create --name pi-sandbox --from pi -- pi

OpenShell 走远程网关时，项目文件不会自动同步。需要手动上传：

openshell sandbox upload pi-sandbox ./repo /workspace
# ... 在沙箱里操作 ...
openshell sandbox download pi-sandbox /workspace/repo ./repo-out

OpenShell 的一个亮点是模型凭证托管——API Key 留在沙箱外面，沙箱内的 pi 通过 https://inference.local 请求模型，网关在外部注入凭证。

三种方案怎么选

方案	隔离程度	复杂度	适合场景
Plain Docker	进程级	低	日常隔离，跑一次性的 pi 任务
Gondolin	VM 级	中	需要隔离工具执行但不隔离认证
OpenShell	策略级	高	企业级权限控制、远程沙箱

大多数个人用户用 Plain Docker 就足够了。装个 Docker Desktop，写个 Dockerfile，两分钟跑起来。

---

环境变量与配置文件路径

各平台的环境变量设置方式和配置文件路径不一样。一张表说清楚：

环境变量设置

平台	持久化方式	示例
macOS / Linux	~/.zshrc 或 ~/.bashrc	export ANTHROPIC_API_KEY=sk-xxx
Windows (Git Bash)	~/.bashrc	同上
Windows (系统级)	系统属性 → 环境变量	GUI 操作
Docker	docker run -e 或 .env	-e ANTHROPIC_API_KEY
Termux	~/.bashrc	同 Linux

对于 llama.cpp 提供商，pi 支持直接在环境变量里设：

export LLAMA_BASE_URL=http://127.0.0.1:8080
export LLAMA_API_KEY=your-key

配置文件路径

文件	macOS / Linux / Termux	Windows
全局 AGENTS.md	~/.pi/agent/AGENTS.md	C:\Users\用户名\.pi\agent\AGENTS.md
全局 settings.json	~/.pi/agent/settings.json	C:\Users\用户名\.pi\agent\settings.json
全局 prompts/	~/.pi/agent/prompts/	C:\Users\用户名\.pi\agent\prompts\
项目 settings	<项目>/.pi/settings.json	同
项目 prompts	<项目>/.pi/prompts/	同
会话数据	~/.pi/agent/sessions/	C:\Users\用户名\.pi\agent\sessions\
llama.cpp 模型	~/.pi/agent/models/	C:\Users\用户名\.pi\agent\models\

路径模式是一致的——Linux/macOS 遵循 ~/.pi/agent/，Windows 映射为 %USERPROFILE%\.pi\agent\。pi 内部自动处理了这个映射，你不用手动转。

settings.json 平台差异

settings.json 的结构是跨平台统一的，但有少数配置项只在特定平台有意义：

• shellPath（Windows）：前面说过，指定 bash 路径
• compaction（全平台）：下下章会详细讲
• 其他配置项没有平台差异

---

终端设置优化

不管你用什么平台，几条通用的终端建议：

设置	建议值	原因
True Color	启用	pi 的界面依赖 24 位色彩
字体	等宽字体（JetBrains Mono、Fira Code）	代码对齐和特殊字符显示
回滚缓冲区	至少 10000 行	AI 输出历史很长，翻得过来
VS Code 终端对比度	minimumContrastRatio: 1	确保 pi 主题色准确

在 VS Code 的 settings.json 里加：

{
  "terminal.integrated.minimumContrastRatio": 1,
  "terminal.integrated.fontFamily": "JetBrains Mono",
  "terminal.integrated.fontSize": 13
}

---

这一章覆盖了四个主流平台的安装要点和三种容器化方案。大多数场景下——macOS 上用 iTerm2、Linux 服务器上用 tmux、Windows 上优先考虑 WSL2、手机上应急用 Termux——各取所需就行。

下一章要讲一个更有意思的话题：不联网、不用 API Key，在你自己的机器上跑本地模型。