跳到主要内容
feedback
feedback

Pi

Pi（Pi Coding Agent）是一款在终端中运行的 AI 编程助手。它可以读取、编辑和创建项目文件，也可以在你的确认下执行终端命令。本文介绍 Pi 的安装、模力方舟 API 配置与基础使用。

模力方舟提供 OpenAI 兼容接口，可在 Pi 中配置编码模型，享受更优质的中文支持和更低的调用成本。

安装 Pi​

Pi 官方提供安装脚本和 npm、pnpm、Bun 等包管理器安装方式。使用包管理器安装时，请确保 Node.js 版本不低于 22.19.0，建议使用 Node.js LTS 版本。

macOS / Linux / WSL​

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

Windows PowerShell​

powershell -c "irm https://pi.dev/install.ps1 | iex"

验证 Pi 安装​

安装完成后，验证命令是否可用：

pi --version
pi --help

若能分别看到版本号和帮助信息，说明安装完成。

如果终端提示找不到 pi，请关闭并重新打开终端，使 npm 的全局命令目录重新加载到 PATH 中。

Windows Bash 配置​

Pi 的 bash 工具使用 Bash 语法执行命令。Windows 用户如需使用该工具，请安装 Git for Windows 提供的 Git Bash，并在 Git Bash 中验证：

bash --version

Pi 会自动查找默认位置的 Git Bash。若 Git 安装在自定义路径，可以在 %USERPROFILE%\.pi\agent\settings.json 中指定 Bash 路径，例如：

{
  "shellPath": "E:\\Git\\Git\\bin\\bash.exe"
}

将示例路径替换为自己电脑上 bash.exe 的实际位置。

获取访问令牌​

访问 工作台 -> 设置 -> 访问令牌 获取访问令牌。没有购买 Serverless API 的开发者，可以使用免费体验访问令牌（仅供体验，每日调用次数有限）。复制要使用的令牌，稍后填入 Pi 配置文件。

访问令牌页面

配置 Pi​

使用 CC Switch 自动配置（推荐）​

CC-Switch 是社区开源的桌面 GUI，可集中管理多个 AI 编程工具的服务商与模型配置，并在多套 API Key 或计费方案之间一键切换，无需手动修改 Pi 的配置文件。

如果已安装 CC-Switch，可以通过它的界面自动写入 Pi 的模型配置文件，无需手动编辑 models.json。请使用支持 Pi 的 CC-Switch v3.20.0 或更高版本。

  1. 打开 CC-Switch，在顶部应用列表中选择 Pi。

    CC-Switch 选择 Pi 应用

  2. 点击添加供应商，选择 自定义配置。供应商信息、API Key、请求地址和模型参数的填写方式，请参阅 CC Switch 快速配置；Pi 的请求地址、上游格式和模型参数，可通过 工具配置参考 快速获取。

  3. 保存并启用配置。CC-Switch 会自动写入 Pi 的模型配置文件。

  4. 启动 Pi，输入 /model，选择 deepseek-v4-flash-0731。

手动添加模型配置​

Pi 通过 models.json 配置自定义模型服务（Pi 不会自动创建，需要手动创建）。创建或编辑下列文件：

  • macOS / Linux：~/.pi/agent/models.json
  • Windows：%USERPROFILE%\.pi\agent\models.json

写入以下配置（这里用模力方舟的 deepseek-v4-flash-0731 模型作为示例）：

{
  "providers": {
    "moark": {
      "baseUrl": "https://ai.gitee.com/v1",
      "api": "openai-completions",
      "apiKey": "你的 API 密钥",
      "authHeader": true,
      "headers": {
        "X-Failover-Enabled": "true"
      },
      "models": [
        {
          "id": "deepseek-v4-flash-0731",
          "name": "DeepSeek-V4-Flash-0731（模力方舟）"
        }
      ]
    }
  }
}
将“你的 API 密钥”替换为上一步获取的实际访问令牌。请妥善保管该文件，不要将访问令牌提交到代码仓库或分享给他人。

Pi 会在打开模型选择器时读取此文件。配置完成后，启动 Pi 并输入 /model，选择你要使用的模型。

Pi 模型选择

使用其他服务商​

在 Pi 中输入 /login 后，可以选择以下两种认证方式：

  • 订阅服务：选择订阅登录选项，按界面提示在浏览器中完成服务商账号授权。
  • API Key 服务：选择 API Key 选项，并在列表中选择要使用的服务商。

以 DeepSeek API Key 为例：

  1. 输入 /login，选择 Use an API key。
  2. 在服务商列表中选择 DeepSeek。
  3. 按提示粘贴你的 DeepSeek API Key 并确认保存。

完成认证后，输入 /model，从 DeepSeek 的可用模型中选择本次会话使用的模型。

这里的 DeepSeek 仅作为 Pi 内置 API Key 服务商的示例，与前文通过 models.json 配置的模力方舟模型相互独立。

开始使用 Pi​

进入希望让 Pi 协助处理的项目目录：

cd path/to/your-project
pi

常用交互命令：

命令用途
/login登录或管理模型服务凭据
/model选择或切换模型
/new创建新的会话
/session查看当前会话的文件、消息数、Token 用量和费用信息
/settings调整主题、思考等级等设置

更多命令说明请参见 Pi Coding Agent README 中的官方命令列表。

更多资源​

Copyright © 2026 模力方舟京ICP备2025119063号京公网安备11011502039387号京公网安备11011502039387号