用 BLACKBOX CLI 在终端里完成安装、配置与首个项目

BLACKBOX CLI 是一个跑在终端里的 AI 编程助手。它把「描述需求—生成或修改代码—解释改动」这一整套流程放进命令行，不需要在编辑器和浏览器之间来回切换。它适合已经习惯用终端工作、希望用自然语言驱动代码生成与调试的开发者；对刚接触命令行的人也不算难，因为核心交互就是打开会话、用一句话说清要做什么。本文按安装、配置、首次会话、实际任务、命令速查的顺序讲一遍，读完可以独立完成一次从零建项目到修 bug 的完整流程。如果你更习惯在网页端对话，也可以先看看 BLACKBOX AI 的在线形态，再决定是否装 CLI。

准备工作

开始之前需要确认三件事，缺一件都会卡在第一步：

• 一个可用的终端：macOS 用 Terminal 或任意 shell，Linux 用 Bash 等常见 shell，Windows 用 PowerShell。Windows 上如果打算使用 Blackbox 与 Claude 之外的 agent，还需要 WSL（Windows Subsystem for Linux）。
• 一个 BLACKBOX AI 账号：CLI 首次配置时要登录并填入 API Key，Key 从账号的 Dashboard 页面获取。
• 一个代码项目（可选）：如果只是想先试试生成能力，空目录也能用；如果要让 CLI 分析现有代码库，就在项目根目录启动会话。

另外提醒一句：CLI 的版本号、可用模型清单、各套餐的调用额度都会变动，本文不列具体数字，实际以官网当前信息为准。

操作步骤

第一步：安装 BLACKBOX CLI

安装方式按操作系统分两种，都是一行命令。

Unix / Linux / macOS（Bash）：

curl -fsSL | bash

Windows（PowerShell）：

iex (irm )

Windows 上如果遇到执行策略（execution policy）报错，先在同一个 PowerShell 会话里放开当前进程的策略，再重新执行安装命令：

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

注意 -Scope Process 只影响当前这个 PowerShell 窗口，关掉就恢复原状，不会改动系统级设置，这是相对安全的做法。

第二步：配置提供方与 API Key

安装完不能直接用，必须先配置。执行：

blackbox configure

首次运行会依次引导你完成三件事：选择要修改的配置项、选择模型提供方、输入 API Key。初次配置时在配置菜单里选 Configure Providers。

选择模型提供方（agent）。CLI 支持多个 agent，不同 agent 背后是不同的模型家族：

Agent	说明	平台可用性
Blackbox	BLACKBOX AI 自有模型	所有平台
Claude	Anthropic 的 Claude 模型	所有平台
Codex	OpenAI 的编程向模型	Windows 需 WSL
Gemini	Google 的多模态模型	Windows 需 WSL
Goose	可访问 BLACKBOX CLI 的全部模型	Windows 需 WSL
OpenCode	完整模型支持	Windows 需 WSL
Qwen	可访问 BLACKBOX CLI 的全部模型	Windows 需 WSL

这里有一个容易踩的坑：在 Windows 原生 PowerShell 下，只有 Blackbox 和 Claude 两个 agent 可选。想用 Codex、Gemini、Goose、OpenCode、Qwen，必须把 CLI 放进 WSL 里运行。所有 agent 共用同一个 BLACKBOX API Key，不需要为每个 agent 单独申请。

输入 API Key。登录 BLACKBOX Dashboard，复制 API Key，粘贴到终端提示处即可。

Windows 上选 Claude 的额外依赖。如果在 Windows 上选了 Claude agent，需要本机装有 Git Bash，否则 Claude Code 跑不起来。先在 PowerShell 里检查：

git --version

如果提示找不到命令，用 winget 安装 Git：

winget install Git.Git

装完重启终端，再回到配置流程。

选择具体模型。选定 agent 之后，还要从该提供方下挑一个具体模型，闭源和开源模型都在可选范围内。配置完成后设置会保存在本机，之后随时可以再跑一次 blackbox configure 改回来。

第三步：启动第一个会话

新开一个终端窗口，直接输入：

blackbox

看到欢迎界面和提示符就说明配置生效了。按 Ctrl + C 退出会话。之后想恢复之前的会话，用 blackbox session。

第四步：用自然语言提问

会话里不需要记命令语法，直接说人话。可以先试探能力边界：

> what can you help me build today?
> show me what programming languages you support

如果当前目录是一个已有项目，可以直接让它读代码：

> analyze this project and tell me what it does
> what files are in this directory?
> help me understand the project structure

这里有个设计上的便利：CLI 会按需自己读取文件，不需要你手动把上下文贴进去。它会分析整个项目结构再给建议，所以从项目根目录启动会话效果最好。

第五步：从零创建一个项目

让它生成完整的小项目，是熟悉工作方式最快的方法：

> create a simple todo list web app using HTML, CSS, and JavaScript
> build a basic calculator app with a clean interface
> create a personal portfolio website template

这类请求执行后，CLI 会创建所需的文件和目录、写出完整代码、安排好文件结构，并给出运行项目的说明。也就是说它不只给一段代码片段，而是把可运行的骨架搭起来。

第六步：改进已有代码

在已有项目里，改进类任务同样用一句话描述：

> add responsive design to my website
> improve the styling of my todo app with modern CSS
> add form validation to my contact form
> optimize my JavaScript code for better performance

处理这类请求时，它会先分析现有代码，再提出并实施改动，在增强功能的同时尽量保持原有行为不变，最后解释改了什么。这一点对维护老项目很关键——你要的是「改完还能跑」，而不是推倒重来。

第七步：调试与排错

排错是这类工具最能体现价值的地方。把现象描述清楚，而不是只说「有 bug」：

> my website isn't displaying correctly on mobile devices - fix it
> there's an error when I click the submit button - debug this
> my CSS styles aren't applying properly - help me fix this
> optimize my code to load faster

它会定位问题根因、给出详细解释、自动实施修复，并验证方案是否真的有效。

第八步：进阶用法

熟悉基本交互后，可以尝试更重的任务，按类型分三类：

复杂项目搭建

> create a full-stack e-commerce website with user authentication
> build a REST API with database integration and testing

代码生成与自动化

> generate unit tests for all my functions
> create a deployment script for my web application

环境与集成

> set up a development environment with hot reloading
> integrate a payment system into my e-commerce site

核心思路始终一致：用自然语言描述目标，由它处理技术实现细节。

一个完整示例

下面把前面的步骤串成一条可跑通的路径，假设你在一台 macOS 或 Linux 机器上，从零开始。

1. 安装

curl -fsSL | bash

2. 配置

blackbox configure

在菜单里选 Configure Providers，agent 选 Blackbox（所有平台都可用，最省事），粘贴 Dashboard 里复制的 API Key，再挑一个具体模型。

3. 建一个空目录并进入

mkdir todo-demo && cd todo-demo

4. 启动会话

blackbox

5. 提出需求

> create a simple todo list web app using HTML, CSS, and JavaScript

它会生成 HTML、CSS、JS 文件并给出运行说明。按提示在浏览器里打开页面，确认能添加、勾选、删除待办项。

6. 迭代改进（仍在同一会话里）

> improve the styling of my todo app with modern CSS
> add form validation to my contact form

7. 制造并修复一个问题。手动改坏一处样式，然后描述现象：

> my CSS styles aren't applying properly - help me fix this

观察它如何定位原因、改哪几行、怎么解释。这一步是理解它工作方式的最好方式。

8. 退出并恢复

Ctrl + C

下次回来：

blackbox session

或者用 blackbox project 直接打开最近的项目目录。

常用命令速查

命令	作用	示例
blackbox session	启动交互式会话	blackbox session 或 blackbox s
blackbox configure	配置设置与提供方	blackbox configure
blackbox project	打开最近的项目目录	blackbox project 或 blackbox p
blackbox projects	列出最近的项目目录	blackbox projects 或 blackbox ps
blackbox run	执行文件中的指令	blackbox run instructions.txt
blackbox info	显示系统信息	blackbox info
blackbox update	更新到最新版本	blackbox update
Ctrl + C	退出交互会话	—

其中 blackbox run 值得单独说一句：它把一串指令写进文本文件后批量执行，适合把重复性的初始化流程固化下来，比如每次新建项目都要跑的那几步。

提示词写法建议

同样的工具，描述方式不同，产出质量差别很大。几条实践原则：

• 具体到现象。不要写「fix the bug」，而要写「fix the login bug where users see a blank screen after entering wrong credentials」。前者它只能猜，后者它能直接定位。
• 复杂任务拆成步骤。分多轮下达，每轮确认结果再继续：先「create a landing page with hero section and navigation」，再「add a contact form with email validation」，最后「make the entire site mobile-responsive」。
• 从简单项目起步。先让它做一个只显示当前天气的小应用、一个多页面的基础博客模板，摸清它的产出风格，再上复杂度。
• 顺手要解释。边建边学：「explain how this CSS flexbox layout works」「teach me about JavaScript event handling while building this feature」，把生成过程变成学习过程。

注意事项

• Windows 原生环境只支持两个 agent。PowerShell 下只有 Blackbox 和 Claude 可用，其余 agent 需要 WSL。这是平台限制，不是配置问题。
• Windows 上用 Claude 需要 Git Bash。缺了它 Claude Code 无法正常运行，先用 git --version 确认。
• 执行策略报错只影响当前进程。用 Set-ExecutionPolicy -Scope Process 放开即可，不必改系统级策略。
• 首次使用必须先配置。没跑过 blackbox configure 就直接 blackbox，会因为缺少提供方和 API Key 而无法工作。
• 更新机制分版本。较新版本会在启动会话时自动检查并安装更新；旧版本需要手动执行 blackbox update，或者重跑一次安装命令。更新后重新用 blackbox 启动会话，才能看到介绍新功能的欢迎界面。
• 模型清单与额度会变。可选的 agent、具体模型、各套餐的调用限制都以官网当前信息为准，本文不列具体数值。
• 在项目根目录启动会话。它依赖自动读取文件来理解上下文，目录层级选错，分析结果就会偏。

把上面这套流程走一遍，基本就能把 BLACKBOX CLI 用起来了：安装一行命令，配置一次，之后所有工作都在 blackbox 会话里用自然语言完成。真正需要练习的不是命令，而是怎么把需求描述得足够具体。