macOS：Pi

Pi 是终端里的极简 AI 编程助手，核心小巧、可高度自定义。它通过 models.json 声明自定义模型服务商，本页按步骤在 macOS 上完成悠然 AI 接入。

第 1 步：安装 Pi

打开终端，使用 npm 全局安装：

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

也可以使用官方安装脚本：

curl -fsSL https://pi.dev/install.sh | sh

安装完成后运行 pi --version 验证。详细说明见 Pi 官方文档。

第 2 步：保存 API Key 到环境变量

在终端执行（替换为真实 Key），写入 ~/.zshrc 并立即生效：

cat >> ~/.zshrc <<'EOF'
export YOURAN_API_KEY="<YOURAN_API_KEY>"
EOF

source ~/.zshrc

这样 Pi 的配置文件只需引用变量名，Key 不会写进配置文件。

第 3 步：写入 models.json

打开（或新建）配置文件 ~/.pi/agent/models.json，写入：

{
"providers": {
  "youran": {
    "baseUrl": "https://youran-ai.du-fu.com/v1",
    "api": "openai-completions",
    "apiKey": "$YOURAN_API_KEY",
    "models": [
      { "id": "gpt-5.6-sol", "reasoning": true },
      { "id": "gpt-5.6-terra", "reasoning": true },
      { "id": "gpt-5.6-luna", "reasoning": true }
    ]
  }
}
}

说明：

apiKey 里的 $YOURAN_API_KEY 会在运行时读取第 2 步设置的环境变量。
api 也可以改成 openai-responses（悠然 AI 两种协议都支持），openai-completions 兼容性最好。
三个模型的 reasoning: true 让 Pi 显示思考强度档位；不需要时可整行删除。
models.json 每次打开 /model 时自动重载，改完不用重启 Pi。

第 4 步：验证

pi --provider youran --model gpt-5.6-terra -p "请只回复：连接成功"

或者运行 pi 进入交互模式，输入 /model，在 youran 分组下选择模型后对话。

遇到连接问题时，先确认 echo $YOURAN_API_KEY 在当前终端可见，再前往故障排查。