gptme 完全教程:开源终端 AI Agent 的安装、配置与实战

Claude Code、Codex 这类终端 AI Agent 很好用,但它们大多绑定自家模型与订阅。如果你想找一个开源、模型随便换、数据不出自己机器的同类工具,gptme 是目前最成熟的选择之一。它 2023 年春天就发布了,是最早一批 Agent CLI,至今仍在高频更新(MIT 协议,GitHub 约 4.5k star)。

gptme 的定位是「运行在任何终端里的个人 AI Agent」:笔记本、SSH 会话、tmux、无头服务器、CI 流水线里都能跑。它内置 shell、Python、文件编辑、浏览器、视觉等一整套工具,你用自然语言下达任务,它自己拆解步骤、调用工具执行、看结果纠错,直到把活干完。本文按「安装 → 配置模型 → 上手使用 → 工具与命令 → 实战场景 → 进阶玩法 → 注意事项」的顺序,把 gptme 讲透。

一、安装

gptme 用 Python 编写,需要 Python 3.11.5 或更新版本。官方推荐用 pipx 或 uv 安装(隔离环境,不污染系统 Python):

# 方式一:pipx(推荐)
pipx install gptme

# 方式二:uv
uv tool install gptme

# 方式三:一键脚本(自动识别 uv / pipx)
curl -sSf https://gptme.ai/install.sh | sh

# 带可选扩展:browser 是 Playwright 网页浏览能力,all 是全家桶
pipx install 'gptme[browser]'
pipx install 'gptme[all]'

# 想尝鲜最新开发版
uv tool install 'git+https://github.com/gptme/gptme.git[all]'

# 验证安装
gptme --version

Windows 与 macOS 同样支持(macOS 还可以用 Homebrew 装 Python/pipx 后同理);另外官方还提供桌面 App(Linux/macOS/Windows)和 Web UI,对纯命令行不感冒的用户可以先从图形界面体验。服务器上部署时建议就用 pipx 版,升级一条 pipx upgrade gptme 即可。

二、配置模型:五种接法

gptme 最大的特点是不绑模型厂商。模型用「厂商/模型名」的格式指定,例如 anthropic/claude-sonnet-4-6、openai/gpt-5、openrouter/xxx、local/xxx。接法有五种,按手头资源选:

1. API Key(最常规)

# 按需设置你有的那家的 key(写进 ~/.bashrc 或 ~/.zshrc 长期生效)
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export OPENROUTER_API_KEY="sk-or-..."
export GEMINI_API_KEY="..."
export DEEPSEEK_API_KEY="..."
export GROQ_API_KEY="..."

2. 订阅账号登录(不用 API Key)

有 ChatGPT Plus/Pro 或 SuperGrok 订阅的,可以直接用订阅额度:执行 gptme-auth openai-subscription 或 gptme-auth grok-subscription 走一遍浏览器授权,之后用 -m openai-subscription/模型名 调用。

3. OpenRouter 免费起步

第一次启动 gptme 时它会引导做 provider 设置,选 OpenRouter 走浏览器 OAuth 授权后,可以先用免费模型练手:gptme "hello" -m openrouter/openrouter/free。会话里也能用 /account setup openrouter 补做这步。

4. 本地模型(全离线)

# 以 Ollama 为例:拉一个模型并启动服务
ollama pull llama3.2:3b
ollama serve

# 指向本地的 OpenAI 兼容接口,用 local/ 前缀调用
OPENAI_BASE_URL="http://127.0.0.1:11434/v1" gptme 'hello' -m local/llama3.2:3b

LM Studio、vLLM、llama.cpp 等任何 OpenAI 兼容服务端同理。要提醒的是:小参数本地模型的工具调用能力明显弱于云端大模型,复杂任务容易翻车,本地跑更适合简单问答与轻量脚本任务。

5. 写进配置文件(设默认模型)

每次敲 -m 太麻烦,把默认模型和个人信息写进 ~/.config/gptme/config.toml:

[user] name = "User" about = "I am a Linux ops engineer." response_preference = "Don't explain basic concepts" [prompt] # 每次对话都自动带上的上下文文件 # files = ["~/notes/llm-tips.md"] [env] # 默认模型,启动时不再需要 -m MODEL = "anthropic/claude-sonnet-4-6" # 本地/自建接口也可以写在这里 # OPENAI_BASE_URL = "http://127.0.0.1:11434/v1"

配置或授权出问题时,运行 gptme-doctor --fix 做一次自动体检与修复,是官方给的排障入口。

三、快速上手

直接运行 gptme 进入交互会话,像聊天一样提需求即可;也可以把任务作为参数一次性给出。文件用 @路径 的方式附加为上下文,管道输入同样支持:

# 交互模式
gptme

# 一句话任务
gptme 'write an impressive and colorful particle effect using three.js to particles.html'

# 附带文件作为上下文
gptme 'review this' @main.py @README.md

# 管道喂入:让它补全 diff 里的 TODO、修失败的测试
git diff | gptme 'complete the TODOs in this diff'
make test | gptme 'fix the failing tests'

# 恢复上一次会话继续聊
gptme -r

执行过程中,gptme 每调用一次工具(执行命令、写文件等)默认都会先征求你确认,你能看到它要跑的命令再放行,也可以随时 Ctrl+C 打断并纠正方向。确认交互有三档:默认逐个确认;-y 自动批准但人还在场可随时接管;-n 完全非交互(见第五节)。

四、工具系统:它凭什么能干活

gptme 的能力来自一组内置工具,会话里输入 /tools 可以查看当前启用的清单和状态。核心工具如下:

  • shell:在终端执行命令(核心中的核心)
  • ipython:运行 Python 代码,可直接用你环境里装好的库做数据处理
  • read / save / append:读文件、建文件、追加内容
  • patch / morph:对已有文件做增量修改(改代码主力)
  • browser:基于 Playwright 搜索和浏览网页
  • vision / screenshot:看懂图片、截取桌面画面
  • computer:完整的桌面 GUI 操作(computer use)
  • tmux:在持久终端会话里跑长任务
  • gh:通过 GitHub CLI 操作仓库、Issue、PR
  • subagent:派生子 Agent 并行处理子任务
  • rag:对本地文件做语义检索(需 gptme-rag 包)
  • memory / lessons / todo / chats:跨会话记忆、经验规则、任务清单、历史会话检索
  • mcp:运行时发现并加载外部 MCP 服务作为新工具

工具可以按需裁剪:-t 参数限定本次会话可用的工具集,比如 gptme -t read-only 'summarize the repo' 就只给只读工具,让它总结代码时天然不可能改文件——给不信任的任务上保险时很实用。

五、会话命令与自动化参数

交互会话里有一组斜杠命令,/help 查看全量,常用的有:/model 切换模型、/tools 查看工具、/tokens 查看用量、/compact 压缩上下文(长会话必备)、/undo 与 /backtrack 回退操作、/rename 给会话起名。

# 指定模型开会话
gptme -m anthropic/claude-sonnet-4-6

# 自动批准工具调用(人可旁观、随时打断接管)
gptme -y 'run the test suite and fix any failing tests'

# 完全非交互:脚本与 CI 专用,无任何确认环节
gptme -n 'run the test suite and fix any failing tests'

# 机器可读输出(JSONL),方便流水线解析
gptme --non-interactive --output-format json 'summarize the current git diff'

# 子命令体系
gptme tools list        # 查看工具
gptme chats search 关键词  # 搜索历史会话
gptme skills list       # 查看已装技能

-n 模式是把双刃剑:它让 gptme 能进 crontab、CI 和自动化脚本,但所有工具调用无人复核,务必给它限定工作目录、用最小权限的账号和凭据运行,别在生产机上裸奔。

六、实战场景(运维与开发各举几例)

场景 1:让它读日志找故障

# 在服务器上直接开会话,把现象说清楚,它会自己 tail/grep/journalctl 排查
gptme 'nginx 从昨晚开始偶发 502,看一下 /var/log/nginx 和 upstream 服务状态,定位原因先别改配置'

关键是把「先定位、别动手」写进提示词,再配合默认的逐项确认,整个过程可控。它比直接问聊天机器人强的地方在于:不用你手动贴日志,它自己会翻。

场景 2:批量文件与数据处理

# 自然语言批处理:它会写好命令或 Python 再执行
gptme '把当前目录所有 .log 文件按月份打包压缩,超过 90 天的删掉,先给我看清单再执行'
gptme '分析 sales.csv,按地区汇总销售额并画一张柱状图存成 report.png' @sales.csv

场景 3:代码修复闭环

在项目目录里让它「跑测试 → 看报错 → 改代码 → 再跑测试」形成闭环,是 Agent 相对聊天式 AI 的最大优势:make test | gptme 'fix the failing tests' 一条命令就能启动全流程,你只需要在关键修改处点确认。

场景 4:写脚本并沉淀为工具

临时需求先让 gptme 写一次性脚本解决,验证好用后让它整理成带参数和帮助信息的正式脚本存进你的工具目录。运维手里大量的巡检、备份、清理脚本都适合这样生产。

七、进阶:记忆、技能与自主 Agent

  • 项目级配置:在项目根目录放 gptme.toml,可以声明该项目启用的插件、工具与上下文,让团队成员打开同一仓库时获得一致的 Agent 行为
  • Lessons(经验规则):把团队规范、踩坑经验写成规则文件,gptme 会按关键词和场景自动注入相关规则再行动——相当于给 Agent 配了一本岗位手册
  • Skills(技能):Anthropic 格式的轻量工作流包,按名称自动加载,适合把固定流程(如发布检查、日报生成)打包复用
  • 跨工具记忆:gptme 的记忆是本地 Markdown 文件,还能与 Claude Code、Codex 共享同一份记忆库,换工具不丢上下文
  • MCP 与 ACP:既能消费外部 MCP 服务的工具,也能用 gptme-mcp-server 把自己的 shell/Python/文件工具暴露给 Claude Desktop、Cursor 等客户端;在 Zed、JetBrains 里则通过 ACP 协议集成
  • 服务端与 Web UI:gptme-server 提供 REST API,配套 React Web UI 可自托管;也有官方云服务 gptme.ai(早期访问阶段)
  • 常驻自主 Agent:基于官方 gptme-agent-template,可以把 gptme 做成 systemd 托管的无头 Agent:记忆存在自己的 Git 仓库里,按任务选择器自主领取工作、执行、提交。作者的演示 Agent「Bob」自 2025 年起就这样长期自主运行,参与开源项目维护——这是 gptme 区别于多数同类工具的招牌玩法,但也务必配合权限护栏使用(限定工作区、凭据最小化、输出经 hooks/pre-commit 校验)

八、注意事项

  • 它真的能执行命令:默认确认机制不要嫌烦就关掉;-y 用于你全程在场的场景,-n 只用于隔离好的自动化环境。第一次在重要机器上用,先拿 -t read-only 让它只看不动
  • 模型决定上限:Agent 框架再好,工具调用的可靠性主要看模型。复杂工程任务优先选 Claude/GPT 级别的主力模型,便宜小模型适合简单明确的任务,按任务分级选模型能省不少钱
  • 自建网关的协议兼容性:gptme 的 OpenAI 兼容指的是 Chat Completions 接口(含 OPENAI_BASE_URL 的接法)。如果你的中转网关只支持 Responses API(/v1/responses)而不支持 /v1/chat/completions,直连会失败——接入前先用一条真实请求验证,不要想当然
  • 上下文成本:长会话用 /compact 压缩、/tokens 盯用量;大文件别整个 @ 进去,先让它用 shell 工具按需读取
  • 版本迭代快:gptme 更新频繁,命令与配置偶有调整,遇到行为不一致先 gptme-doctor --fix,再查官方文档(gptme.org)的对应章节

九、小结

gptme 适合三类人:想摆脱厂商绑定、自由切换模型的重度终端用户;想在自己服务器上跑一个常驻 Agent 的折腾派;以及在意数据本地化、不愿把代码发给闭源服务的团队。它的学习成本主要在第一次配模型和摸清确认机制,之后就是「说人话派活」的自然交互。如果你已经在用 Claude Code 或 Codex,gptme 值得作为开源备选装一个试试——pipx 一行命令的事,合不合手,跑一个真实任务就知道。

发表回复

后才能评论