Butterfish

一句话介绍

Butterfish是一款为bash和zsh增加AI问答、命令生成、自动补全与Agent执行能力的开源Shell包装器，让用户无需复制终端输出就能获得上下文相关帮助。

软件本身采用MIT许可证且免费，但默认需要用户自己的OpenAI API密钥，模型调用产生的Token与服务层费用由用户承担。

Butterfish是什么

Butterfish Shell由Peter Bakkum维护，主要面向长期在macOS或Linux终端工作的开发者和运维人员。它不会替换系统Shell，而是在现有bash或zsh外层启动包装会话并截取输入输出。

普通命令仍交给Shell执行，以大写字母开头的自然语言输入则发送给模型。Butterfish会把近期命令、输出和先前对话放入上下文，因此可以直接询问上一条命令为何失败。

当前维护状态

截至2026年8月20日，官方GitHub最新发布版本为v0.4.3，发布记录包含Agent输入处理、Shell启动提示和低延迟自动补全等修复。Go模块页面也列出v0.4.3，并确认MIT许可证。

项目仍处于0.x版本，不能按稳定的1.0接口假设兼容性。升级前应阅读变更、保留自定义提示配置，并在非关键环境验证Shell交互和模型参数。

主要功能

上下文终端问答

在Butterfish Shell中，以大写字母开始输入即可向模型提问。近期Shell输入、输出和AI回复会进入上下文，适合解释错误、继续追问和根据当前目录建议下一步。

命令自动补全

用户输入命令时，Butterfish可以根据Shell历史和先前的AI建议预测完整命令，并用Tab接受。自动补全会频繁发起模型请求，既可能增加费用，也可能把正在输入的敏感内容传给模型服务。

Agent Mode

以单个感叹号开始任务会进入Agent Mode，模型可以根据目标反复提出和运行命令，再根据结果调整策略。当前安全模式会保留人工确认环节，而双感叹号会进入无确认执行的危险模式。

Action Mode

以单个@开始请求会要求模型生成恰好一条Shell命令，并先把命令放入终端供用户检查。双@会立即执行生成结果，只有在目标、目录和副作用都非常清楚时才应考虑。

独立prompt命令

prompt子命令可以直接发送文字，也能把管道输入与提示组合后流式返回模型结果。它适合解释配置、摘要文本或在脚本外完成一次性问答。

gencmd命令生成

gencmd把自然语言转换为Shell命令，并允许用户先检查结果。强制选项会跳过确认直接执行生成命令，面对删除、覆盖、网络下载和权限操作时风险很高。

exec错误修复

exec用于运行指定命令，并在失败时请求模型分析与提出修复建议。它可以减少复制错误日志的步骤，但建议仍需结合操作系统、工具版本和项目状态人工确认。

• 在终端中直接进行带Shell历史上下文的AI问答。
• 根据当前输入和近期命令提供Tab自动补全。
• 将自然语言转换为可检查的Shell命令。
• 运行命令并针对错误输出生成修复建议。
• 使用Agent Mode循环执行与调试多步目标。
• 使用Action Mode生成一条适合当前任务的命令。
• 查看并编辑发送给模型的系统提示和命令提示。
• 连接OpenAI或实现Responses流式接口的兼容模型服务。
• 通过标准输入把文件或其他命令输出交给模型处理。

Shell模式如何工作

1. 用户启动Butterfish Shell，程序在包装层中启动原来的bash或zsh。
2. 普通键盘输入和命令输出继续在终端中显示，并写入内存历史。
3. 普通命令直接交给Shell，大写提示和特殊模式前缀由Butterfish截获。
4. 发起模型请求时，程序从系统信息、提示模板和近期历史构造上下文。
5. 请求通过OpenAI Responses接口或兼容服务器发送，并把结果流式写回终端。
6. 若模型建议命令，安全模式先把命令放入Shell供用户检查与编辑。
7. 用户继续执行、追问或退出，当前会话历史随上下文窗口被截断和整理。

内存历史不代表数据从不离开设备。只要发起AI请求，选入上下文的命令、输出、提示和系统信息就会发送到配置的模型服务器。

安装教程

通过Homebrew安装

macOS用户可以使用维护者提供的Homebrew Tap安装，然后启动Butterfish Shell。安装完成后先查看版本和帮助，确认调用的是预期二进制文件。

1. 确认设备为受支持的macOS，并已经安装Homebrew。
2. 从维护者的Tap安装Butterfish，不要使用渠道不明的同名软件包。
3. 运行版本命令并与官方最新发布核对。
4. 首次启动Shell模式，根据提示配置模型API密钥。
5. 在临时目录运行普通命令和简单问答，验证Shell输入输出没有异常。
6. 确认安全模式会在执行生成命令前等待人工检查。

通过Go安装

macOS和Linux也可以使用Go工具链安装最新模块，适合不使用Homebrew或希望从源码构建的用户。安装后的二进制通常位于Go环境的bin目录，需要确保该目录已经加入PATH。

1. 安装当前可用的Go工具链，并确认Go环境目录。
2. 使用官方模块路径安装最新Butterfish命令。
3. 把Go的bin目录加入PATH，重新打开终端。
4. 检查Butterfish版本、许可证和帮助输出。
5. 首次启动时配置密钥，并用无副作用问题测试连接。

首次配置与API密钥

第一次调用时，Butterfish会要求提供OpenAI API密钥，并把它保存在用户配置目录的环境文件中。密钥不是ChatGPT网页订阅，是否有余额和访问权限取决于独立API账户。

• 只使用权限与额度受控的项目密钥，不要复用高权限生产密钥。
• 限制配置目录和密钥文件的系统权限，避免其他本地用户读取。
• 不要把配置目录提交到Git、同步到公共网盘或复制进问题报告。
• 发现密钥进入日志、截图或终端共享后应立即撤销并轮换。
• 连接兼容服务器时，确认密钥会随请求发送给该服务器。
• 团队设备应分别分配密钥和预算，以便审计与停止异常消费。

日常使用教程

1. 进入项目目录并启动Butterfish Shell，先用普通命令查看当前状态。
2. 遇到错误时用大写自然语言询问原因，并要求模型解释而不是立即修复。
3. 检查回答引用的命令、路径、工具版本和操作系统差异。
4. 需要一条命令时使用安全Action Mode，让结果先进入终端而不是直接执行。
5. 复杂任务可使用Agent Mode，但每次都审查命令和输出。
6. 完成后查看是否生成敏感日志，并退出包装Shell。

Agent与Action安全用法

自动执行模式可能删除文件、覆盖数据、上传秘密、安装恶意软件或更改系统权限。即使任务看似简单，也不要在生产服务器、管理员Shell或含未备份数据的目录中启用。

• 先运行只读检查，再考虑写入、安装、移动或删除操作。
• 使用普通用户、容器、临时分支或一次性虚拟环境限制影响范围。
• 执行前展开变量、通配符、递归目标和当前工作目录。
• 对下载并执行脚本、提权和磁盘命令保持人工确认。
• 重要修改先提交版本控制或建立可验证备份。
• 不要把模型回答当作命令安全审计或访问授权。

模型选择与本地模型

当前GitHub主分支文档将Shell和prompt默认模型写为GPT-5.5，并使用high推理强度，快速模式还会请求Responses API的priority服务层。用户可以用参数覆盖模型、推理强度、最大输出和服务层。

官网较旧页面仍展示GPT-4 Turbo和GPT-3.5 Turbo示例，属于历史文档口径。实际默认值应以已安装版本的帮助输出和当前仓库为准，因为模型名称和可用性会随API平台变化。

Butterfish也能连接实现OpenAI兼容Responses流式接口的本地或远程服务器。兼容性不仅要求路径相似，还要正确实现流式结果；提示模板主要针对OpenAI调优，本地模型表现可能明显不同。

价格与使用成本

Butterfish程序本身免费，没有官方会员套餐、月费或按席位价格。MIT许可证允许按条款使用、修改和分发，用户的实际成本主要来自模型API、优先服务层、本地算力和维护。

开启自动补全后，停顿期间可能频繁请求模型，是日常用量的主要渠道之一。可以禁用自动补全或增加触发等待时间，并取消不需要的priority服务层。

提示透明与自定义

Butterfish把系统提示、命令生成和自动补全提示保存在YAML配置中，用户可以查看并编辑。修改后的条目应关闭自动替换标志，否则程序更新提示库时可能覆盖自定义版本。

• 检查Shell系统提示是否符合团队安全和命令风格。
• 要求命令生成默认解释参数、路径和副作用。
• 为生产、数据库和云资源设置禁止自动执行的明确规则。
• 升级后比较默认提示变化，不要盲目保留过时模板。
• 使用版本控制保存脱敏的提示文件，但排除密钥和本机路径。
• 提示规则只能降低误操作概率，不能替代操作系统权限和人工审批。

隐私与数据安全

Butterfish是本地开源CLI，没有集中式Butterfish账户或托管聊天历史服务。模型请求仍会把选中的Shell历史、命令输出、系统信息、用户提示和AI对话发送到配置的API端点。

使用详细模式时，完整请求与响应可能打印到终端或写入系统临时目录的日志。终端输出常包含访问Token、环境变量、数据库内容和客户资料，调试日志需要视为敏感文件。

• 不要在显示密钥、生产数据库记录或客户资料后直接发起上下文问答。
• 共享终端、录屏和问题报告前清理Butterfish日志与Shell输出。
• 连接第三方或本地兼容端点时核查其日志、训练和保留政策。
• 限制历史窗口不能保证秘密一定被排除，应主动避免在会话中输出。
• 远程服务器应使用加密传输，不要把认证Token发送给不可信地址。
• 公司环境应先确认代码、数据和模型供应商使用政策。

支持系统与依赖

适合哪些用户

• 命令行初学者：获得命令解释和错误原因，但仍需要学习Shell基础。
• 软件开发者：根据当前目录、构建输出和测试失败继续追问。
• DevOps工程师：生成只读诊断命令并分析日志，生产变更仍要走审批。
• 开源爱好者：审查源代码、提示模板和数据发送逻辑。
• 本地模型用户：把终端助手连接到兼容Responses接口的本地服务。
• 需要可定制提示的团队：把命令风格与安全要求写入透明提示库。

典型使用场景

• 解释刚刚失败的构建、测试、包管理或Git命令。
• 生成查找文件、查看端口、统计目录和过滤日志的只读命令。
• 把配置文件或命令输出通过管道交给模型摘要。
• 根据工具版本差异调整参数，并解释每个标志的作用。
• 在临时分支中让Agent运行测试并尝试修复简单问题。
• 用本地模型处理不适合发送到公共云的低风险内部终端任务。

产品优势

• 直接利用Shell历史，减少复制命令、错误和上下文的往返。
• 包装现有bash或zsh，普通命令习惯基本保持不变。
• 问答、单命令和多步Agent有明确的不同输入前缀。
• 提示模板和原始模型请求可以查看与修改。
• 支持OpenAI默认服务，也能连接兼容的本地或远程模型。
• MIT开源且没有Butterfish订阅费，源代码和行为可审查。
• prompt、gencmd和exec子命令可以脱离完整Shell模式单独使用。

使用限制与注意事项

• 官方当前主要支持macOS与Linux中的bash和zsh，没有原生Windows承诺。
• Agent和Action的双前缀模式会跳过确认，错误命令可能造成不可逆损失。
• 模型可能根据错误的工具版本、操作系统或路径生成无效命令。
• Shell历史与输出会成为模型上下文，存在秘密和业务数据泄露风险。
• 自动补全频繁调用API，可能产生超出预期的Token和priority费用。
• 本地兼容服务器必须实现Responses流式接口，普通Chat Completions兼容不一定够。
• 0.x项目仍可能更改参数、默认模型、交互和提示格式。
• Butterfish不是权限隔离、备份、审计、恶意软件防护或正式运维审批系统。

API、GitHub与开源情况

Butterfish完整源代码托管在公开GitHub仓库，采用MIT许可证，并以Go编写。仓库包含命令入口、Shell包装、提示、测试、发布配置和依赖信息，开发者可以按许可证审查、修改与分发。

它不是提供远程业务API的SaaS，而是OpenAI Responses API的客户端。项目也不是模型本身，MIT许可证只覆盖Butterfish代码，不覆盖OpenAI、第三方模型、用户数据或依赖的其他许可证。

基本信息

推荐指数

推荐指数为4.3分，满分5分。Butterfish把Shell历史、透明提示、单命令与多步Agent整合到熟悉终端中，开源、轻量且允许连接本地模型，对命令行重度用户很有吸引力。

扣分主要来自自动执行的高风险、终端上下文隐私、API用量成本和平台支持范围有限。它更适合作为有经验用户的辅助层，而不是让不了解Shell的人无审查执行模型命令。

常见问题

Butterfish免费吗？

软件本身免费并采用MIT许可证，没有官方订阅套餐。使用OpenAI或其他云模型时，需要自行支付对应API费用。

Butterfish和fish shell有关系吗？

没有直接关系，Butterfish只是产品名称。官方当前明确测试的是bash和zsh，不应因为名称中有fish就假设兼容fish shell。

支持Windows吗？

官方当前安装说明只列出macOS和Linux，没有原生Windows支持承诺。WSL是否适合需要按具体Shell、终端和模型配置自行测试。

需要ChatGPT订阅吗？

不需要ChatGPT网页订阅，但默认需要独立OpenAI API密钥和可用余额。网页会员与API计费是不同产品。

默认使用什么模型？

当前GitHub主分支说明默认使用GPT-5.5和high推理强度，快速模式请求priority服务层。旧官网仍有GPT-4 Turbo示例，实际应查看安装版本帮助。

可以使用本地模型吗？

可以连接实现OpenAI兼容Responses流式接口的本地服务器。只兼容传统聊天接口的服务可能无法工作，模型质量也可能低于默认提示所针对的模型。

Shell历史会发送到云端吗？

发起AI请求时，Butterfish会把选中的近期命令、输出和对话作为上下文发送到所配置的模型端点。敏感输出不应出现在准备发送的会话中。

Agent Mode安全吗？

单感叹号模式仍需要仔细检查模型命令，双感叹号会跳过确认，风险极高。建议只在隔离环境和有备份的临时任务中使用安全模式。

Action Mode和Agent Mode有什么区别？

Action Mode只尝试生成一条Shell命令并结束，Agent Mode可以多步执行、观察结果并调整策略。单前缀默认保留检查，双前缀会自动执行。

为什么自动补全可能很贵？

它会在用户输入停顿时发起模型预测，高频请求会累积Token和服务层费用。可关闭自动补全、增加等待时间或选择更便宜的模型。

可以查看完整提示吗？

可以编辑本地YAML提示库，也能用详细模式查看原始请求和响应。详细日志可能包含秘密，使用后要妥善清理。

Butterfish完全离线吗？

默认不是，它会连接OpenAI API。只有配置本地兼容模型并确认所有请求都指向本地端点时，模型交互才可能保持在本机或内网。