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

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 执行所有操作
MCP	Model Context Protocol，用于扩展 AI 能力的服务器体系
Sub Agent	执行不同专项任务的智能代理体系
context left	CLI 右下角的指示器，显示对话中剩余的上下文长度

其中 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 执行所有操作，不再逐条确认。在版本控制覆盖不到、或包含敏感配置的目录里，不要开启该模式。

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