开源最强本地AI CLI工具来了

开源最强本地AI CLI工具来了

语音转文字 / 智能纠错 / RAG代理 / 并行开发

支持 macOS/Linux/Windows，100%本地运行保护隐私

我是atyou, 今天教大家agent-cli 本地AI命令行工具深度解读。

你是否受够了每次使用AI都需要联网？你是否想要一个完全私有、本地运行的AI助手？你是否渴望用语音直接输入内容而不用敲键盘？

今天要介绍的 agent-cli 是一个完全开源的本地AI命令行工具套件。它可以让你的麦克风变成AI输入端，让你的终端拥有语音交互能力，而且一切都在本地运行，数据永远不会离开你的电脑。

这个项目在 GitHub 上已经获得了 179 Stars，由 Bas Nijholt 开发维护。最新版本 v0.85.0 于 2026年3月发布，带来了大量新功能和性能优化。本文将带你深入了解这个强大的本地AI工具。

— — — — — — — — — —

一、为什么需要 agent-cli？

传统的AI交互方式存在诸多痛点，而 agent-cli 针对性地解决了这些问题。

Step 1痛点分析：传统AI工具的局限

首先，每次使用 ChatGPT、Claude 等云端AI都需要联网，网络不稳定时体验极差。其次，你的聊天记录、文档内容都被上传到云端，存在隐私泄露风险。再者，语音输入必须通过第三方服务转文字，不仅慢还要付费。

agent-cli 的核心理念是「Local-First」——所有AI能力都在本地运行，不依赖任何云服务。你的麦克风输入、剪贴板内容、文档数据，都保存在本地设备上。

Step 2系统级热键：全局语音输入

最酷的功能是系统级热键。以 macOS 为例，按下 Cmd+Shift+R 就能开始语音录制，说完后再次按下热键，语音会自动转成文字并复制到剪贴板。

这意味着在任何应用里——邮件、文档、代码编辑器——你都能直接说话输入文本，再也不用在键盘和鼠标之间来回切换。

macOS 热键配置:

Cmd+Shift+R - 语音转文字

Cmd+Shift+A - 智能纠错

Cmd+Shift+V - 语音编辑剪贴板

— — — — — — — — — —

二、安装与配置：5分钟快速上手

agent-cli 提供多种安装方式，满足不同用户的需求。

Step 1方式一：仅安装 CLI 工具

如果你已经有 Ollama 或其他 AI 服务运行，或者计划使用 OpenAI 云端服务，只需要一行命令即可安装：

这是最轻量的安装方式，适合已有 AI 基础设施的用户。

# 使用 uv (推荐)

uv tool install agent-cli -p 3.13

# 或使用 pip

pip install agent-cli

# 验证安装

agent-cli --version

Step 2方式二：自动安装全套服务

如果想要完整的本地 AI 体验，包括 Whisper 语音识别、Ollama 本地大模型、Piper/TTS 语音合成，建议使用自动安装脚本：

安装脚本会自动配置 Ollama、Whisper、TTS 等服务，真正实现开箱即用。

# 安装 agent-cli

uv tool install agent-cli -p 3.13

# 安装所有服务

agent-cli install-services

# 启动服务

agent-cli start-services

# 设置系统热键

agent-cli install-hotkeys

Step 3配置文件的正确姿势

agent-cli 支持 TOML 格式的配置文件，可以为不同命令设置默认值。配置文件按以下顺序查找：

建议在项目根目录放一个 agent-cli-config.toml，方便团队成员统一配置。

— — — — — — — — — —

三、核心命令详解

agent-cli 提供 11 个核心命令，覆盖语音、文字、开发等各种场景。

Step 1autocorrect - 智能语法纠错

这个命令可以快速修复文本中的拼写和语法错误。它会读取剪贴板内容（或直接传入文本），发送给本地 LLM 进行校正，然后自动把修正后的文本复制回剪贴板。

配合系统热键 Cmd+Shift+A，选中任何有问题的文本，一键就能修复。

# 修正剪贴板中的文本

agent-cli autocorrect

# 直接修正指定文本

agent-cli autocorrect "this has an eror"

# 使用 OpenAI 而非本地模型

agent-cli autocorrect --llm-provider openai

Step 2transcribe - 语音转文字

这是作者开发 agent-cli 的初衷——用语音解放双手。它使用 Faster Whisper（Linux/CUDA）或 MLX Whisper（Apple Silicon）进行本地语音识别，不需要联网。

支持多种音频格式，识别结果直接复制到剪贴板，方便粘贴到任何应用中使用。

# 查看可用麦克风

agent-cli transcribe --list-devices

# 开始录音转文字

agent-cli transcribe --input-device-index 1

Step 3transcribe-live - 连续实时转录

与 transcribe 不同，transcribe-live 是连续录音模式，使用 VAD（Voice Activity Detection）自动检测语音开始和结束。

适合会议记录、实时字幕等场景。它会把每段识别结果保存到 JSONL 文件，同时可选保存原始音频为 MP3。

# 安装 VAD 支持

uv tool install "agent-cli[vad]" -p 3.13

# 启动连续转录

agent-cli transcribe-live

# 自定义角色标签

agent-cli transcribe-live --role meeting

Step 4speak - 文本转语音

把文字转为语音输出。agent-cli 支持多种 TTS 引擎：Piper（CPU，免费开源）、Kokoro（GPU，高质量）、OpenAI TTS（云端）。

本地 TTS 的优势是零延迟、无限量，完全离线也能使用。

# 本地 TTS (Piper)

agent-cli speak "Hello, world!"

# 使用 Kokoro (需要 GPU)

agent-cli speak "Hello!" --tts-provider kokoro

Step 5voice-edit - 语音编辑剪贴板

这是语音转文字的进阶版——用语音命令直接编辑剪贴板内容。比如可以说「make this more formal」让它变得更正式，或者说「summarize this」生成摘要。

LLM 会根据你的语音指令理解和修改文本，然后更新剪贴板。

# 语音编辑剪贴板

agent-cli voice-edit

# 指定编辑指令

agent-cli voice-edit --prompt "translate to Spanish"

— — — — — — — — — —

四、开发者神器：dev 并行开发环境

dev 命令是 agent-cli 最强大的功能之一，它让 AI 辅助的并行开发变得前所未有的简单。

Step 1什么是 dev 命令？

dev 命令使用 git worktree 创建隔离的开发环境，每个功能都在独立的分支和目录中工作，互不干扰。这解决了多任务开发时的三大难题：

1. 切换分支需要 stash 当前改动；2. 同时开发多个功能无法并行；3. 主分支容易被实验性代码污染。

Step 2快速创建开发环境

一行命令就能创建全新的开发环境，自动完成：创建 git worktree、检出分支、复制 .env 文件、运行项目初始化（npm install / uv sync 等）、自动检测并启动 AI 编码助手。

你甚至可以让 AI 自动生成有意义的分支名。

# 创建新环境（随机分支名）

agent-cli dev new

# 指定分支名

agent-cli dev new my-feature

# 让 AI 生成分支名

agent-cli dev new --branch-name-mode ai --prompt "Refactor auth flow"

# 创建后自动打开编辑器并启动 AI 代理

agent-cli dev new my-feature -e --start-agent

Step 3Claude Code 插件集成

最惊艳的功能是 Claude Code 插件。安装后，你可以直接对 Claude Code 说「在三个独立环境同时开发 auth、payment、notification 功能」，它会自动调用 agent-cli dev 创建三个并行的 git worktree，每个都启动独立的 AI 代理。

这才是真正的 AI 原生开发工作流。

# 安装 Claude Code 技能

agent-cli dev install-skill

# 或通过插件市场安装

claude plugin marketplace add basnijholt/agent-cli

claude plugin install agent-cli-dev@agent-cli

Step 4多代理并行审查

利用 tmux 多路复用，你可以在同一个 worktree 中启动多个 AI 代理进行并行代码审查、性能分析、测试验证。

每个代理可以有不同的角色定义，输出到不同的报告文件。

# 创建 worktree

agent-cli dev new review-auth --from HEAD

# 启动多个审查代理

agent-cli dev agent review-auth -m tmux --prompt-file .claude/review-security.md

agent-cli dev agent review-auth -m tmux --prompt-file .claude/review-performance.md

agent-cli dev agent review-auth -m tmux --prompt-file .claude/review-tests.md

— — — — — — — — — —

五、服务器与代理功能

除了命令行工具，agent-cli 还提供强大的服务器功能。

Step 1server whisper - 本地 Whisper 服务器

本地运行的语音识别服务器，提供双协议支持：Wyoming 协议（兼容 Home Assistant）和 OpenAI 兼容 API。

特性包括：TTL 内存管理（5分钟无活动自动卸载模型释放显存）、MLX 加速（Apple Silicon）、Faster Whisper（Linux/CUDA）、自动选择最优后端。

# 安装 Whisper 支持

pip install "agent-cli[faster-whisper]"

# 启动服务器

agent-cli server whisper

# 服务器地址

# OpenAI 兼容: http://localhost:10301

# Wyoming: localhost:10300

Step 2rag-proxy - 文档问答代理

RAG（检索增强生成）代理服务器，让你可以与本地文档对话。它是 OpenAI 兼容的中间件，拦截 chat 请求、检索相关文档、注入上下文、转发给上游 LLM。

使用两阶段检索（Bi-Encoder + Cross-Encoder）提高召回率和准确率。支持 ChromaDB 向量存储，自动文档分割。

# 安装 RAG 支持

agent-cli install-extras rag

# 启动 RAG 代理

uvx -p 3.13 --from "agent-cli[rag]" agent-cli rag-proxy \

--docs-folder./my-docs \

--openai-base-urlhttp://localhost:11434/v1

# 与文档对话

curl http://localhost:8000/v1/chat/completions \

-d'{"messages":[{"role":"user","content":"文档说了什么？"}]}'

Step 3memory - 长期记忆系统

memory 命令提供长期记忆功能，包括 memory add（添加记忆）和 memory proxy（记忆代理服务）。

它能在多轮对话中保持上下文，学习用户的偏好和项目知识，特别适合个人 AI 助手场景。

# 添加记忆

agent-cli memory add "我最喜欢使用 qwen3:4b 模型"

# 启动记忆代理

agent-cli memory proxy

— — — — — — — — — —

六、常见问题解答

以下是大家最关心的问题汇总。

Step Q1支持 Windows 吗？

支持！建议使用 WSL2 以获得最佳体验，或者使用 Docker 方式安装。Windows 原生支持正在完善中。

Step Q2需要什么样的硬件？

基础功能（autocorrect、chat）只需 8GB 内存。语音识别建议 16GB 内存 + NVIDIA 显卡（或 Apple Silicon Mac）。本地大模型建议 16GB+ 显存。

Step Q3可以自定义模型吗？

完全支持！Ollama 支持自定义模型，也可以配置使用 llama.cpp、vLLM 等本地服务器，或切换到 OpenAI/Gemini 云端模型。

Step Q4热键不生效怎么办？

macOS 需要在系统设置中授予 Accessibility 权限给 skhd（热键守护进程）。Linux 需要使用对应的桌面环境配置脚本。

Step Q5和现有 AI 工具冲突吗？

不冲突。agent-cli 是独立工具，可以与 VS Code Copilot、Claude Desktop 等共存。它专注于终端场景和本地私有化部署。

— — — — — — — — — —

七、安全使用建议

虽然 agent-cli 是本地工具，但在使用过程中仍需注意以下安全事项。

Step 1API Key 保护

如果使用 OpenAI/Gemini 云端模型，确保 API Key 不写入代码或配置文件。使用环境变量或 .env 文件管理，并在 .gitignore 中排除。

# 正确方式：使用环境变量

export OPENAI_API_KEY="sk-xxx"

# 或配置文件中引用环境变量

# openai_api_key = "$OPENAI_API_KEY"

Step 2权限最小化

macOS 热键需要 Accessibility 权限，仅授予可信应用。Linux 使用自定义热键时注意权限隔离。

Step 3本地模型安全

使用本地大模型时，确保模型来源可信。不要下载运行来路不明的模型文件，以防安全风险。

— — — — — — — — — —

八、总结与下一步

agent-cli 为开发者提供了一个强大、私有、灵活的本地 AI 工作环境。

Step 1核心亮点回顾

✅ 100% 本地运行，数据不离开设备

✅ 系统级热键，语音输入无处不在

✅ 支持多平台（macOS/Linux/Windows）

✅ 11 个核心命令，覆盖语音、文字、开发全场景

✅ dev 并行开发环境，AI 辅助多任务处理

✅ Claude Code 插件，原生 AI 开发工作流

Step 2学习路径建议

1. 先安装 CLI 并测试 autocorrect 命令

2. 配置系统热键，体验语音转文字

3. 探索 dev 命令，为现有项目创建开发环境

4. 尝试 rag-proxy，与自己的文档对话

5. 安装 Claude Code 插件，体验多代理并行开发

— — — — — — — — — —

七、常见问题与排错

agent-cli 和 Ollama 是什么关系？

agent-cli 使用 Ollama 作为默认的本地 LLM provider，两者配合使用效果最佳。

语音识别需要网络吗？

完全不需要。Whisper 识别在本地执行，支持离线使用。

支持中文语音输入吗？

支持！Whisper 对多语言都有良好支持，中文识别效果不错。

如何更新 agent-cli？

使用 uv tool update agent-cli 或 pip install --upgrade agent-cli。

可以同时运行多个命令吗？

可以，每个命令独立运行。server 系列命令会启动后台服务。

— — — — — — — — — —

八、安全建议

•API Key 要通过环境变量管理，不要写入代码

•本地模型要从可信来源下载

•macOS 热键权限仅授予必要应用

•定期更新版本获取安全补丁

— — — — — — — — — —

总结

agent-cli 是一个完全本地化的 AI 命令行工具套件，核心特性是 100% 离线运行和数据隐私保护。

它提供了 11 个核心命令，包括语音转文字(.transcribe)、智能纠错(autocorrect)、文本转语音(speak)、并行开发(dev)、RAG代理(rag-proxy) 等。

dev 命令是最强大的功能，它使用 git worktree 创建隔离的开发环境，支持 Claude Code 插件实现多代理并行开发。

支持 macOS/Linux/Windows，Apple Silicon Mac 可以获得 MLX 加速的语音识别体验。

安装简单，一行命令即可开始：uv tool install agent-cli -p 3.13

•核心特性100% 本地运行、隐私保护、系统级热键

•支持平台macOS / Linux / Windows / Docker

•核心命令11 个（autocorrect/transcribe/speak/dev/chat/memory/rag-proxy等）

•安装方式uv tool install agent-cli -p 3.13

•进阶功能RAG 文档问答、长期记忆、并行开发环境

— — — — — — — — — —

我是atyou, 您有什么感兴趣的主题，可以给我留言让我们一起拥抱AI, 共同进步，享受美好生活。

参考文档：

•GitHub 仓库 → 点击访问

https://github.com/basnijholt/agent-cli

•官方文档 → 点击访问

https://agent-cli.nijho.lt/

•演示视频 → 点击访问

https://www.youtube.com/watch?v=7sBTCgttH48

•PyPI 安装包 → 点击访问

https://pypi.org/project/agent-cli/