本页参考 New API 官方 AI 应用文档，已按青云 TOP API（New API 兼容）环境整理。API 地址使用 https://top.qingyuntop.ai/v1，API Key 使用 $QINGYUN_TOP_API_KEY 占位符，请在青云 TOP API 控制台创建并妥善保存密钥。

Factory Droid CLI 教程 — 安装并配置 AI 软件工程助手，对接 青云 TOP API。从规划到测试的全流程自动化开发。

项目介绍

Droid CLI 是由 Factory AI 开发的命令行工具，旨在作为 AI 软件工程代理运行。它允许用户通过终端与各种大型语言模型交互，构建、调试和重构代码，甚至创建完整的应用程序。

效果演示

droid.webp

特性

类别

特性

价值/能力

示例/备注

快速上手与 CLI

30 秒安装；在项目目录中启动 droid 交互会话；支持 macOS/Linux 与 Windows

快速接入当前工程，无需新工具

Windows 安装：irm https://app.factory.ai/cli/windows | iex；启动：droid

端到端特性开发

从规划到实现到测试的全流程自动化；透明的评审流程

提升交付速度，保持人类把控

原生 diff 查看与批准流程（见"透明与可控"）

代码库深度理解

融合组织在代码库、文档、Issue 追踪中的共享知识；上下文感知，效果随时间提升

更准确的建议与改动

持续利用跨仓库与文档的知识

工程系统集成

原生集成 Jira、Notion、Slack 等工具；开发工作与团队流程保持同步

减少工具切换与信息孤岛

"等"表示还有更多集成

生产级自动化

工作流可在本地与 CI/CD 复用；企业级安全与合规内建

一致性与可审计性

适配流水线与企业环境

企业级能力

私有部署选项、SOC-2 合规、空气隔离（air-gapped）环境

满足安全与合规要求

以安全与质量优先

现有工具增强

在终端、IDE 与既有开发环境中工作；无需切换编辑器或学习新界面

保持现有工作习惯、低迁移成本

与熟悉工具深度集成

透明与可控

每个决策可见且可审阅；对代码变更保持完全监督；原生 diff 查看与审批工作流

降低风险、提升可控性

审核友好、可追踪

模型灵活性

不锁定单一 AI 提供商；按任务选择最佳模型；组织级一致行为与记忆

在性能与成本间做最优选择

支持多模型路由

下一步与资源

Quickstart、Common Use Cases、IDE Integration、Configuration、AGENTS.md

便于落地与实践

见页面 "Next steps/Additional resources"

AI 模型配置方法

Windows 端图文指引

1.打开终端

windows\_open\_terminal

2.安装 Factory Droid CLI

官方一键安装命令：

一键安装命令

irm https://app.factory.ai/cli/windows | iex
windows-install

3.修改配置文件

Droid CLI 使用第三方 API 需要修改配置文件。

windows-configure.webp

修改环境变量

iex (irm 'https://raw.githubusercontent.com/QuantumNous/new-api-docs/refs/heads/main/helper/factory-cli-setup.ps1')

4.开始使用 Droid CLI

现在你可以开始使用 Droid CLI 了！

启动 Droid CLI

直接启动 Droid CLI：

droid

在特定项目中使用：

# 进入你的项目目录
cd C:\path\to\your\project

# 启动 Droid CLI
droid

按 Enter 启动 Droid CLI。

Droid CLI 要求用户登录官方账号（免费）后才能使用。

5.Windows 常见问题解决

安装时提示 permission denied 错误

这通常是权限问题，尝试以下解决方法：

  • 以管理员身份运行 PowerShell
  • 或者配置 npm 使用用户目录：npm config set prefix %APPDATA%\npm

PowerShell 执行策略错误

如果遇到执行策略限制，运行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

macOS/Linux 端图文指引

1.安装 Droid CLI

安装 Droid CLI

打开终端，运行以下命令：

curl -fsSL https://app.factory.ai/cli | sh
macos-open-terminal
macos-img-02.webp

按照安装提示修改环境变量（直接复制安装提示代码）：

Linux 视情况选择 ~/.bashrc 或 ~/.zshrc

Droid CLI 环境变量 (仅作示例)

echo 'export PATH=/Users/修改此处/.local/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

2.修改配置文件

Droid CLI 使用第三方 API 需要修改配置文件。

一键修改配置文件

curl -fsSL https://raw.githubusercontent.com/QuantumNous/new-api-docs/refs/heads/main/helper/factory-cli-setup.sh | bash
macos-img-03.webp

3.开始使用 Droid CLI

现在你可以开始使用 Droid CLI 了！

启动 Droid CLI

直接启动 Droid CLI：

droid

在特定项目中使用：

# 进入你的项目目录
cd /path/to/your/project

# 启动 Droid CLI
droid

按 Enter 启动 Droid CLI。

> Droid CLI 要求用户登录官方账号（免费）后才能使用。

接入检查

  • API 地址填写青云 TOP API 的 Base URL：https://top.qingyuntop.ai/v1；应用若要求不带 /v1 的站点地址，请按页面说明填写对应格式。
  • API Key 只使用环境变量 $QINGYUN_TOP_API_KEY 或应用的安全密钥存储，不要把真实密钥提交到代码仓库。
  • 模型名称必须与控制台可用模型完全一致；遇到 401/403 检查密钥、分组和模型权限，遇到 404 检查 Base URL 是否重复填写 /v1。

发布前检查

以下检查适用于客户端中选择 OpenAI 兼容 或 Responses 提供商的场景；如果你选择的是 Anthropic、Gemini 等原生协议，请按对应协议的接口和返回结构配置。

  1. 模型 ID：先用目标 API Key 请求 GET https://top.qingyuntop.ai/v1/models，把返回的 data[].id 原样填入客户端。截图、教程和历史配置中的模型名不保证仍可用。
  2. 协议选择：新 OpenAI 集成优先选择 Responses；只有客户端或模型明确要求 Chat Completions 时才选择 Chat。Responses 的返回从 output 读取，Chat 的返回从 choices[].message 读取。
  3. Base URL：通常填写 https://top.qingyuntop.ai/v1，也就是只保留一个 /v1。要求完整接口地址的客户端才追加 /responses 或 /chat/completions，不要重复追加。
  4. 流式与重试：流式响应必须按所选协议解析事件；连接中断后不要盲目重放可能已被服务端接受的生成请求。对 429 和 5xx 使用带抖动的退避，并设置连接、读取和总超时。
  5. 上线前验证：分别验证普通文本、流式文本、工具调用或结构化输出中实际用到的能力，并记录 request id、HTTP 状态、业务状态和完成原因，避免只根据 HTTP 200 判定成功。