之前帮团队搭开发环境时发现不少同学都卡在同一个环节机器上只有 Ubuntu 命令行没有桌面图形界面却急着要把 Pi 这类编码代理工具跑起来。网上教程要么只讲了 Windows 带界面的装法要么直接跳过了依赖准备导致跟着操作到一半就报错。这篇文章就专门解决这个问题。我会带你用纯终端方式在 Ubuntu 本地把 Pi 装好并跑起来全程不需要图形界面复制命令就能操作。无论你是刚接触 Linux 的新手还是已经在用 Vim 或 Tmux 的老手按这套流程走完都能得到一个可正常使用的 Pi 环境。先说明一下这里的 Pi 指的是一款运行在终端里的编码代理Coding Agent工具它能在命令行环境中帮你完成代码生成、指令执行、文件修改等任务。它和 Codex、OpenCode 一样都属于“把 AI 编程能力放进终端”的这类工具。文章里涉及的版本信息我会以当前常见环境为例具体细节请按你的实际版本调整。1. Pi 是什么为什么适合在 Ubuntu 终端中使用1.1 Pi 的核心定位Pi 的定位是一款面向终端环境的个性化编码代理。你可以把它理解成在命令行里有一个 AI 助手你给它一个自然语言任务比如“帮我写一个 Python 脚本读取 CSV 文件”它会在终端里分析任务、生成代码、执行命令并给出结果反馈。这种工具和普通聊天机器人的区别在于能感知当前工作目录的文件结构。能执行终端命令。能读取和修改项目文件。能根据执行结果一步步调整方案。简单来说它不是在“聊天”而是在“干活”。从工程角度看Pi 适合在 Ubuntu 服务器、云主机、Docker 容器这类没有图形界面的环境里使用这也是它比较大的优势。1.2 终端交互模式的优势很多开发者第一次接触编码代理时习惯用 Web 页面或者桌面客户端。但 Pi 这类终端工具在 Ubuntu 环境里更有优势资源占用低。终端工具没有浏览器渲染开销在低配云主机上也能流畅运行。和 SSH 工作流天然契合。你通过 SSH 登录远程主机后直接在终端里就能使用 Pi不需要额外转发图形界面。能直接操作文件系统。Pi 可以在当前目录下创建、修改、删除文件这对项目工程化很有帮助。可脚本化。你可以把 Pi 的命令集成到 Shell 脚本中实现半自动化的开发流程。1.3 与同类工具的关系如果你之前关注过 Codex、OpenCode 等工具可能会好奇它们之间的区别。这里需要明确一点这一大类工具都还处于快速迭代阶段各自的功能边界也在不断调整。有的侧重代码生成有的侧重自主执行长任务有的则更像一个可编程的终端助手。Pi 的典型特点是强调“自适应编码代理”和“个性化专属智能”。具体到实际使用中它更关注跟随用户的编码习惯。在复杂项目环境中自主规划任务。与当前终端会话深度绑定。在后续演示中我们会把重点放在通用安装流程和终端使用方法上而不是纠结于某个工具的私有功能。因为这类工具的命令结构和配置方式变化较快掌握通用思路比死记命令更重要。2. 环境准备Ubuntu 与终端基础2.1 系统与网络要求本文以 Ubuntu 系统为例。不管你是 Ubuntu 22.04 LTS 还是更新版本下面的命令基本都能直接使用。如果你的系统是 Ubuntu 20.04也没有问题但个别依赖包版本可能偏旧建议先执行一次系统更新。必备清单如下项目要求操作系统Ubuntu 20.04 / 22.04 / 24.04 或更新版本架构x86_64 或 arm64Python3.9 以上版本网络能访问 Pi 官方资源地址终端Bash、Zsh 均可磁盘空间至少 2GB 可用空间如果你的 Ubuntu 是刚装好的最小化系统没有图形界面甚至还没有安装 curl、git 等基础工具也没关系下面会一步步带你把环境补齐。2.2 打开终端的方式既然要求“全程不用图形界面”意味着你大概率是通过 SSH 远程连接到 Ubuntu 主机。我在写这篇教程时的环境就是一台无桌面版 Ubuntu 服务器整个安装过程只用到了 SSH 终端。在终端里执行以下命令先确认系统版本和架构lsb_release -a 2/dev/null || cat /etc/os-release uname -m第一条命令查看 Ubuntu 发行版本第二条命令查看 CPU 架构。x86_64 表示 64 位 Intel/AMD 架构aarch64 表示 64 位 ARM 架构。记录下结果后面安装依赖时会用到。如果你是在本地虚拟机里操作可以使用 VMware 安装 Ubuntu 后进入纯命令行模式也可以按 Ctrl Alt F3 切换到 TTY 终端这种模式下同样没有图形界面操作原理和 SSH 一致。2.3 基础工具检查Ubuntu 最小化安装通常自带 Python3但可能缺少 curl、git、vim 等工具。不急着安装 Pi先把基础依赖补全sudo apt update sudo apt install -y curl git vim build-essential这里简单解释每条命令的作用apt update更新软件源索引让 apt 知道有哪些可用软件包。curl用于下载 Pi 安装脚本或后续需要拉取的文件。git某些安装脚本会通过 git 拉取仓库提前装好避免中断。vim纯终端环境下的文本编辑器用于修改配置文件。build-essential包含编译工具链部分 Python 包需要本地编译。执行完后再确认 Python 版本python3 --version如果输出类似Python 3.10.12说明 Python 环境可用。如果提示找不到 python3说明系统没有安装 Python需要先安装sudo apt install -y python3 python3-pip python3-venv到这里安装 Pi 之前的环境准备工作就完成了。3. 终端复用工具 tmux不打开图形界面的多窗口方案3.1 为什么需要 tmux在纯终端环境里有一个很常见的问题你正在终端里执行一个长时间任务比如 Pi 正在循环处理多个文件这时候 SSH 连接突然断开任务就会中断。又或者你想同时打开两个终端窗口一个跑 Pi一个看日志但没有图形界面时普通终端做不到这种多窗口效果。tmux 就是解决这个问题的终端复用工具。它允许你在一个终端窗口里创建多个会话并且让这些会话在后台保持运行即使 SSH 断开了任务也不会停。用到 Pi 时tmux 有两个比较实用的价值把 Pi 放在一个独立的 tmux 会话中运行即使关闭 SSH 窗口Pi 的任务仍然继续。可以分屏操作左边跑 Pi右边看日志或编辑文件。3.2 安装 tmuxUbuntu 下安装 tmux 非常简单sudo apt install -y tmux安装完成后通过下面的命令创建一个新的 tmux 会话tmux new -s piwork这条命令会创建一个名为 piwork 的会话。你会发现在终端底部出现了一个绿色的状态栏这说明你已经进入了 tmux 环境。离开这个会话可以使用# 先按 Ctrl b然后按 d这样会 detach脱离当前会话但会话本身还在后台运行。重新进入这个会话使用tmux attach -t piwork如果不再需要某个会话可以杀掉它tmux kill-session -t piwork3.3 tmux 常用命令速查命令功能tmux new -s 名称创建并进入一个新会话tmux attach -t 名称重新连接指定会话tmux ls查看所有会话列表Ctrl b然后按d脱离当前会话Ctrl b然后按%左右分屏Ctrl b然后按上下分屏Ctrl b然后按方向键切换分屏焦点exit或者Ctrl d关闭当前窗格在安装 Pi 之前先掌握 tmux能让你后续操作顺畅很多。如果你是在自己的 Ubuntu 桌面上操作也可以直接打开多个终端窗口但如果你通过 SSH 管理远程服务器tmux 基本是必备工具。4. 安装 Pi 的完整终端流程4.1 获取安装入口现在进入核心步骤安装 Pi。由于 Pi 这类工具迭代很快安装命令和下载地址可能随版本变化。稳妥的方式是先去 Pi 的官方文档或官方仓库确认最新安装命令。通常这类工具的安装方式主要有三种官方一键安装脚本curl 管道方式。通过 npm 或 pip 等包管理器安装。通过 git clone 源码后本地构建。以“官网提供安装脚本”这一通用形式为例安装思路通常如下# 进入一个临时目录方便清理下载文件 cd /tmp # 下载官方安装脚本具体地址请以官方文档为准 curl -fsSL 安装脚本地址 -o install_pi.sh # 查看脚本内容确认没有危险操作 less install_pi.sh # 执行安装 bash install_pi.sh这里需要特别强调下载第三方脚本后先查看内容再执行是一个很好的安全习惯。你可以用less命令翻页查看脚本内容确认脚本在做什么操作。如果脚本中包含明显可疑的命令请立即停止执行不要盲目把未知脚本跑在服务器上。如果你是通过 npm 方式安装则命令格式通常为npm install -g pi/cli如果你是通过 pip 方式安装则可能是pip3 install pi-agent以上两种命令仅为常见模式的示例具体包名需要以官方发布的为准。我在自己的服务器上安装时就是先通过官网确认了当前的安装方式再执行对应命令整个过程不到 5 分钟。4.2 执行安装无论你使用哪种方式安装完成之后都需要验证安装结果。在终端里执行pi --version如果能输出版本号说明安装成功。如果提示pi: command not found原因通常是安装目录不在当前用户的 PATH 环境变量中。对于 npm 全局安装的情况可以通过npm prefix -g命令查看全局安装路径然后把路径加入.bashrcecho export PATH$(npm prefix -g)/bin:$PATH ~/.bashrc source ~/.bashrc对于 pip 安装的情况可以用python3 -m pip show查看包信息确认安装位置后再决定是否调整环境变量。4.3 初始化与认证安装完成后第一次使用 Pi 通常需要进行初始化。初始化流程可能包括选择模型的接入方式例如 API Key 或本地模型。确认默认的工作目录。配置个性化偏好。以 API Key 方式为例你需要在官方平台创建自己的密钥然后在终端中写入配置文件。配置文件通常位于~/.pi/目录下。如果没有这个目录可以手动创建mkdir -p ~/.pi vim ~/.pi/config.json在配置文件中写入类似下面的内容{ api_key: 你的API密钥, model: 默认模型名, work_dir: . }注意这只是配置文件的一种常见结构具体有哪些字段、模型名怎么填写请以你拿到的工具版本为准。不要照抄这里的字段否则可能无法正常启动。初始化过程中如果工具提供了pi init或pi setup命令优先使用这类官方命令完成配置因为它会引导你一步步填写必要信息比手动写配置文件更不容易出错。4.4 验证安装结果初始化完成后启动 Pi 的交互式界面pi正常情况下终端会显示交互式命令行提示符等待你输入任务描述。输入“你好”或者“帮助”看看能否收到回复。如果你的终端中文显示乱码可以在终端中设置 UTF-8 编码export LANGen_US.UTF-8或者安装中文字体sudo apt install -y fonts-noto-cjk到这里Pi 在 Ubuntu 本地就安装好了并且全程没有打开任何图形界面。5. Pi 的基础使用演示5.1 打开交互式会话Pi 安装好之后最基础的使用方式就是打开交互式会话。在终端中输入pi此时你进入了类似 Shell 的交互环境但这里接收的是自然语言指令而不是 Linux 命令。如果当前项目目录比较复杂建议先切换到你希望 Pi 工作的目录再启动 Pi。例如cd ~/work/myproject pi这样 Pi 创建的文件、修改的代码都会落在当前项目目录里逻辑更清晰。5.2 第一个任务让 Pi 创建一个 Python 脚本下面用一个简单例子演示 Pi 的使用方式。假设你想让 Pi 写一个脚本读取当前目录下的一个 CSV 文件并把数据按行打印出来。在 Pi 的交互提示符下输入请在当前目录创建一个 read_csv.py 脚本使用 Python 读取 data.csv 文件并打印每一行内容。这时Pi 会分析你的请求如果它支持终端命令执行可能会直接帮你创建文件并写入代码。如果它只返回代码示例你可以要求它“把代码写入文件”。得到文件后退出 Pi在普通终端中执行python3 read_csv.py如果你的目录下还没有 data.csv可以使用下面的命令创建测试数据echo name,age,city data.csv echo Alice,25,Beijing data.csv echo Bob,30,Shanghai data.csv再运行脚本你会看到 CSV 文件的内容被按行打印出来。5.3 会话管理技巧在 Pi 的交互环境中有一些通用操作需要留意输入exit或quit退出交互环境。输入clear清空当前终端显示。按Ctrl C中断当前正在执行的任务而不是退出 Pi。如果你想要多个任务并行可以借助之前安装的 tmux 创建多个会话每个会话独立运行一个 Pi 实例。例如# 会话1写代码 tmux new -s pi-code # 会话2查日志 tmux new -s pi-log这样就能在同一个 SSH 窗口内完成多任务管理不需要打开新的图形终端窗口。6. 常见问题与排查思路在实际安装过程中难免会遇到各种问题。这里整理了纯终端环境下最常见的几种情况按“问题现象 - 原因 - 解决思路”整理成表格方便查阅。问题现象常见原因解决思路pi: command not found安装目录不在 PATH 中检查安装路径将 bin 目录加入~/.bashrc启动 Pi 后提示缺少 Python 依赖Python 环境不完整安装 python3-venv 和 pip重新安装依赖安装脚本执行到一半中断网络原因或依赖下载失败重新执行安装或配置镜像源后重试终端显示乱码缺少中文字体或编码不对设置 UTF-8 编码安装 fonts-noto-cjktmux 会话丢失服务器重启使用 tmux new -s 时会话不会开机自启需配合开机脚本任务执行时 SSH 断开网络波动务必在 tmux 中运行 Pi重连后 attach 恢复镜像下载速度慢网络问题使用 mirror 加速或更换网络环境6.1 pi 命令找不到的详细处理这是出现频率比较高的问题。安装完成但没有报错结果一执行pi就提示找不到。处理流程如下# 1. 确认 pi 安装在哪里 which pi 2/dev/null # 如果没有结果执行 ls -la ~/.local/bin/pi 2/dev/null ls -la ~/.npm-global/bin/pi 2/dev/null # 2. 查看 PATH 变量 echo $PATH # 3. 根据找到的路径向 .bashrc 添加内容 echo export PATH$HOME/.local/bin:$PATH ~/.bashrc source ~/.bashrc如果是通过 npm 安装的并且你配置了自定义全局目录需要把对应路径加进去。6.2 Python 依赖问题的处理Pi 这类工具通常依赖多个 Python 包。报错信息如果提示ModuleNotFoundError说明某个依赖没有安装成功。在纯终端环境下建议使用虚拟环境来隔离依赖避免和系统 Python 环境互相污染cd ~ python3 -m venv pi-env source pi-env/bin/activate pip3 install 缺失的包名如果提示权限不足不要直接使用sudo pip正确的做法是在虚拟环境中安装或者使用pip3 install --user安装到个人目录。7. 最佳实践与工程建议7.1 工作目录规范使用 Pi 这类终端编码代理时最需要养成的习惯是“为每个项目创建独立目录”。不要直接在/root或/home用户主目录下随意使用 Pi因为这个目录下文件杂乱Pi 在分析项目结构时会受到干扰也容易误操作到无关文件。推荐结构如下~/work/ ├── project-a/ ├── project-b/ └── scripts/每次使用 Pi 前先进入对应项目目录cd ~/work/project-a pi7.2 配置管理Pi 的配置文件建议单独管理不要全部堆在用户主目录。如果你的 Pi 支持--config参数可以把配置文件放到项目目录的.pi/子目录中mkdir -p .pi vim .pi/config.json配置文件中涉及 API Key 的内容不要在团队内共享。如果不小心把密钥提交到了 Git 仓库应立刻撤销密钥并在官方平台重新生成。另外如果你管理多台 Ubuntu 服务器可以用 Ansible 或简单的 Shell 脚本同步配置模板但一定不要把密钥明文放在脚本里。可以使用环境变量注入的方式export PI_API_KEY你的密钥 pi配置文件里则使用占位符{ api_key: ${PI_API_KEY} }7.3 日志与任务记录Pi 在终端里执行的任务默认不会保留完整记录。如果想让每次交互都有迹可循推荐使用 tmux 的日志功能。在创建 tmux 会话之前先开启日志录制# 在 tmux 会话内执行 script -f ~/pi-logs/$(date %Y%m%d-%H%M%S).log这样终端的所有输出会同步写入日志文件方便后续排查问题和复盘。7.4 安全边界编码代理工具拥有修改文件和执行命令的能力这就意味着你必须注意安全边界。建议做到以下几点在测试环境充分验证 Pi 的指令准确性再用于生产环境项目。不要直接用 root 用户运行 Pi除非你十分清楚风险。执行 Pi 生成的 Shell 命令前先审查命令内容。敏感目录如/etc、/var不要作为 Pi 的工作目录。定期检查项目目录的变更使用 git status 查看修改记录。本质上Pi 再强大也只是辅助工具最终审查责任还在开发者身上。把它当成一个“很懂命令行的实习生”它的输出需要你复核这和你用 Codex、OpenCode 时的态度是一样的。8. 总结与后续学习方向这篇教程从 Ubuntu 终端环境的准备开始依次完成了基础工具安装、tmux 终端复用配置、Pi 的安装与初始化并通过一个简单的 Python 脚本演示了 Pi 的基本使用流程。全程没有打开图形界面适合远程服务器和最小化系统场景。你现在应该已经掌握在 Ubuntu 纯终端环境下安装基础依赖的流程。使用 tmux 管理多个终端会话的基本操作。通过官网确认 Pi 最新安装方式并完成部署。验证 Pi 安装结果和排查常见错误的方法。在实际项目中使用 Pi 时的路径规划和安全意识。下一步可以重点深入学习三块内容终端效率提升。熟练使用 tmux 分屏、vim 编辑、ripgrep 搜索文件这些工具组合使用后纯终端开发体验会非常顺手。编码代理的工程化用法。把 Pi 集成进自动化脚本、Git 提交前检查、代码生成流程中让它帮你处理重复性工作。多模型切换与个性化配置。当你不满足于默认模型时可以研究 Pi 的模型接入方式把本地模型或第三方模型接进来形成符合自己需求的专属开发环境。安装工具只是第一步真正的价值在于你如何把终端里的 AI 编码代理用在自己的日常开发流程里。建议你在清理干净的环境里再完整执行一遍安装流程不用多久就能形成肌肉记忆。第一次折腾可能花点时间但配置好后后续使用会顺畅很多。
纯终端环境安装 Pi 编码代理：Ubuntu 无图形界面部署全指南
之前帮团队搭开发环境时发现不少同学都卡在同一个环节机器上只有 Ubuntu 命令行没有桌面图形界面却急着要把 Pi 这类编码代理工具跑起来。网上教程要么只讲了 Windows 带界面的装法要么直接跳过了依赖准备导致跟着操作到一半就报错。这篇文章就专门解决这个问题。我会带你用纯终端方式在 Ubuntu 本地把 Pi 装好并跑起来全程不需要图形界面复制命令就能操作。无论你是刚接触 Linux 的新手还是已经在用 Vim 或 Tmux 的老手按这套流程走完都能得到一个可正常使用的 Pi 环境。先说明一下这里的 Pi 指的是一款运行在终端里的编码代理Coding Agent工具它能在命令行环境中帮你完成代码生成、指令执行、文件修改等任务。它和 Codex、OpenCode 一样都属于“把 AI 编程能力放进终端”的这类工具。文章里涉及的版本信息我会以当前常见环境为例具体细节请按你的实际版本调整。1. Pi 是什么为什么适合在 Ubuntu 终端中使用1.1 Pi 的核心定位Pi 的定位是一款面向终端环境的个性化编码代理。你可以把它理解成在命令行里有一个 AI 助手你给它一个自然语言任务比如“帮我写一个 Python 脚本读取 CSV 文件”它会在终端里分析任务、生成代码、执行命令并给出结果反馈。这种工具和普通聊天机器人的区别在于能感知当前工作目录的文件结构。能执行终端命令。能读取和修改项目文件。能根据执行结果一步步调整方案。简单来说它不是在“聊天”而是在“干活”。从工程角度看Pi 适合在 Ubuntu 服务器、云主机、Docker 容器这类没有图形界面的环境里使用这也是它比较大的优势。1.2 终端交互模式的优势很多开发者第一次接触编码代理时习惯用 Web 页面或者桌面客户端。但 Pi 这类终端工具在 Ubuntu 环境里更有优势资源占用低。终端工具没有浏览器渲染开销在低配云主机上也能流畅运行。和 SSH 工作流天然契合。你通过 SSH 登录远程主机后直接在终端里就能使用 Pi不需要额外转发图形界面。能直接操作文件系统。Pi 可以在当前目录下创建、修改、删除文件这对项目工程化很有帮助。可脚本化。你可以把 Pi 的命令集成到 Shell 脚本中实现半自动化的开发流程。1.3 与同类工具的关系如果你之前关注过 Codex、OpenCode 等工具可能会好奇它们之间的区别。这里需要明确一点这一大类工具都还处于快速迭代阶段各自的功能边界也在不断调整。有的侧重代码生成有的侧重自主执行长任务有的则更像一个可编程的终端助手。Pi 的典型特点是强调“自适应编码代理”和“个性化专属智能”。具体到实际使用中它更关注跟随用户的编码习惯。在复杂项目环境中自主规划任务。与当前终端会话深度绑定。在后续演示中我们会把重点放在通用安装流程和终端使用方法上而不是纠结于某个工具的私有功能。因为这类工具的命令结构和配置方式变化较快掌握通用思路比死记命令更重要。2. 环境准备Ubuntu 与终端基础2.1 系统与网络要求本文以 Ubuntu 系统为例。不管你是 Ubuntu 22.04 LTS 还是更新版本下面的命令基本都能直接使用。如果你的系统是 Ubuntu 20.04也没有问题但个别依赖包版本可能偏旧建议先执行一次系统更新。必备清单如下项目要求操作系统Ubuntu 20.04 / 22.04 / 24.04 或更新版本架构x86_64 或 arm64Python3.9 以上版本网络能访问 Pi 官方资源地址终端Bash、Zsh 均可磁盘空间至少 2GB 可用空间如果你的 Ubuntu 是刚装好的最小化系统没有图形界面甚至还没有安装 curl、git 等基础工具也没关系下面会一步步带你把环境补齐。2.2 打开终端的方式既然要求“全程不用图形界面”意味着你大概率是通过 SSH 远程连接到 Ubuntu 主机。我在写这篇教程时的环境就是一台无桌面版 Ubuntu 服务器整个安装过程只用到了 SSH 终端。在终端里执行以下命令先确认系统版本和架构lsb_release -a 2/dev/null || cat /etc/os-release uname -m第一条命令查看 Ubuntu 发行版本第二条命令查看 CPU 架构。x86_64 表示 64 位 Intel/AMD 架构aarch64 表示 64 位 ARM 架构。记录下结果后面安装依赖时会用到。如果你是在本地虚拟机里操作可以使用 VMware 安装 Ubuntu 后进入纯命令行模式也可以按 Ctrl Alt F3 切换到 TTY 终端这种模式下同样没有图形界面操作原理和 SSH 一致。2.3 基础工具检查Ubuntu 最小化安装通常自带 Python3但可能缺少 curl、git、vim 等工具。不急着安装 Pi先把基础依赖补全sudo apt update sudo apt install -y curl git vim build-essential这里简单解释每条命令的作用apt update更新软件源索引让 apt 知道有哪些可用软件包。curl用于下载 Pi 安装脚本或后续需要拉取的文件。git某些安装脚本会通过 git 拉取仓库提前装好避免中断。vim纯终端环境下的文本编辑器用于修改配置文件。build-essential包含编译工具链部分 Python 包需要本地编译。执行完后再确认 Python 版本python3 --version如果输出类似Python 3.10.12说明 Python 环境可用。如果提示找不到 python3说明系统没有安装 Python需要先安装sudo apt install -y python3 python3-pip python3-venv到这里安装 Pi 之前的环境准备工作就完成了。3. 终端复用工具 tmux不打开图形界面的多窗口方案3.1 为什么需要 tmux在纯终端环境里有一个很常见的问题你正在终端里执行一个长时间任务比如 Pi 正在循环处理多个文件这时候 SSH 连接突然断开任务就会中断。又或者你想同时打开两个终端窗口一个跑 Pi一个看日志但没有图形界面时普通终端做不到这种多窗口效果。tmux 就是解决这个问题的终端复用工具。它允许你在一个终端窗口里创建多个会话并且让这些会话在后台保持运行即使 SSH 断开了任务也不会停。用到 Pi 时tmux 有两个比较实用的价值把 Pi 放在一个独立的 tmux 会话中运行即使关闭 SSH 窗口Pi 的任务仍然继续。可以分屏操作左边跑 Pi右边看日志或编辑文件。3.2 安装 tmuxUbuntu 下安装 tmux 非常简单sudo apt install -y tmux安装完成后通过下面的命令创建一个新的 tmux 会话tmux new -s piwork这条命令会创建一个名为 piwork 的会话。你会发现在终端底部出现了一个绿色的状态栏这说明你已经进入了 tmux 环境。离开这个会话可以使用# 先按 Ctrl b然后按 d这样会 detach脱离当前会话但会话本身还在后台运行。重新进入这个会话使用tmux attach -t piwork如果不再需要某个会话可以杀掉它tmux kill-session -t piwork3.3 tmux 常用命令速查命令功能tmux new -s 名称创建并进入一个新会话tmux attach -t 名称重新连接指定会话tmux ls查看所有会话列表Ctrl b然后按d脱离当前会话Ctrl b然后按%左右分屏Ctrl b然后按上下分屏Ctrl b然后按方向键切换分屏焦点exit或者Ctrl d关闭当前窗格在安装 Pi 之前先掌握 tmux能让你后续操作顺畅很多。如果你是在自己的 Ubuntu 桌面上操作也可以直接打开多个终端窗口但如果你通过 SSH 管理远程服务器tmux 基本是必备工具。4. 安装 Pi 的完整终端流程4.1 获取安装入口现在进入核心步骤安装 Pi。由于 Pi 这类工具迭代很快安装命令和下载地址可能随版本变化。稳妥的方式是先去 Pi 的官方文档或官方仓库确认最新安装命令。通常这类工具的安装方式主要有三种官方一键安装脚本curl 管道方式。通过 npm 或 pip 等包管理器安装。通过 git clone 源码后本地构建。以“官网提供安装脚本”这一通用形式为例安装思路通常如下# 进入一个临时目录方便清理下载文件 cd /tmp # 下载官方安装脚本具体地址请以官方文档为准 curl -fsSL 安装脚本地址 -o install_pi.sh # 查看脚本内容确认没有危险操作 less install_pi.sh # 执行安装 bash install_pi.sh这里需要特别强调下载第三方脚本后先查看内容再执行是一个很好的安全习惯。你可以用less命令翻页查看脚本内容确认脚本在做什么操作。如果脚本中包含明显可疑的命令请立即停止执行不要盲目把未知脚本跑在服务器上。如果你是通过 npm 方式安装则命令格式通常为npm install -g pi/cli如果你是通过 pip 方式安装则可能是pip3 install pi-agent以上两种命令仅为常见模式的示例具体包名需要以官方发布的为准。我在自己的服务器上安装时就是先通过官网确认了当前的安装方式再执行对应命令整个过程不到 5 分钟。4.2 执行安装无论你使用哪种方式安装完成之后都需要验证安装结果。在终端里执行pi --version如果能输出版本号说明安装成功。如果提示pi: command not found原因通常是安装目录不在当前用户的 PATH 环境变量中。对于 npm 全局安装的情况可以通过npm prefix -g命令查看全局安装路径然后把路径加入.bashrcecho export PATH$(npm prefix -g)/bin:$PATH ~/.bashrc source ~/.bashrc对于 pip 安装的情况可以用python3 -m pip show查看包信息确认安装位置后再决定是否调整环境变量。4.3 初始化与认证安装完成后第一次使用 Pi 通常需要进行初始化。初始化流程可能包括选择模型的接入方式例如 API Key 或本地模型。确认默认的工作目录。配置个性化偏好。以 API Key 方式为例你需要在官方平台创建自己的密钥然后在终端中写入配置文件。配置文件通常位于~/.pi/目录下。如果没有这个目录可以手动创建mkdir -p ~/.pi vim ~/.pi/config.json在配置文件中写入类似下面的内容{ api_key: 你的API密钥, model: 默认模型名, work_dir: . }注意这只是配置文件的一种常见结构具体有哪些字段、模型名怎么填写请以你拿到的工具版本为准。不要照抄这里的字段否则可能无法正常启动。初始化过程中如果工具提供了pi init或pi setup命令优先使用这类官方命令完成配置因为它会引导你一步步填写必要信息比手动写配置文件更不容易出错。4.4 验证安装结果初始化完成后启动 Pi 的交互式界面pi正常情况下终端会显示交互式命令行提示符等待你输入任务描述。输入“你好”或者“帮助”看看能否收到回复。如果你的终端中文显示乱码可以在终端中设置 UTF-8 编码export LANGen_US.UTF-8或者安装中文字体sudo apt install -y fonts-noto-cjk到这里Pi 在 Ubuntu 本地就安装好了并且全程没有打开任何图形界面。5. Pi 的基础使用演示5.1 打开交互式会话Pi 安装好之后最基础的使用方式就是打开交互式会话。在终端中输入pi此时你进入了类似 Shell 的交互环境但这里接收的是自然语言指令而不是 Linux 命令。如果当前项目目录比较复杂建议先切换到你希望 Pi 工作的目录再启动 Pi。例如cd ~/work/myproject pi这样 Pi 创建的文件、修改的代码都会落在当前项目目录里逻辑更清晰。5.2 第一个任务让 Pi 创建一个 Python 脚本下面用一个简单例子演示 Pi 的使用方式。假设你想让 Pi 写一个脚本读取当前目录下的一个 CSV 文件并把数据按行打印出来。在 Pi 的交互提示符下输入请在当前目录创建一个 read_csv.py 脚本使用 Python 读取 data.csv 文件并打印每一行内容。这时Pi 会分析你的请求如果它支持终端命令执行可能会直接帮你创建文件并写入代码。如果它只返回代码示例你可以要求它“把代码写入文件”。得到文件后退出 Pi在普通终端中执行python3 read_csv.py如果你的目录下还没有 data.csv可以使用下面的命令创建测试数据echo name,age,city data.csv echo Alice,25,Beijing data.csv echo Bob,30,Shanghai data.csv再运行脚本你会看到 CSV 文件的内容被按行打印出来。5.3 会话管理技巧在 Pi 的交互环境中有一些通用操作需要留意输入exit或quit退出交互环境。输入clear清空当前终端显示。按Ctrl C中断当前正在执行的任务而不是退出 Pi。如果你想要多个任务并行可以借助之前安装的 tmux 创建多个会话每个会话独立运行一个 Pi 实例。例如# 会话1写代码 tmux new -s pi-code # 会话2查日志 tmux new -s pi-log这样就能在同一个 SSH 窗口内完成多任务管理不需要打开新的图形终端窗口。6. 常见问题与排查思路在实际安装过程中难免会遇到各种问题。这里整理了纯终端环境下最常见的几种情况按“问题现象 - 原因 - 解决思路”整理成表格方便查阅。问题现象常见原因解决思路pi: command not found安装目录不在 PATH 中检查安装路径将 bin 目录加入~/.bashrc启动 Pi 后提示缺少 Python 依赖Python 环境不完整安装 python3-venv 和 pip重新安装依赖安装脚本执行到一半中断网络原因或依赖下载失败重新执行安装或配置镜像源后重试终端显示乱码缺少中文字体或编码不对设置 UTF-8 编码安装 fonts-noto-cjktmux 会话丢失服务器重启使用 tmux new -s 时会话不会开机自启需配合开机脚本任务执行时 SSH 断开网络波动务必在 tmux 中运行 Pi重连后 attach 恢复镜像下载速度慢网络问题使用 mirror 加速或更换网络环境6.1 pi 命令找不到的详细处理这是出现频率比较高的问题。安装完成但没有报错结果一执行pi就提示找不到。处理流程如下# 1. 确认 pi 安装在哪里 which pi 2/dev/null # 如果没有结果执行 ls -la ~/.local/bin/pi 2/dev/null ls -la ~/.npm-global/bin/pi 2/dev/null # 2. 查看 PATH 变量 echo $PATH # 3. 根据找到的路径向 .bashrc 添加内容 echo export PATH$HOME/.local/bin:$PATH ~/.bashrc source ~/.bashrc如果是通过 npm 安装的并且你配置了自定义全局目录需要把对应路径加进去。6.2 Python 依赖问题的处理Pi 这类工具通常依赖多个 Python 包。报错信息如果提示ModuleNotFoundError说明某个依赖没有安装成功。在纯终端环境下建议使用虚拟环境来隔离依赖避免和系统 Python 环境互相污染cd ~ python3 -m venv pi-env source pi-env/bin/activate pip3 install 缺失的包名如果提示权限不足不要直接使用sudo pip正确的做法是在虚拟环境中安装或者使用pip3 install --user安装到个人目录。7. 最佳实践与工程建议7.1 工作目录规范使用 Pi 这类终端编码代理时最需要养成的习惯是“为每个项目创建独立目录”。不要直接在/root或/home用户主目录下随意使用 Pi因为这个目录下文件杂乱Pi 在分析项目结构时会受到干扰也容易误操作到无关文件。推荐结构如下~/work/ ├── project-a/ ├── project-b/ └── scripts/每次使用 Pi 前先进入对应项目目录cd ~/work/project-a pi7.2 配置管理Pi 的配置文件建议单独管理不要全部堆在用户主目录。如果你的 Pi 支持--config参数可以把配置文件放到项目目录的.pi/子目录中mkdir -p .pi vim .pi/config.json配置文件中涉及 API Key 的内容不要在团队内共享。如果不小心把密钥提交到了 Git 仓库应立刻撤销密钥并在官方平台重新生成。另外如果你管理多台 Ubuntu 服务器可以用 Ansible 或简单的 Shell 脚本同步配置模板但一定不要把密钥明文放在脚本里。可以使用环境变量注入的方式export PI_API_KEY你的密钥 pi配置文件里则使用占位符{ api_key: ${PI_API_KEY} }7.3 日志与任务记录Pi 在终端里执行的任务默认不会保留完整记录。如果想让每次交互都有迹可循推荐使用 tmux 的日志功能。在创建 tmux 会话之前先开启日志录制# 在 tmux 会话内执行 script -f ~/pi-logs/$(date %Y%m%d-%H%M%S).log这样终端的所有输出会同步写入日志文件方便后续排查问题和复盘。7.4 安全边界编码代理工具拥有修改文件和执行命令的能力这就意味着你必须注意安全边界。建议做到以下几点在测试环境充分验证 Pi 的指令准确性再用于生产环境项目。不要直接用 root 用户运行 Pi除非你十分清楚风险。执行 Pi 生成的 Shell 命令前先审查命令内容。敏感目录如/etc、/var不要作为 Pi 的工作目录。定期检查项目目录的变更使用 git status 查看修改记录。本质上Pi 再强大也只是辅助工具最终审查责任还在开发者身上。把它当成一个“很懂命令行的实习生”它的输出需要你复核这和你用 Codex、OpenCode 时的态度是一样的。8. 总结与后续学习方向这篇教程从 Ubuntu 终端环境的准备开始依次完成了基础工具安装、tmux 终端复用配置、Pi 的安装与初始化并通过一个简单的 Python 脚本演示了 Pi 的基本使用流程。全程没有打开图形界面适合远程服务器和最小化系统场景。你现在应该已经掌握在 Ubuntu 纯终端环境下安装基础依赖的流程。使用 tmux 管理多个终端会话的基本操作。通过官网确认 Pi 最新安装方式并完成部署。验证 Pi 安装结果和排查常见错误的方法。在实际项目中使用 Pi 时的路径规划和安全意识。下一步可以重点深入学习三块内容终端效率提升。熟练使用 tmux 分屏、vim 编辑、ripgrep 搜索文件这些工具组合使用后纯终端开发体验会非常顺手。编码代理的工程化用法。把 Pi 集成进自动化脚本、Git 提交前检查、代码生成流程中让它帮你处理重复性工作。多模型切换与个性化配置。当你不满足于默认模型时可以研究 Pi 的模型接入方式把本地模型或第三方模型接进来形成符合自己需求的专属开发环境。安装工具只是第一步真正的价值在于你如何把终端里的 AI 编码代理用在自己的日常开发流程里。建议你在清理干净的环境里再完整执行一遍安装流程不用多久就能形成肌肉记忆。第一次折腾可能花点时间但配置好后后续使用会顺畅很多。