ChatGPT CLI：零API成本，终端与MCP生态无缝集成AI助手

1. 项目概述：将ChatGPT桌面应用变成你的命令行AI助手

如果你和我一样，日常开发工作流重度依赖终端，同时又订阅了ChatGPT Plus，那么你很可能面临一个尴尬的局面：一边是功能强大但被“困”在图形界面里的ChatGPT，另一边是效率至上的命令行环境。每次想用GPT查个API用法、解释一段代码，都得手动切屏、打开应用、粘贴问题，等待回复，再复制结果回来，流程被打断得七零八落。toby1991/chatgpt-cli这个项目，就是为了解决这个痛点而生的。

简单来说，gpt是一个用Go编写的macOS命令行工具，它通过macOS内置的无障碍访问（Accessibility）API，直接“遥控”你电脑上已经安装的ChatGPT桌面应用。它的核心价值在于，你无需支付额外的API费用，就能在终端里直接使用你已经订阅的ChatGPT服务。更酷的是，它还是一个标准的MCP（Model Context Protocol）服务器，这意味着你可以把它接入Claude Desktop、OpenCode等支持MCP的AI助手，让它们也能调用你的ChatGPT能力，形成一个功能互补的AI工具链。

想象一下，在终端里直接敲gpt “如何用Go解析这个复杂的JSON？”，或者让Claude通过MCP调用ChatGPT进行联网搜索来补充信息，这种无缝衔接的体验，才是真正面向开发者的AI工作流。接下来，我会带你从零开始，深入这个项目的安装、配置、原理，并分享一些实战中积累的配置技巧和避坑经验。

2. 核心原理与架构拆解：它究竟是如何“遥控”ChatGPT的？

在深入使用之前，理解gpt的工作原理至关重要，这能帮助你在遇到问题时快速定位，并明白其能力边界。它的核心魔法来自于macOS的AXUIElement API，这是一套允许程序以编程方式访问和控制其他应用程序用户界面的框架，常被用于开发屏幕阅读器等辅助功能。

2.1 驱动层：基于AXUIElement的自动化引擎

项目最底层的automation/目录包含了与系统交互的“引擎”。ax.m和ax.h是Objective-C实现的底层封装，通过CGo桥接给Go层 (ax.go) 调用。这套引擎主要做几件事：

1. 应用定位与窗口控制：通过进程名（ChatGPT）找到应用实例，获取其主窗口的AXUIElement引用。
2. UI元素遍历与查找：遍历窗口内的所有无障碍元素（按钮、输入框、文本框等），通过元素的属性（如AXRole、AXTitle、AXIdentifier）精确定位目标。例如，找到模型切换的下拉菜单、网页搜索的开关、输入问题的文本框以及“发送”按钮。
3. 模拟用户操作：执行点击（AXPerformAction）、输入文本（AXSetValue）、读取内容（AXValue）等操作。

注意：这种基于UI自动化的方式，其稳定性和速度高度依赖于ChatGPT桌面应用本身的UI结构。如果OpenAI更新了应用界面，修改了按钮的标题或布局，gpt可能需要相应更新才能继续工作。这也是项目维护者需要持续跟进的地方。

2.2 业务逻辑层：编排自动化流程

driver/目录下的chatgpt.go是业务逻辑的核心。它利用底层的自动化引擎，编排了一套完整的“提问-回答”流程，我将其称为“Ask Flow”：

1. 导航回首页 (NavigateToHome)：这是一个关键的前置步骤。如果ChatGPT应用当前停留在某个历史对话或搜索结果页面，直接输入新问题可能会产生混乱。因此，gpt会先尝试点击左上角的“返回”按钮（通常是一个向左的箭头或“<”图标），确保处在一个干净的、新建对话的起始页。
2. 设置模型 (SetModel)：根据命令行参数（如--model “GPT-4o”），打开模型选择下拉框，并选择名称前缀匹配的模型。这里用的是“前缀匹配”，所以“GPT-4”可以匹配到“GPT-4o”和“GPT-4”。
3. 启用/禁用联网搜索 (SetWebSearch)：找到并点击那个小小的“地球仪”图标开关，来控制本次对话是否启用“联网搜索”功能。
4. 输入问题 (SetTextAreaValue)：将你的查询文本“键入”到主输入框。
5. 提交并等待 (Click(“发送”),WaitForStopButton,WaitForStopGone)：点击“发送”按钮，然后进入等待状态。它会监测一个“停止生成”按钮的出现和消失，这个按钮的消失通常意味着ChatGPT已经完成了本次回答的生成。
6. 读取答案 (ReadResponseText)：从对话历史中定位并提取出最新的一条回复内容。

driver/search.go则像一个调度器，根据配置决定使用哪个后端（目前主要是UI后端），并调用上述流程。

2.3 接口层：CLI与MCP双模输出

cmd/目录下是面向用户的接口。root.go定义了主要的CLI命令和参数，而mcp.go则实现了MCP服务器协议。

• CLI模式：你直接在终端中与gpt交互，它处理你的查询并返回格式化的结果。
• MCP模式：当以gpt mcp命令启动时，它会作为一个后台服务器，通过标准输入输出（stdio）与MCP客户端（如Claude Desktop）通信。客户端按照MCP协议发送JSON-RPC请求（如调用search工具），gpt执行操作后返回结果。

这种双模设计非常巧妙，既满足了个人在终端直接使用的需求，又为生态集成打开了大门。

3. 从零开始的完整安装与配置指南

理论清楚了，我们开始动手。以下步骤假设你使用的是macOS，并且已经安装了Go和Homebrew（如果没有，请先安装）。

3.1 基础环境准备与编译安装

首先，我们需要从源码构建gpt工具。

# 1. 克隆项目仓库 git clone https://github.com/toby1991/chatgpt-cli cd chatgpt-cli # 2. 编译并安装到系统路径 make install

执行make install后，编译好的gpt二进制文件会被放置到/usr/local/bin/目录下，这样你就可以在终端的任何位置直接调用它了。你可以用which gpt命令来验证安装是否成功。

3.2 关键一步：授予无障碍访问权限

这是基于UI自动化的工具在macOS上运行的必经之路，也是最容易出错的一步。系统必须允许gpt（或者说，允许运行gpt的终端程序）去控制其他应用。

1. 打开系统设置->隐私与安全性->辅助功能。
2. 点击左下角的锁图标，输入密码解锁。
3. 在右侧的应用程序列表中，找到你用来执行命令的终端应用（例如：Terminal, iTerm2, Warp），并确保它被勾选上。
4. 重要提示：如果你在VS Code的内置终端里运行gpt，那么你需要授予VS Code本身辅助功能权限。同样，如果你通过脚本或其他应用调用，也需要给对应的应用授权。

实操心得：授权后如果仍然报错，可以尝试完全退出终端应用再重新打开。有时系统权限的刷新需要重启应用进程。如果还不行，可以暂时移除权限再重新添加一次。

3.3 验证安装与基础使用

权限搞定后，我们来做个快速测试。

# 最简单的测试，确保ChatGPT桌面应用正在运行 gpt status # 进行一次真实的查询 gpt “什么是MCP协议？”

如果一切正常，你会看到终端里出现一个旋转的等待图标，然后ChatGPT应用会被自动激活（如果没运行则会启动），问题被输入，答案生成后会被完整地提取并显示在终端里，通常还会带有格式和颜色高亮。

3.4 进阶CLI功能探索

gpt的CLI功能相当丰富，远不止基础问答。

# 1. 指定模型：使用 `--model` 参数，参数值是模型名称的前缀匹配 gpt --model “GPT-4o” “用Python写一个快速排序函数，并分析其时间复杂度” # 2. 启用联网搜索：获取最新信息 gpt --web-search “今天苹果公司发布了什么新产品？” # 3. 使用管道：非常适合集成到脚本中 cat my_error_log.txt | gpt “请分析这段错误日志，可能的原因是什么？” echo “法国的首都是？” | gpt -q # -q 参数只输出答案，不要任何装饰 # 4. 交互式REPL模式：直接输入 `gpt` 回车，进入多轮对话环境 gpt > 进入交互模式，输入你的问题... > 你可以连续提问，上下文会保留在当前会话中。 > 输入 ‘exit’ 或 ‘quit’ 退出。 # 5. 实用子命令 gpt models # 列出ChatGPT应用界面上所有可用的模型 gpt dump # 诊断命令：导出当前ChatGPT窗口的无障碍元素树，用于调试

输出格式的智慧：

• 当输出到终端（TTY）时，gpt会提供彩色输出、进度提示和美观的分隔线，体验很好。
• 当通过管道重定向时（如gpt “xxx” > answer.txt），它会自动切换为纯文本模式，方便后续处理。
• 使用--json参数可以获得结构化的JSON输出，非常适合与其他工具（如jq）集成，构建自动化流程。

gpt --web-search “最新的Go版本特性” --json | jq ‘.answer’ > latest_go_features.txt

4. 集成到AI工作流：配置MCP服务器

CLI模式已经很强大了，但MCP集成才是让这个工具价值倍增的关键。它能让你的Claude、Cursor等AI助手直接调用你的ChatGPT。

4.1 理解MCP集成配置

MCP集成本质上是在AI助手的配置文件中，告诉它：“嘿，这里有一个新的工具服务器，这是启动它的命令，你可以通过标准输入输出来和它通信。”

你需要修改对应AI助手的配置文件。这些文件通常是JSON格式，位于特定的用户目录下。

4.2 配置Claude Desktop

Claude Desktop是目前最流行的MCP客户端之一。

1. 首先，找到Claude Desktop的MCP配置文件。它的通常路径是：~/Library/Application Support/Claude/claude_desktop_config.json（注意：路径可能因Claude版本略有不同，如果不存在，你可能需要先运行一次Claude Desktop让它生成）。

2. 编辑这个JSON文件。你需要添加一个mcpServers字段（如果不存在就创建）。以下是配置示例：

{ “mcpServers”: { “chatgpt”: { “type”: “stdio”, “command”: “/usr/local/bin/gpt”, “args”: [“mcp”], “env”: {} } } }

• “chatgpt”: 这是你给这个服务器起的名字，Claude内部会用它来引用。
• “type”: “stdio”: 指定通过标准输入输出通信。
• “command”:gpt可执行文件的绝对路径。使用which gpt命令可以确认你的路径。
• “args”: [“mcp”]: 启动参数，告诉gpt以MCP服务器模式运行。
• “env”: {}: 可以设置环境变量，例如{“GPT_PROMPT_SUFFIX”: “请用中文回答。”}可以为每个查询添加后缀。

3. 保存文件，并完全重启Claude Desktop。重启后，你可以在Claude的输入框里尝试使用新工具。通常，Claude会意识到它有了新能力，你可以直接说：“用chatgpt工具搜索一下最新的Rust并发模型。”

4.3 配置OpenCode

OpenCode是另一个支持MCP的代码编辑器/IDE。其配置方式类似，但配置文件路径不同。

1. 配置文件通常位于：~/.config/opencode/opencode.json
2. 编辑该文件，添加MCP服务器配置：

{ “mcp”: { “chatgpt”: { “type”: “stdio”, “command”: “/usr/local/bin/gpt”, “args”: [“mcp”, “--model”, “GPT-4o”], “env”: {} } } }

这里我在args里直接指定了默认模型“GPT-4o”，这样通过OpenCode发起的查询默认就会使用这个模型。

4.4 配置OpenClaw与mcporter

OpenClaw是一个管理MCP服务器的桌面应用，它通过mcporter来管理服务器配置。这种方式更图形化，管理多个服务器时更方便。

1. 首先确保你安装了 mcporter 。
2. 编辑mcporter的配置文件：~/.mcporter/mcporter.json。
3. 添加gpt服务器的配置：

{ “mcpServers”: { “gpt”: { “command”: “/usr/local/bin/gpt”, “args”: [“mcp”, “--model”, “GPT-4o”, “--web-search”], “env”: { “GPT_PROMPT_SUFFIX”: “” } } } }

在OpenClaw中，你就可以方便地启用、禁用这个服务器，或者查看其日志。

配置后的验证：配置完成后，在Claude或OpenCode中，你可以尝试问：“你现在可以使用哪些工具？” 或者直接给出一个需要联网搜索或特定模型能力的任务，观察AI助手是否会正确调用gpt工具。如果调用失败，请检查AI助手的日志输出，通常会有详细的错误信息。

5. 无头模式（Headless Mac）深度配置指南

如果你想把gpt部署在一台远程的、没有显示器的Mac mini或Mac Studio上（通过SSH访问），会遇到一些特殊挑战。核心问题是：macOS的图形界面和自动化API在完全没有显示信号时会行为异常。

5.1 核心问题：虚拟显示与防休眠

ChatGPT桌面应用是一个GUI程序，它需要一个有效的显示上下文来渲染界面。当Mac处于真正的“无头”状态时，WindowServer（管理窗口的系统服务）可能会降级或停止工作，导致AXUIElement API无法获取到有效的UI元素信息，gpt也就无法操作。

解决方案是让系统“认为”它连接了一个显示器。

方案一：启用苹果远程管理（推荐首选）这是最“原生”的方案。对于Apple Silicon的Mac mini，启用“远程管理”功能会自动创建一个虚拟显示缓冲区。

1. 打开系统设置->通用->共享。
2. 打开远程管理。
3. 根据提示进行配置。启用后，即使没有物理显示器，系统也会维持一个活跃的显示会话。

方案二：使用HDMI虚拟插头如果方案一无效或不稳定，购买一个便宜的HDMI虚拟插头（Dummy Plug）是最物理、最可靠的方案。将其插入Mac的HDMI端口，macOS会将其识别为一台真实的1080p或4K显示器，完美解决显示问题。

方案三：软件虚拟显示（BetterDisplay）对于只有USB-C接口的设备，或者不想购买硬件的用户，可以使用 BetterDisplay 这类软件来创建虚拟显示器。它通过软件模拟一个显示设备，效果也不错，但可能比硬件方案稍耗资源。

5.2 自动化防睡眠与锁屏

远程服务器另一个大敌是自动睡眠和锁屏。一旦系统睡眠或锁屏，所有自动化操作都会中断。

gpt项目非常贴心地提供了一个一键解决方案：

gpt setup-caffeinate

这个命令做了两件大事：

1. 安装Caffeinate守护进程：它会创建一个LaunchAgent（~/Library/LaunchAgents/com.user.gpt-caffeinate.plist），在用户登录时自动运行caffeinate -dimsu命令。-dimsu参数组合可以防止磁盘休眠、系统休眠、空闲睡眠，并声明一个用户级别的断言，效果非常全面。
2. 禁用自动锁屏：通过sysadminctl命令将“屏幕锁定后需要密码”的延迟设置为“永不”。这一步至关重要，因为当SSH或VNC会话断开时，系统可能会触发锁屏，锁屏界面会破坏自动化对ChatGPT应用窗口的访问。

要卸载这些设置，可以运行：

gpt remove-caffeinate

5.3 额外的系统级设置（锦上添花）

为了万无一失，你还可以手动调整一些系统节能设置：

# 禁用显示器睡眠（虽然我们可能没有物理显示器，但设置它有益无害） sudo pmset -a displaysleep 0 # 禁用系统睡眠 sudo pmset -a sleep 0

同时，在系统设置中：

• 显示器->高级-> 将“当显示器关闭时防止自动睡眠”的选项勾选上（如果存在）。
• 锁定屏幕-> 将“开始屏幕保护程序”和“关闭显示器”的时间设为“永不”，并将“需要密码”的选项设为“永不”。

5.4 无头模式下的权限问题

在无头模式下通过SSH运行gpt，辅助功能权限需要授予给sshd进程或其父进程吗？实际上，权限是授予给终端进程的。只要你通过SSH登录后，是在同一个用户会话下的终端（如bash或zsh）中运行gpt，并且这个终端应用（比如系统自带的Terminal，如果你通过SSH启动了一个新的终端会话）已经在辅助功能列表中被授权，那么gpt就能正常工作。关键在于运行命令的环境是否已被授权。

6. 实战问题排查与经验技巧

即使按照指南一步步操作，也难免会遇到问题。下面是我在长期使用和调试中总结的常见问题与解决方法。

6.1 权限问题排查

症状：运行gpt命令后无反应、报错提示“无法访问UI元素”或直接失败。解决步骤：

1. 确认应用已授权：再次检查系统设置 -> 隐私与安全性 -> 辅助功能，确保你使用的终端应用（如iTerm2）已被勾选。如果通过VS Code的终端运行，则需要勾选VS Code。
2. 重启终端：授权更改后，完全退出终端应用再重新打开。这是最常被忽略但最有效的步骤。
3. 检查TCC数据库（进阶）：如果怀疑权限未正确写入，可以使用tccutil命令重置对应应用的权限，然后重新勾选。

   # 重置Terminal的辅助功能权限（谨慎操作） sudo tccutil reset Accessibility com.apple.Terminal

   执行后需要重新打开Terminal并再次授权。
4. 查看系统日志：在终端运行log stream --predicate ‘subsystem == “com.apple.TCC”‘ --info，然后尝试运行gpt，观察是否有关于权限拒绝的日志输出。

6.2 ChatGPT应用界面变化导致失败

症状：之前好用的gpt突然无法输入问题或点击发送按钮了。原因：ChatGPT桌面应用更新，改变了按钮的AXTitle（可访问性标题）或UI结构。解决：

1. 使用诊断命令gpt dump。这个命令会输出当前ChatGPT窗口的完整无障碍元素树（AX Tree）。将输出保存到文件。
2. 在输出中搜索关键词，如“发送”、“停止生成”、模型选择按钮的标题等。观察这些元素的AXTitle或AXIdentifier是否发生了变化。
3. 如果确认变化，需要修改driver/chatgpt.go中对应的元素查找逻辑（例如sendButtonTitle常量），然后重新make install。当然，更常见的做法是向项目提交Issue或等待作者更新。

6.3 MCP连接失败或工具不可用

症状：在Claude或OpenCode中无法调用chatgpt工具，或者调用后无反应。排查：

1. 检查配置文件语法：确保你编辑的JSON配置文件没有语法错误（如多余的逗号、括号不匹配）。可以使用json_pp或在线JSON校验工具检查。
2. 检查命令路径：确保配置文件中command的路径完全正确。使用which gpt确认绝对路径。
3. 手动测试MCP服务器：在终端直接运行gpt mcp，它应该启动并等待输入（不会有明显输出，因为它在等待stdio的JSON-RPC请求）。这说明服务器本身能启动。
4. 查看客户端日志：Claude Desktop和OpenCode通常有日志输出窗口或日志文件。查看那里是否有关于加载MCP服务器失败的错误信息。错误信息通常会明确指出是路径问题、权限问题还是协议通信问题。
5. 重启客户端：修改MCP配置后，必须完全重启AI客户端应用，否则新配置不会被加载。

6.4 性能与稳定性优化

• 网络环境：gpt的响应速度最终取决于ChatGPT应用本身的速度，而ChatGPT应用又依赖于你的网络。确保稳定的网络连接。
• 避免并发：UI后端本质上是模拟用户操作，ChatGPT应用本身不支持并行处理多个查询。因此，gpt在设计上就是串行执行的。不要试图同时运行多个gpt命令，这会导致UI状态混乱。
• 使用合适的模型：在CLI中通过--model指定模型。对于代码问题，GPT-4o通常比默认的GPT-3.5更准确。对于需要最新信息的查询，务必加上--web-search。
• 环境变量GPT_PROMPT_SUFFIX：在MCP模式下，你可以设置这个环境变量，为每个查询自动添加一个后缀。例如，设置为“请用简洁的列表形式回答。”，可以让所有通过MCP的查询都获得格式统一的答案。

6.5 与其他工具集成的小技巧

• Shell Alias：为常用命令设置别名，提升效率。

  # 添加到 ~/.zshrc 或 ~/.bashrc alias gp=‘gpt’ alias gp4=‘gpt --model “GPT-4o”‘ alias gpweb=‘gpt --web-search’

• 与fzf结合：实现历史命令的模糊查找并发送给GPT。

  # 一个简单的例子：用fzf选择历史命令，解释其作用 history | fzf | awk ‘{$1=”“; print $0}’ | xargs gpt “解释这个Linux命令的作用：”

• 作为代码审查助手：将git diff的输出通过管道发送给GPT。

  git diff HEAD~1 | gpt “请以资深开发者的身份，审查这段代码改动，指出潜在的风险、风格问题和改进建议。”

这个项目完美地诠释了“胶水工具”的价值——它没有创造新的AI能力，而是用巧妙的方式将已有的强大工具（ChatGPT桌面应用）无缝嵌入到开发者最熟悉的工作环境（终端和MCP生态）中。它解决的不仅仅是“能用”的问题，更是“好用”和“流畅”的问题。经过一段时间的深度使用，我已经完全习惯了在终端里随时向GPT提问，也习惯了让Claude在需要时调用它进行联网搜索，这种工具间顺畅协作的体验，极大地提升了研究和开发的效率。如果你也是macOS上的AI工具重度用户，花点时间配置好gpt，绝对是值得的投资。