AiPy 怎么安装？客户端、信创系统、命令行版三条路分别怎么走

搜「AiPy 怎么装」的人，十有八九会在第一步就卡住：官网给的是一个客户端安装包，GitHub 上给的却是 pip install aipyapp，两边看起来是两个东西。它们确实是两个东西——先把这一步分清楚，后面的路才不会走岔。

一、先分清你要装的是哪一个

官方 FAQ 里把这件事说得很直白：AiPy 是这个项目的开源引擎，适合极客使用；AiPy Pro 是面向普通用户的客户端版本，对不懂技术的人更易用。

落到安装方式上就是两条完全不同的路：

• AiPy Pro（客户端）：从官网下载对应操作系统的安装包，双击安装，像装任何一个桌面软件那样。适配 Windows、Mac，以及国产信创操作系统。
• 开源引擎 aipyapp（命令行）：走 Python 生态，pip install aipyapp 装好后用 aipy 命令启动。官方明确说它可以部署在服务器上——这是客户端做不到的场景。

如果你的目标是「在自己电脑上有个能干活的助手」，装客户端；如果你的目标是「放一台云主机上让它 7×24 跑」，走命令行版。两者不冲突，都装也可以。

二、Windows / Mac 客户端怎么装

官方给的下载地址是官网首页 https://www.aipyaipy.com/（海外站是 https://www.aipy.app/），进去按自己的系统选对应版本。这里有个容易选错的地方：Mac 分 Apple 芯片版和 Intel 芯片版。官方给的判断方法是点屏幕左上角苹果图标，在下拉菜单里选「关于本机」查看芯片类型，确认是 Intel 还是 Apple 芯片之后再下载。选错了装不上，白折腾一轮。

Windows 侧官方标注支持 Windows 10 及以上版本。

安装过程本身没有特别之处，按安装程序的页面提示逐步选择安装路径、确认即可，体验和常规客户端软件一致。但安装路径这一步建议你多想三秒——后面会讲到，装到某些目录里会埋雷。

装完第一次打开，会先进一个登录页面，可以用手机验证码或者微信扫码登录，首次登录会自动注册成一个新账号。登录成功之后，客户端会自动运行初始化环境——这一步是在本机准备 AiPy 干活要用的运行环境，需要一点时间，别以为卡死了就强退。

初始化完成之后进入控制台页面，这时可以选显示模式：窗口模式更日常，玄幻模式更炫酷。这只是外观，随时能在设置里换。

三、初始化失败了怎么办

这是客户端安装阶段最高频的一个坎，官方手册给了明确的处理办法：删掉运行环境目录再重启客户端。

Windows 上这个目录是：

C:\Users\<你的电脑用户名>\AppData\Roaming\aipy-pro\venv

看目录名就明白了——venv，它就是一个 Python 虚拟环境。初始化失败通常意味着这个虚拟环境建到一半坏掉了，删掉让客户端重新建一次，多数情况能过。

如果删了还不行，客户端的**【设置】-【运行环境】-【重置运行环境】是同一个思路的官方入口：它会删除并重新安装 AiPy 的运行环境，但不会删除历史任务**。这个功能官方标注的适用场景是「使用 AiPy 时出现发送消息后无响应、不回复的情况」，和初始化失败是同一类问题。

四、国产信创系统（以统信为例）

信创版有一个绕不开的额外步骤，不知道的话会直接卡死在「无法运行」。

第一步是确认 CPU 架构。 官方手册写明，官网上的信创版安装包支持 x86_64 架构的 CPU。查法很简单，按 Ctrl + Alt + T 调出终端，敲：

uname -m

回显 x86_64 就可以装。

第二步下载安装包，用浏览器访问官网下载 Linux 信创版，下载完双击运行。如果提示需要添加权限，点添加或者运行。

第三步是那个坎：点运行之后会弹出「没有通过系统安全验证，无法运行」。这时点弹窗里的「前往」按钮，在弹出的安全工具中选择「允许任意应用」，会有一个安全警告提示，点击阅读并同意，再点确认，输入电脑密码，就设置好了。

官方对这个提示做了解释，我原样转述：这是统信系统的签名验证不通过导致的，AiPy 目前是第三方应用程序，没有上架统信官方应用商店、没有统信的签名，这并不代表 AiPy 存在安全风险。

这句话值得你自己掂量一下。「关闭系统签名验证」是一个会降低整机安全基线的操作，它影响的不只是 AiPy 一个程序，而是之后所有未签名应用都能跑。官方的说法是合理的技术解释，但要不要放开这个开关，是你自己的安全决策，尤其在办公电脑或者涉密环境里。

五、Linux 服务器上装开源命令行版

这条路是给「想让它一直在线」的人准备的。官方手册里给了一套完整流程，核心难点其实只有一个：服务器自带的 Python 版本往往太低。

5.1 先看 Python 版本

python -V

最低要求是 Python 3.11。 官方 FAQ（2026-08-24 快照）的原话是「命令行开源版本支持，需要你的系统安装了 Python3.11 及以上，然后运行命令 pip install aipyapp 安装，aipy 命令启动」；官方使用指南在服务器安装那一节也标了同一条线——「aipy 运行最低要求：Python 3.11 及以上」，同时推荐用 Python 3.12。

这是个稳定前提，但毕竟会随大版本调整，装之前顺手回官网 FAQ 扫一眼更稳妥。

很多云主机镜像自带的 Python 明显低于这条线——官方手册里举的例子就是一台自带 Python 3.6.8 的服务器，手册直接写明「这个版本太低了，无法安装 aipy」。所以先看清楚自己手里是什么版本，再决定要不要折腾下一步。

5.2 版本太低就装一个新的，但别覆盖旧的

这一段是整个流程里最容易把服务器搞坏的地方，官方手册的思路是新旧共存，不动系统自带的那个。

先看发行版：

cat /etc/os-release

注意手册的适用范围声明：下面这套编译安装步骤仅适用于 ID_LIKE 那一行包含 rhel 或 fedora 或 centos 的发行版。不是这一类的话，别硬套。

装编译工具链和依赖库：

dnf groupinstall "Development Tools" -y
dnf install -y openssl-devel bzip2-devel libffi-devel \
  zlib-devel readline-devel sqlite-devel \
  xz-devel tk-devel gdbm-devel ncurses-devel

下载 Python 源码解压后，配置编译参数：

./configure \
  --prefix=/usr/local \
  --enable-optimizations \
  --enable-shared \
  --with-ssl \
  --with-ensurepip=install \
  LDFLAGS="-Wl,-rpath /usr/local/lib"

手册对每个参数都给了解释，挑几个关键的说：--prefix=/usr/local 让新 Python 装到 /usr/local/bin，和系统自带的 /usr/bin/python3 互不干扰；--with-ssl 保证 SSL/TLS 支持编译进去，pip 装包、requests 发 HTTPS 请求都靠它，漏了后面全是坑；--enable-shared 会编译出共享库，代价是运行时得让系统能找到它。

然后编译安装：

make -j$(nproc)
make altinstall

make altinstall 是这一步的命门。 手册特意标了「关键」：make install 会覆盖 /usr/local/bin/python3 这个软链接，而 altinstall 只创建带版本号的可执行文件，不碰任何已有链接。这一个单词的差别，决定了系统原来的 Python 会不会被你搞坏。

因为开了 --enable-shared，还要告诉系统去哪找共享库：

echo "/usr/local/lib" > /etc/ld.so.conf.d/python-new.conf
ldconfig

手册说明这个配置文件名随意，方便识别即可。

5.3 配 pip 国内镜像

官方手册的原话是，pip 默认从官方源下载，国内访问很慢。建议先 pip config list 看看当前源，如果还是官方源就换掉：

mkdir -p ~/.pip
cat > ~/.pip/pip.conf << 'EOF'
[global]
index-url = https://mirrors.aliyun.com/pypi/simple/
trusted-host = mirrors.aliyun.com
EOF

手册还列了清华、华为云、腾讯云的备选镜像，其中腾讯云的地址是 https://mirrors.cloud.tencent.com/pypi/simple/。

5.4 建虚拟环境再装

mkdir -p /opt/myproject
cd /opt/myproject
# python3.12 换成你刚装的那个可执行文件名（手册推荐 3.12，最低 3.11）
python3.12 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install aipyapp
pip show aipyapp

手册在这里插了一条加粗警告，值得原样搬过来：很多人踩坑，没激活虚拟环境就直接 pip install，结果包装到了全局 Python 里。 每次打开新终端窗口，都要先 cd 到项目目录，再 source venv/bin/activate。终端提示符前面出现 (venv) 才算激活成功。

六、装完第一次跑：语言、授权、会话提示符

语言。 手册提到，进 aipy 交互窗口后如果显示的是英文选项，需要改语言设置。先 Ctrl+C 退出，然后：

deactivate
cd ~/.aipyapp/
echo 'lang="zh"' >> aipyapp.toml
cat aipyapp.toml

确认写入后再回虚拟环境运行 aipy。

授权。 选择 Trustoken 的 API Key 之后会弹出一个授权链接。手册特意说明：如果本地没有浏览器，这个链接不是必须在安装 aipy 的服务器上访问，在任何有浏览器的设备上打开都行。这一条对纯命令行的云主机很关键，不知道的话会以为流程走不下去。访问后用手机号或微信扫码登录，没账号会自动注册，然后点授权。

提示符。 这是开源版一个很实用的细节：命令行前面显示 >>>（三个大于号）说明当前仍在之前的任务会话中，保留了之前对话的上下文记忆；要执行无关的新任务，按 Ctrl+C 结束当前会话，提示符变成 >> 就是新会话了。任务串味、AI 老是提上一件事，多半就是没注意这个符号。

如果你只是想在本机快速试一下，README 里给的最小配置更简单——在 ~/.aipyapp/aipyapp.toml 里写一段 [llm.xxx] 配上 type 和 api_key 就能跑。开源版默认是任务模式，加 --python 参数可以切到 Python 模式。

七、装的时候顺手避开的几个坑

• 安装目录别选 C:\Program Files\。 官方排查建议里明确提到，这是 Windows 的系统保护目录，普通用户权限无法直接写入文件，装在这里可能导致任务发出去没反应。
• 工作目录要改到安装目录以外。 设置里的工作目录是任务产物的落脚点，官方要求改成安装目录之外的路径，且修改后在新建的任务中才生效。
• 别急着开代理。 如果装完发消息没回应，官方排查清单里有一条就是关掉 VPN 代理再试。确实需要走代理的（企业内网、校园网），客户端【设置】-【运行环境】里有独立的代理设置。

装完之后接下来该配什么、遇到报错怎么查，可以接着看 AiPy 发任务没反应、初始化失败怎么办 和 AiPy 智能体集市怎么用。还在纠结装哪个版本的，AiPy 开源版和 AiPy Pro 有什么区别 那篇把两边的能力边界列了个对照。

核实边界

本文依据 2026-08-24 抓取的以下官方内容写成：AiPy 中国官网 https://www.aipyaipy.com/ 及其官方使用指南 https://www.aipyaipy.com/manual/、官方常见问题页 https://www.aipyaipy.com/faq.html、海外站 https://www.aipy.app/ 与 https://www.aipy.app/faq.html，以及开源引擎仓库 https://github.com/knownsec/aipyapp 的 README。

文中的最低 Python 版本（3.11）取自当日快照的官方 FAQ 与官方使用指南，两处一致；推荐版本（3.12）取自使用指南。这类要求会随大版本调整，动手前建议回官网复核一眼。

没核到、因此本文没写的部分：客户端版本号、各版本安装包的体积与校验值；Mac 与麒麟系统上是否有和统信类似的签名放行步骤（手册只详述了统信）。本文所有步骤均来自官方文档转述与源码阅读，作者没有实际安装运行过 AiPy，界面细节以你机器上的实际情况为准。