shellChatGPT：终端AI助手配置与实战指南

1. 项目概述：一个为终端而生的全能AI助手

如果你和我一样，是个常年泡在终端里的开发者、运维或者技术爱好者，那你肯定有过这样的体验：想快速问AI一个问题，或者让它帮你写段脚本，结果不得不离开心爱的命令行，打开浏览器，登录某个AI服务的网页，复制粘贴，再切回来。这个过程不仅打断了工作流，还特别影响效率。今天要介绍的shellChatGPT，就是为了解决这个痛点而生的。

shellChatGPT是一个纯粹的Bash脚本，它把OpenAI的ChatGPT、Whisper语音识别和TTS语音合成，以及Anthropic、Google Gemini、Mistral、Grok、DeepSeek等众多AI服务商的API，全部封装进了你的终端。你不用离开命令行，就能完成对话、代码补全、文档分析、语音转录、甚至语音对话。它支持本地部署的LLM（如Ollama、LocalAI），也支持云端API，提供了一个高度可定制、脚本友好的AI交互界面。简单来说，它让你在终端里拥有了一个功能强大、随叫随到的AI助手。

这个项目特别适合以下几类人：

• 终端重度用户：习惯在命令行下完成一切工作，追求极致的效率和流畅体验。
• 开发者和运维工程师：需要频繁使用AI辅助代码编写、调试、系统问题排查或生成文档。
• 技术写作者和研究人员：需要快速处理文本、翻译、总结或基于本地文档进行问答。
• 隐私敏感或离线场景使用者：希望通过LocalAI或Ollama在本地离线运行模型，保证数据不出本地。
• 自动化脚本开发者：希望将AI能力无缝集成到自己的Shell脚本或自动化流程中。

接下来，我将带你从零开始，深入解析这个工具的配置、核心功能、高级玩法以及我踩过的一些坑，让你能真正把它变成提升生产力的利器。

2. 核心设计思路与架构解析

2.1 为什么选择纯Bash脚本？

你可能会问，现在Python写的AI工具那么多，为什么还要用Bash？shellChatGPT的作者给出了几个关键理由，这也是其设计的精髓所在：

1. 极致的轻量与零依赖（核心依赖除外）：除了必须的curl（处理HTTP请求）和jq（解析JSON），脚本本身几乎不依赖其他特定环境。这意味着它可以在绝大多数Linux发行版、macOS甚至Android的Termux上即装即用，无需复杂的Python虚拟环境或包管理。
2. 无缝的Shell集成：作为Bash脚本，它能天然地利用Shell的特性。例如，你可以轻松地用管道（|）将其他命令的输出直接喂给AI，或者将AI的输出重定向到文件、作为另一个命令的参数。这种与Shell生态的深度融合，是其他语言工具难以比拟的。
3. 启动速度和响应迅速：没有解释器启动开销，脚本调用几乎是瞬时的。对于需要频繁、快速交互的场景（比如补全一行命令），这一点体验提升非常明显。
4. 配置即文件，透明可控：所有配置都通过一个简单的~/.chatgpt.conf文件或环境变量管理，没有隐藏的数据库或复杂状态。会话历史也是清晰的TSV（制表符分隔值）文件，你可以用任何文本编辑器查看，甚至用grep、awk进行分析。

当然，纯Bash也带来了挑战，比如复杂逻辑的实现、错误处理和对不同API响应格式的适配。shellChatGPT通过大量巧妙的脚本技巧和外部工具（如dialog用于图形化文件选择）的配合，在保持核心简洁的同时，实现了令人惊讶的丰富功能。

2.2 核心工作模式与数据流

理解脚本的几种核心操作模式，是高效使用它的关键。这些模式主要通过命令行选项来切换：

数据流示例（以-cwz模式为例）：

1. 用户按下回车开始说话，脚本调用arecord或sox录制音频。
2. 音频文件通过curl发送到Whisper API（或本地LocalAI的Whisper端点）。
3. 接收转录后的文本，将其作为用户输入，连同历史记录，通过curl发送到Chat Completions API。
4. 接收AI的文本回复。
5. 将回复文本通过curl发送到TTS API（如OpenAI的TTS-1）。
6. 接收音频流或文件，调用mpv或ffplay进行播放。
7. 将本轮对话的文本记录追加到本地的.tsv历史文件中。

整个流程在脚本中通过函数和临时文件串联，确保了会话状态的持久化和可回溯性。

3. 从零开始：安装、配置与初体验

3.1 基础安装与依赖检查

安装过程极其简单，体现了Unix哲学。你只需要下载一个脚本文件。

# 方法A：直接下载主脚本（推荐） wget https://gitlab.com/fenixdragao/shellchatgpt/-/raw/main/chatgpt.sh chmod +x ./chatgpt.sh sudo mv ./chatgpt.sh /usr/local/bin/chatgpt # 可选，放入PATH # 方法B：克隆整个仓库（如果你想研究代码或使用其他资源） git clone https://gitlab.com/fenixdragao/shellchatgpt.git cd shellchatgpt chmod +x chatgpt.sh

核心依赖检查：在运行前，请确保系统已安装以下两个必需工具：

• curl：用于所有的HTTP API通信。
• jq：用于解析和构造JSON数据，这是脚本与AI服务商“对话”的语言。

在Ubuntu/Debian上安装：

sudo apt update && sudo apt install curl jq

在CentOS/RHEL上：

sudo yum install curl jq

在macOS上（使用Homebrew）：

brew install curl jq

可选依赖安装（按需）：脚本的许多强大功能依赖于外部工具。我建议至少安装以下这些，以备不时之需：

# Ubuntu/Debian 示例 sudo apt install \ sox libsox-fmt-all ffmpeg \ # 用于音频录制/播放 mpv \ # 更好的音频播放器 xclip \ # 剪贴板操作 w3m \ # 网页文本抓取 poppler-utils \ # PDF文本提取 (pdftotext) abiword \ # DOC文件处理 (可选) dialog \ # 终端图形化文件选择 bat \ # 语法高亮显示Markdown和代码 python3 python3-pip # 用于tiktoken等高级功能 pip3 install tiktoken # 精确的Token计数（非必需但推荐）

实操心得：依赖管理不要被一长串的可选依赖吓到。脚本在设计上非常优雅，大部分功能在缺少某个依赖时会自动降级或给出明确提示。例如，没有bat，Markdown渲染就回退到纯文本；没有dialog，文件选择就需要手动输入路径。你可以先装上核心的curl和jq，然后根据实际遇到的功能提示，再按需安装其他工具。这是一种“渐进式增强”的体验。

3.2 核心配置：API密钥与模型选择

配置是使用任何AI服务的第一步。shellChatGPT的配置非常灵活。

1. 最快上手方式：环境变量直接在启动脚本前设置环境变量，适合临时测试。

export OPENAI_API_KEY='sk-your-openai-key-here' ./chatgpt.sh -c "Hello, world!"

对于其他服务商，同理：

export ANTHROPIC_API_KEY='your-claude-key' export GOOGLE_AI_API_KEY='your-gemini-key' export MISTRAL_API_KEY='your-mistral-key' # ... 然后使用对应的 --anthropic, --gemini, --mistral 选项

2. 推荐方式：配置文件创建统一的配置文件，一劳永逸。

# 生成默认配置文件模板到 ~/.chatgpt.conf ./chatgpt.sh -FF >> ~/.chatgpt.conf # 编辑配置文件 nano ~/.chatgpt.conf

配置文件内容示例：

# ~/.chatgpt.conf # OpenAI OPENAI_API_KEY="sk-..." OPENAI_ORG_ID="org-..." # 可选，如果你属于多个组织 # 默认模型 OPENAI_MODEL="gpt-4o-mini" # 可选：设置Base URL用于本地或第三方代理 # OPENAI_BASE_URL="http://localhost:8080/v1" # Anthropic ANTHROPIC_API_KEY="sk-ant-..." ANTHROPIC_MODEL="claude-3-5-sonnet-20241022" # Google AI (Gemini) GOOGLE_AI_API_KEY="AIza..." GOOGLE_AI_MODEL="gemini-1.5-pro" # 通用设置 TEMP_DIR="/tmp/chatgptsh" # 临时文件目录 HISTDIR="$HOME/.cache/chatgptsh" # 历史记录目录 MAX_TOKENS=2000 # 默认最大生成长度 TEMPERATURE=0.7 # 默认创意度

重要提示：安全第一永远不要将你的配置文件提交到公开的版本控制系统（如Git）。确保~/.chatgpt.conf的权限是600（仅所有者可读可写）：

chmod 600 ~/.chatgpt.conf

3. 模型选择策略脚本通过-m参数指定模型。如果不指定，它会使用对应服务商的默认模型（在配置文件中设置或脚本内置）。

• -m gpt-4o：使用OpenAI的GPT-4o。
• -m claude-3-5-sonnet-20241022：使用Anthropic的Claude 3.5 Sonnet。
• -m gemini-1.5-pro：使用Google Gemini 1.5 Pro。
• -m mistral-large-latest：使用Mistral AI的最新大模型。

你可以使用-mm选项启动一个交互式模型选择器（如果该服务商支持列出模型）。

注意事项：模型兼容性不同服务商的模型名称和参数支持可能不同。例如，Anthropic的模型有独特的max_tokens参数要求。脚本内部会尽力做兼容处理，但最稳妥的方式是查阅对应服务商的最新API文档，使用其官方推荐的模型名称。如果遇到400 Bad Request错误，首先检查模型名是否拼写正确、是否对该API密钥可用。

4. 核心功能深度实操与技巧

4.1 聊天模式 (-c)：你的主力对话工具

这是最常用的模式。启动一个聊天会话：

chatgpt -c

你会进入一个交互式界面，提示符是Q:。直接输入问题即可。

高级会话管理技巧：

• 加载特定角色指令：项目内置了“Awesome Prompts”和自定义提示词功能。

  # 加载一个“Linux终端专家”角色 chatgpt -c -S /linux_terminal # 加载一个“关系教练”角色 chatgpt -c -S /Relationship_Coach # 加载自定义提示词文件（位于 ~/.cache/chatgptsh/*.pr） chatgpt -c .my_coder # 加载名为 my_coder.pr 的提示词

• 会话历史与回溯：
  • -P：打印上一轮会话。
  • -P /history_name：打印指定历史文件中的上一轮会话。
  • 在聊天界面中，输入/list可以查看当前历史文件中的所有会话。
  • 输入/grep keyword可以搜索包含关键词的历史会话。
  • 输入/sub或/fork可以从历史中选择一个会话分支出来继续对话，这对于探索不同的对话路径非常有用。
• 文件内容分析：这是杀手级功能。你可以直接将文件路径或URL放在问题后面。

  Q: 总结一下这个PDF的核心观点。 ~/Documents/report.pdf Q: 这段代码有什么潜在问题？ ./src/main.py Q: 这个网页在讲什么？ https://news.example.com/article

  脚本会自动调用pdftotext、cat或w3m等工具提取文本内容，并将其作为上下文附加到你的问题中。注意：文件路径有空格时，需要用反斜杠转义或用|符号隔开：Q: 分析这个 | path/to/my file.txt。
• 视觉模型（GPT-4V等）：需要先指定支持视觉的模型。

  chatgpt -c -m gpt-4-vision-preview

  进入聊天后，使用!img /path/to/image.jpg命令上传图片，或者直接在问题末尾加上图片URL或路径。
• 调节对话风格：使用!conf命令可以实时修改参数。

  Q: !conf temperature 0.9 Q: !conf max_tokens 500

  这比退出重设命令行参数方便多了。

4.2 文本补全与插入模式 (-d,-q)：创作与编程利器

文本补全模式 (-d) 不同于聊天，它不预设“对话”结构，而是让模型根据你给的文本前缀，生成最可能的后续。这非常适合：

• 写作续写：给个开头，让它完成故事、文章。
• 代码补全：给个函数签名或注释，让它写完函数体。
• 数据格式化：给几行示例，让它按格式生成更多行。

# 单次补全 chatgpt -d -m gpt-3.5-turbo-instruct "def calculate_fibonacci(n):" # 多轮补全（保持上下文） chatgpt -dd > The quick brown fox （AI生成） jumps over the lazy dog. > And then it saw a （AI生成） rabbit and decided to chase it.

插入模式 (-q)是更精确的“填空”工具。你在文本中标记[insert]，AI只在这个位置生成内容。这对于修改文章、填充代码块特别有效。

chatgpt -q "The capital of France is [insert], and it's famous for the Eiffel Tower."

Mistral 的代码模型对FIM（Fill-in-the-Middle）支持很好，可以试试：

chatgpt --mistral -m codestral-latest -q "def factorial(n):\n if n <= 1:\n return 1\n [insert]\n return result"

实操心得：指令（Instruction）的妙用在文本补全模式中，一个清晰的指令（-S参数）能极大提升效果。例如，想让AI用Python写一个排序算法，不要只给def sort_list(lst):，最好加上指令：

chatgpt -d -S 'You are an expert Python programmer. Write efficient and well-commented code.' 'def quick_sort(arr):'

指令和输入文本共同构成了模型的“上下文”，指令设定了角色和任务框架。

4.3 语音的输入与输出 (-w,-z,-cwz)：打造终端语音助手

这是shellChatGPT最炫酷的功能之一，让你在终端里实现类似智能音箱的交互。

1. 语音转录 (-w)

• 转录音频文件：chatgpt -w ./meeting_recording.mp3
• 录制并转录麦克风输入：chatgpt -w然后按回车开始说话，再按回车结束。
• 指定转录语言：chatgpt -w zh（转录为中文），chatgpt -w ja（转录为日文）。
• 生成带时间戳的转录稿：chatgpt -ww ./audio.mp3（短语级），chatgpt -www ./audio.mp3（单词级）。这对于做字幕或精确定位非常有用。

2. 语音合成 (-z)

• 文本转语音：echo "Hello, world." | chatgpt -z
• 指定语音和语速：chatgpt -z --voice alloy --speed 1.2 "今天天气真好"

3. 全语音对话 (-cwz)启动一个能听会说的AI聊天机器人：

chatgpt -cwz

进入后，按回车开始说话，说完再按回车。AI会先把你说的转成文字，然后思考并生成文字回复，最后把回复读出来。你可以通过!conf命令切换TTS的声音（如alloy,echo,fable,onyx,nova,shimmer）。

4. 自动化语音对话 (-cwz -vv)加上-vv(verbose level 2) 参数，脚本会尝试自动检测静音来结束录音，并在AI回复朗读完毕后自动开始下一轮录音，实现接近连续的对话体验，适合做演示或长时间交互。

chatgpt -cwz -vv -m gpt-4o-audio-preview --voice nova

避坑指南：音频硬件与格式

• 权限问题：在Linux上，确保你的用户有权限访问录音设备（通常是/dev/snd下的文件）。你可能需要将用户加入audio组：sudo usermod -a -G audio $USER，然后注销重新登录。
• 找不到录音设备：脚本默认尝试arecord和sox。如果失败，检查arecord -l或sox -n -d是否能正常工作。你可以在配置文件中指定录音命令：RECORD_COMMAND="sox -q -d -r 16000 -b 16 -c 1 $TMPFILE"。
• 播放没声音：同样检查播放命令。脚本按顺序尝试mpv,ffplay,aplay,afplay(macOS)。可以在配置中设置优先项：PLAY_COMMAND="mpv --no-terminal -- $AUDIO_FILE"。
• TTS语音不自然：调整--speed（语速，0.25-4.0）和--voice。不同声音风格差异很大，多试试。

4.4 本地模型集成：Ollama 与 LocalAI

使用云端API虽然方便，但有延迟、费用和隐私顾虑。shellChatGPT完美支持本地部署的模型。

使用 Ollama

1. 安装并启动Ollama：按照 Ollama官网 指示安装，并拉取一个模型，例如ollama pull llama3.2。
2. 配置脚本：Ollama默认API地址是http://localhost:11434。启动脚本时指定即可。

   chatgpt --base-url http://localhost:11434/api -m llama3.2 -c

   或者，在配置文件中设置OPENAI_BASE_URL="http://localhost:11434/api"，然后就可以像使用OpenAI一样使用-m指定Ollama中的模型名。

使用 LocalAILocalAI是一个更强大的本地API服务器，能兼容OpenAI API格式，并运行多种模型（包括视觉、语音）。

1. 部署LocalAI：最简单的方式是用Docker。

   docker run -p 8080:8080 localai/localai:latest

2. 下载模型：LocalAI需要手动下载GGUF格式的模型文件。例如，下载一个Chat模型：

   # 进入LocalAI容器内部或模型目录 curl -L -o models/llama3.2.gguf https://huggingface.co/localai/Text-Generation-GGUF/resolve/main/llama-3.2-1b-instruct.Q4_K_M.gguf

3. 配置与使用：

   # 告诉脚本使用LocalAI服务器 export OPENAI_BASE_URL="http://localhost:8080/v1" # 注意：LocalAI的模型名对应你下载的模型文件名（不含.gguf） chatgpt -c -m llama3.2

   LocalAI的强大之处在于还能运行Whisper语音模型，从而实现完全离线的-cwz全语音对话。

深度技巧：混合使用本地与云端你可以在配置文件中为不同任务设置别名（alias）或写个小包装脚本。例如，写一个chatgpt-local脚本，里面设置好OPENAI_BASE_URL和本地模型；另一个chatgpt-cloud脚本使用云端API。根据任务对速度、成本和隐私的要求灵活切换。

5. 高级配置、问题排查与性能调优

5.1 配置文件.chatgpt.conf详解

除了API密钥，配置文件里有很多隐藏的宝藏选项可以大幅提升体验。

# 历史与会话 HISTDIR="$HOME/.cache/chatgptsh" # 历史文件存放目录 HISTORY_COLS=1000 # 历史文件中每行记录的最大列数（防止TSV格式错乱） MAX_HISTORY_LINES=500 # 单个历史文件最大行数，避免文件过大 # 网络与超时 CONNECT_TIMEOUT=30 # cURL连接超时（秒） MAX_TIME=300 # 请求最大总时间（秒），对于长文本生成很重要 # 文本处理 MAX_FILE_SIZE=500000 # 最大文件上传大小（字节），防止误传大文件 PRE_PROMPT="" # 在每个用户输入前自动添加的前缀（可用于强制语言等） POST_PROMPT="" # 在每个用户输入后自动添加的后缀 # 音频设置 RECORD_COMMAND="arecord -q -r 16000 -f S16_LE -c 1 -t wav $TMPFILE" # 自定义录音命令 PLAY_COMMAND="mpv --no-terminal -- $AUDIO_FILE" # 自定义播放命令 SILENCE_DURATION=1.5 # 静音检测时长（秒），用于 `-vv` 自动停止录音 # 显示与交互 PAGER="less -R" # 查看长文本时使用的分页器 MARKDOWN_RENDERER="bat -p --language=markdown" # Markdown渲染器 EDITOR="nano" # 编辑提示词或长文本时使用的编辑器

5.2 常见问题与排查实录

即使配置得当，也可能会遇到问题。下面是我在实际使用中总结的排查清单。

调试利器：-V和-VV参数当遇到诡异的问题时，使用-V（详细模式）可以打印出脚本发送给API的原始JSON请求。使用-VV（更详细）可以同时打印出API的原始响应。这能帮你精准定位是脚本构造的请求有问题，还是API返回的结果异常。

chatgpt -c -V "Hello" # 查看请求体 chatgpt -c -VV "Hello" # 查看请求和响应

5.3 性能调优与最佳实践

1. Token管理：API是按Token收费的。使用tiktoken（通过Python安装）可以让脚本更准确地计算Token，避免意外超限。在配置中启用：ENABLE_TIKTOKEN=1。对于长文档，脚本会自动进行截断，但最好先用自己的话总结或提取关键部分再提问。
2. 上下文长度：模型有最大上下文长度限制（如GPT-4o是128K）。使用-N参数告诉脚本模型的上下文容量，有助于它更好地管理历史。例如：chatgpt -c -N 128000。
3. 温度与随机性：-t参数控制创造性。写代码、总结事实用低温（0.1-0.3），创意写作、头脑风暴用高温（0.7-1.0）。在聊天中可以用!conf temperature 0.8动态调整。
4. 流式输出：默认情况下，脚本使用流式输出（streaming），你可以看到文字一个个蹦出来，体验更好且响应感知更快。如果网络不稳定或需要完整响应后再处理，可以用--no-stream关闭。
5. 利用Shell管道：这是shellChatGPT作为Shell脚本的最大优势。

   # 分析日志文件中最常见的错误 tail -100 /var/log/syslog | chatgpt -c "分析以下日志，列出最常见的三种错误类型：" # 将命令输出翻译成中文 ls -la | chatgpt -c "将以下Linux命令输出列表翻译成中文，并保持格式：" # 生成脚本并直接执行（⚠️ 危险，务必先检查！） chatgpt -c -S '生成安全的Bash命令' "列出当前目录下所有大于100M的文件" > find_large_files.sh bash -n find_large_files.sh # 先语法检查 bash find_large_files.sh # 再执行

6. 生态集成与自动化脚本示例

shellChatGPT的真正威力在于它可以被嵌入到你自己的脚本和自动化流程中。

示例1：自动生成Git提交信息创建一个git-commit-ai脚本：

#!/bin/bash # git-commit-ai DIFF=$(git diff --cached --stat) if [ -z "$DIFF" ]; then echo "No changes staged for commit." exit 1 fi COMMIT_MSG=$(chatgpt -c -t 0.3 -S '你是一个专业的Git提交信息生成器，遵循Conventional Commits规范。根据代码变更，生成简洁、清晰的提交信息。只输出提交信息本身，不要有其他解释。' "以下是我暂存的代码变更统计：\n$DIFF\n\n请生成提交信息：") echo "生成的提交信息：" echo "$COMMIT_MSG" read -p "是否使用此信息提交？(y/N): " -n 1 -r echo if [[ $REPLY =~ ^[Yy]$ ]]; then git commit -m "$COMMIT_MSG" fi

示例2：服务器日志监控告警摘要创建一个定期运行的cron任务：

#!/bin/bash # log-monitor.sh ERROR_LOG="/var/log/myapp/error.log" RECENT_ERRORS=$(tail -50 "$ERROR_LOG" 2>/dev/null) if [ -n "$RECENT_ERRORS" ]; then SUMMARY=$(echo "$RECENT_ERRORS" | chatgpt -c -t 0.1 "请用三句话概括以下错误日志的核心问题：") echo "$(date): 发现应用错误，AI摘要：$SUMMARY" >> /var/log/ai-monitor.log # 可以在这里集成发送邮件或Slack通知，将$SUMMARY包含进去 fi

示例3：个人知识库问答结合rg(ripgrep) 和fzf，打造一个本地文档问答系统：

#!/bin/bash # ask-doc DOC_DIR="$HOME/Documents/wiki" QUERY="$*" # 先用ripgrep快速查找相关文档片段 CONTEXT=$(rg -i -C 2 "$QUERY" "$DOC_DIR" --type md --type txt | head -20) if [ -z "$CONTEXT" ]; then chatgpt -c "我的个人知识库中没有找到关于'$QUERY'的直接信息。请根据你的通用知识回答：" else echo "$CONTEXT" | chatgpt -c "以下是从我的个人知识库中提取的相关上下文。请基于这些信息回答：$QUERY" fi

通过这些例子，你可以看到，shellChatGPT不仅仅是一个交互式工具，更是一个可以融入你技术栈各个角落的AI能力模块。它把强大的大语言模型变成了一个可以通过Shell脚本轻松调用的“函数”，极大地扩展了自动化的边界。

最后，这个项目本身也在不断进化。虽然作者说2026年重点是稳定性而非新功能，但社区贡献非常活跃。多关注项目的GitLab仓库，你会发现新的服务商集成、有趣的用法和实用的修复。记住，最好的学习方式就是动手去用，去尝试，去把它组合到你的工作流中。遇到问题，不妨用-VV看看背后发生了什么，或者去项目的Issue里找找答案。祝你终端里的AI之旅愉快而高效。