AB
AB
AiBoss站

全部分类

教程

iFlow CLI

教程

安装并配置 iFlow CLI，在终端里跑通第一个 AI 编程任务

iFlow CLI 是一个跑在终端里的 AI 编程助手，能读代码、改文件、执行命令。本文从安装、三种登录方式的选择，到 /init 分析项目、生成脚本、用 ! 调用系统命令，给出可直接照做的步骤与命令，并整理常见故障的排查方法。

iFlow CLI 是一个运行在终端里的 AI 编程助手。它可以直接读取当前目录下的代码、执行编程任务、处理文件操作，也能通过斜杠命令、@ 文件引用、$ 子代理等机制控制行为。适合已经习惯命令行、希望在项目目录里直接让 AI 读代码和改代码的开发者。这篇教程讲清楚一件事：从零安装 iFlow CLI，完成登录配置，并在终端里跑通第一个 AI 辅助任务。如果你更习惯在浏览器里完成同类工作，也可以先看看 iFlow CLI 对应的工具条目，再回到终端操作。

需要先说明一点：iFlow CLI 已公布将于 2026 年 4 月 17 日（北京时间）正式停止服务，并建议迁移到 Qoder。另外，自 2025 年 10 月 10 日起，iFlow CLI 改用新的认证方式，届时需要手动更新 API Key，官方建议通过 /auth 登录 iFlow 以避免服务中断。这些时间点与迁移安排属于易变信息，动手前请以官网当前公告为准。

准备工作

在安装之前，先确认环境满足要求，并想清楚用哪种方式登录。

系统要求

  • Node.js 22 或更高版本
  • 内存 4GB 以上
  • 可用的网络连接
  • 基本的终端操作经验

Node.js 版本是最容易踩坑的一项。安装前先查一下：

node --version

输出需要是 22 或更高。如果低于 22，先升级 Node.js 再继续，否则后续安装或运行可能失败。

选择登录方式

iFlow CLI 支持三种登录方式，功能覆盖范围不同，这一步决定了你之后能用哪些能力：

登录方式适用场景功能范围
Login with iFlow（推荐）本地开发机，有浏览器完整功能：WebSearch、WebFetch、多模态、平台模型的工具调用优化
iFlow API Key服务器环境、无浏览器场景与第一种相同，功能完整
OpenAI 兼容 API使用自有模型服务或其他兼容 OpenAI 协议的服务不支持 WebSearch、WebFetch、平台内置多模态，也无法享受平台模型的工具调用优化

如果只是本地开发，优先用 Login with iFlow。如果要在没有图形界面的服务器上跑，用 API Key 方式，但要留意 API Key 的有效期为 7 天，需要定期续期。只有当你明确要接入自己的模型服务时，才选 OpenAI 兼容 API，并接受功能上的缺失。

操作步骤

第一步：安装 iFlow CLI

macOS / Linux

可以用一键安装脚本，它会自动装好所需依赖：

bash -c "$(curl -fsSL <安装脚本地址>)"

如果你机器上已经有 Node.js 22 以上版本，也可以直接用 npm 全局安装：

npm i -g @iflow-ai/iflow-cli@latest

Windows

  1. 下载最新的 Node.js 安装包并运行安装程序。
  2. 安装完成后重启终端：按 Windows + R 输入 cmd 打开 CMD，或打开 PowerShell。
  3. 执行 npm install -g @iflow-ai/iflow-cli@latest 安装 iFlow CLI。
  4. 执行 iflow 启动。

在 Windows 上建议使用 Windows Terminal 运行 iFlow CLI，兼容性和使用体验都更好，能明显减少环境兼容问题。

验证安装

iflow --version

能打印出版本号就说明安装成功。

第二步：首次配置与登录

在终端里直接输入命令启动：

iflow

启动后按提示选择登录方式。

方式一：Login with iFlow

  1. 运行 iflow，选择 Login with iFlow。
  2. CLI 会自动打开浏览器并跳转到 iFlow 平台。
  3. 在浏览器里完成注册或登录，并授权 iFlow CLI。
  4. 授权完成后自动回到终端，即可开始使用。

这种方式能获得最完整的功能体验，包括 WebSearch 联网搜索、WebFetch 网页内容提取与分析、内置的多模态能力，以及平台模型针对工具调用做的专门优化——后者直接影响模型调用工具的准确度和效率。

方式二：iFlow API Key

  1. 在 iFlow 官网完成注册。
  2. 在用户设置页面生成 API Key。
  3. 在 iFlow CLI 中选择 API Key 登录，粘贴密钥。

功能上与方式一一致，适合服务器等没有浏览器的环境。注意 API Key 7 天后过期，需要周期性重新生成。粘贴时确认没有多余空格，这是最常见的认证失败原因。

方式三：OpenAI 兼容 API

  1. 选择「OpenAI Compatible API」选项。
  2. 填入服务端点 URL。
  3. 填入对应的 API Key。
  4. 选择模型。

登录成功后，选择你想使用的大语言模型即可开始。模型列表与可用范围以官网当前信息为准。

第三步：认识几个核心概念

在动手之前，先花半分钟记住下面这些符号和术语，后面会反复用到：

术语含义
斜杠命令以 / 开头的控制命令，例如 /init、/help
@ 文件引用用 @文件路径 把某个文件引入对话，例如 @src/App.tsx
$ 子代理用 $ 开头调用特定子代理，例如 $code-reviewer
Shell 命令以 ! 开头，在 CLI 内执行系统命令
yolo一种执行模式，默认允许 CLI 执行所有操作
MCPModel Context Protocol，用于扩展 AI 能力的服务器体系
Sub Agent执行不同专项任务的智能代理体系
context leftCLI 右下角的指示器，显示对话中剩余的上下文长度

其中 yolo 模式需要特别留意：它默认放行所有操作，意味着文件修改和命令执行都不再逐条确认。在陌生项目或生产环境目录里不要随手开启。

第四步：运行第一个任务

有三种典型用法，按你的目的选一种。

方式 A：分析现有项目

cd your-project/
iflow
> /init
> Analyze the structure and main features of this project

/init 会让 CLI 扫描并理解项目结构，随后你可以直接提问项目的主要功能和结构。这是接手陌生代码库时最省事的入口。

方式 B：直接生成代码

iflow
> Create a Python script that calculates the first 10 numbers of the Fibonacci sequence

适合从零写一个小脚本，不需要先有项目目录。

方式 C：借助 Shell 命令辅助分析

iflow
> ! ls -la
> Help me analyze this directory structure and suggest how to organize the files

用 ! 前缀执行系统命令，把输出带进对话，再让模型基于真实输出给建议。这比让模型凭空猜测目录结构可靠得多。

一个完整示例

下面把前面的步骤串起来，从安装到拿到一次可用的分析结果，走一遍最小可运行流程。

1. 检查环境

node --version

确认输出为 22 或更高。

2. 安装

npm i -g @iflow-ai/iflow-cli@latest

3. 验证安装

iflow --version

4. 进入项目目录并启动

cd your-project/
iflow

5. 登录

选择 Login with iFlow，在自动打开的浏览器页面里完成注册与授权，回到终端后选择一个模型。

6. 初始化项目上下文

> /init

7. 提出第一个问题

> Analyze the structure and main features of this project

8. 查看目录实况并追问

> ! ls -la
> Help me analyze this directory structure and suggest how to organize the files

9. 清理并退出

> /clear
> /exit

到这里，安装、认证、项目分析、Shell 辅助、上下文清理这一整条链路都跑通了。之后每次进入项目，重复第 4 步到第 7 步即可。

常用命令速查

命令作用示例
/help查看帮助/help
/init分析项目结构/init
/clear清空对话历史/clear
/exit退出 CLI/exit
!command执行系统命令!npm install

版本更新与重装

iFlow CLI 在启动时会检查最新版本并自动更新，通常不需要手动干预。如果自动更新失败，按下面的顺序处理。

手动更新

npm i -g @iflow-ai/iflow-cli
iflow -v

第一条命令更新，第二条确认当前版本。

卸载后重装

如果手动更新仍然失败，先卸载再重装：

npm uninstall -g @iflow-ai/iflow-cli
iflow -v
npm i -g @iflow-ai/iflow-cli

中间那条 iflow -v 用来确认 iflow 命令是否还残留，卸载干净后再重装可以排除旧版本文件干扰。

注意事项

认证与有效期

  • 自 2025 年 10 月 10 日起启用新的认证方式，届时需要手动更新 API Key；建议用 /auth 通过 iFlow 登录，避免服务中断。
  • API Key 方式登录的密钥 7 天后过期，需要定期重新生成。
  • 粘贴 API Key 时确认没有多余空格，这是认证失败的高频原因。

功能差异

  • OpenAI 兼容 API 方式不支持 WebSearch、WebFetch，也不支持平台内置的多模态能力，并且无法享受平台模型的工具调用优化。如果你依赖联网搜索或图片理解，不要选这种方式。
  • Login with iFlow 与 iFlow API Key 两种方式功能一致，区别只在适用环境。

服务生命周期

iFlow CLI 已公布于 2026 年 4 月 17 日（北京时间）正式停止服务，并建议迁移到 Qoder。如果你正在做长期项目规划，需要把迁移成本算进去。具体时间与迁移方案以官网当前信息为准。

常见故障排查

安装失败

node --version
curl -I <服务地址>

先确认 Node.js 版本达到 22 以上，再确认网络连通。

认证失败

  • 确认 API Key 复制完整、没有多余空格。
  • 确认网络连接正常。
  • 重新生成 API Key 后再试一次。

命令无响应

  • 按 Ctrl+C 中断当前操作。
  • 执行 /clear 清空上下文。
  • 用 /exit 退出后重新运行 iflow。

上下文管理

CLI 右下角的 context left 指示器显示剩余上下文长度。长对话中如果发现回答质量下降或开始遗漏前文，先执行 /clear 再重新描述需求，通常比继续追问更有效。

执行模式

yolo 模式默认允许 CLI 执行所有操作，不再逐条确认。在版本控制覆盖不到、或包含敏感配置的目录里，不要开启该模式。

价格、配额、模型可用范围、版本号等信息随时可能调整，动手前请以官网当前信息为准。

返回