各位 Emacs 用户大家好。最近在折腾 AI 编程工作流时我越来越觉得把大模型直接塞进编辑器里才是效率最高的做法而 Gptel 就是这样一个让我“用过就回不去”的 Emacs 包。很多人第一次听说 Gptel会以为它只是一个聊天窗口其实它的价值远远超过了“ChatGPT 客户端”。这篇文章将以标题 “Gptel Emacs AI Client: Beyond Just a Chat Interface” 为主线从概念、安装、配置到实战完整拆解 Gptel 的能力边界帮助你把它真正融入到日常编辑、代码补全、重构、组织笔记等工作流中。文章主要面向两类读者一是已经熟悉 Emacs 基础操作想在编辑器内接入大模型的开发者二是对 AI 编程工具感兴趣想了解 Emacs 生态中如何落地 LLM 集成的朋友。读完后你将能独立安装 Gptel配置多个 AI 后端掌握上下文发送、区域改写、会话管理、多模型切换等核心用法同时也会了解常见报错的排查思路和工程化配置建议。1. Gptel 是什么为什么说它不只是聊天界面1.1 从聊天客户端到编程助手Gptel 是 Emacs 里的一款大语言模型客户端它基于异步请求实现核心目标是让你在不离开 Emacs 的情况下与各类 LLM 服务交互。一个最直观的用法是M-x gptel打开一个类似聊天软件的 buffer输入问题后按C-c C-c发送AI 的回复会以流式的方式逐字显示出来。但如果你只把它当作“聊天框”那就浪费了它最强大的能力。Gptel 的设计思路更接近“上下文驱动的编辑器插件”你可以把当前缓冲区、选中的 region、组织模式的块、甚至是函数定义直接发送给模型模型基于这些内容生成回答。这意味着你不需要再复制粘贴代码到网页里也不需要人工整理上下文Gptel 会保留当前编辑环境的元信息比如major-mode、行号、文件路径等。1.2 它解决的痛点很多开发者使用 ChatGPT 或同类网页工具时最大的痛点不是模型回答不好而是上下文搬运成本太高。写代码时你要把函数、错误信息、需求描述粘贴到网页再等回答再贴回 Emacs。如果回答超过最大长度还要分段复制。Gptel 把整个流程压缩到了几个快捷键内而且它天然适应 Emacs 的 buffer 文化每个对话都是一个 buffer可以用熟悉的键位操作、保存、检索。另一个痛点是多后端管理。Gptel 抽象了不同 API 的差异支持 OpenAI、Azure OpenAI、Anthropic Claude、Google Gemini以及兼容 OpenAI 接口的本地服务如 llama.cpp、Ollama。你可以为不同场景绑定不同的后端和模型比如日常问答用快速模型代码重构用能力更强的模型从而在成本和效果之间找到平衡。1.3 核心特性一览异步流式响应不会阻塞 Emacs。基于 transient 菜单的交互控制模型、温度、token 上限等参数可以随时调整。上下文集成发送 buffer、region、函数、组织模式条目。多个会话管理支持并行多个对话命名后随时切换。可扩展的响应处理支持把生成内容插入当前 buffer或替换选中区域。多种补全工具配合可以结合completion-at-point和嵌入式补全框架实现类似 Copilot 的效果。看起来功能很多但 Gptel 的配置并不复杂接下来我们先把环境准备好。2. 环境准备与版本说明2.1 基础环境要求Gptel 是一个纯 Elisp 扩展包运行在 GNU Emacs 中。根据项目文档它要求 Emacs 27.1 或更高版本但为了获得更稳定的体验推荐使用 Emacs 29 或当前较新的版本。操作系统方面Windows、macOS、Linux 均支持不过 Windows 用户需要注意网络代理和证书配置这一部分我们会在常见问题中单独说明。在写这篇文章时Gptel 的最新版本迭代很快具体 API 参数和配置项可能会微调。因此本文不会死守某个具体版本的配置文件而是演示一种常见的、稳定的配置思路。你在实际操作时建议先查看本地包的README或者通过C-h f gptel RET查看函数文档再根据实际情况微调。2.2 安装包管理器选择你可以使用 Emacs 自带的能力安装也可以借助第三方包管理工具。我个人比较推荐用use-package统一管理配置这样可读性和可迁移性都更好。下面是一个最小化的安装配置。;; 文件路径~/.emacs.d/init.el 或 ~/.config/emacs/init.el (require package) (add-to-list package-archives (melpa . https://melpa.org/packages/) t) (package-initialize) (unless (package-installed-p use-package) (package-refresh-contents) (package-install use-package)) (use-package gptel :ensure t)如果你使用的是straight.el同样可以通过以下配置安装(use-package gptel :straight (gptel :type git :host github :repo karthink/gptel))这里需要注意直接使用:ensure t时Emacs 会从 MELPA 拉取包。国内网络环境如果下载慢可以配置package-archives为清华或中科大镜像也可以使用straight.el配合代理下载。2.3 获得 API 访问凭证Gptel 本身不提供模型能力它需要你提供一个可访问的 LLM API 服务。常见的选择有OpenAI API需要使用其 API key。Azure OpenAI 服务适用于企业环境。Anthropic Claude API。Google Gemini API。本地或内网部署的兼容 OpenAI 协议的模型服务例如 Ollama、llama.cpp server 等。在配置前请确保你已经具备可用的 API 凭证。出于安全和合规考虑不要把 API key 直接写在 Emacs 配置里推荐使用 Emacs 的auth-source机制管理。下面是一个示例配置它会从~/.authinfo读取凭据。3. Gptel 安装与基础配置3.1 使用 use-package 完成最小配置我们先从一个能跑通的最简配置开始。假设你使用的是 OpenAI 兼容接口并且已经为当前 shell 导出了环境变量OPENAI_API_KEY那么以下配置就能让 Gptel 工作起来。(use-package gptel :ensure t :config (setq gptel-default-mode #org-mode) (setq gptel-prompt-prefix-alist ((org-mode . ** User) (markdown-mode . **User**) (text-mode . ))) (setq gptel-org-state-heading org-state))这段配置做了什么gptel-default-mode指定 Gptel 会话 buffer 使用org-mode作为默认模式。如果你更喜欢纯文本或 Markdown可以改为markdown-mode或text-mode。gptel-prompt-prefix-alist的作用是定义不同主模式下用户输入的标记前缀方便解析对话内容。gptel-org-state-heading控制 org 状态下回复的标题格式。3.2 用 auth-source 管理 API Key不推荐在配置里写死gptel-api-key。更好的做法是让 Gptel 通过 Emacs 的认证源去查询。你可以在~/.authinfo文件中写入类似下面的内容machine api.openai.com login apikey password sk-xxxxxxx然后在配置中指定(setq gptel-api-key (lambda () (auth-source-pick-first-password :host api.openai.com)))注意auth-source文件默认权限应该比较严格避免其他用户读取。在 Linux 下可以使用chmod 600 ~/.authinfoGptel 也支持直接从环境变量读取 key。如果你不希望额外维护文件可以简单设置(setq gptel-api-key (getenv OPENAI_API_KEY))但这种方式在 Emacs 会话启动后不会再自动刷新适合个人开发环境。3.3 打开第一个会话配置完成后重新加载 Emacs执行M-x gptel。如果一切正常你会看到一个新的 buffer底部有一个输入区域上方是对话内容。在输入区域输入“你好请介绍一下你自己”然后按C-c C-c系统会异步调用模型并将回复逐字显示出来。如果遇到空响应或错误提示先检查gptel-api-key是否设置成功。gptel-backend是否指向了正确的服务地址。网络是否能正常访问 API 端点。4. 核心用法把编辑器上下文变成 AI 的“输入”4.1 发送整个缓冲区或选中区域Gptel 区别于普通聊天框的核心体验是你能把当前编辑中的代码或文档直接作为上下文发送给模型。准备一个测试文件比如一个 Python 脚本。# 文件路径/tmp/test.py def add(a, b): return a b def multiply(a, b): return a * b打开这个文件进入python-mode然后执行M-x gptel-send-buffer。Gptel 会创建一个会话并把当前 buffer 的全部内容发送给模型随后你可以继续输入“请解释这段代码”或“请帮我添加类型注解”。此时模型已经看到了文件内容回答会更加贴合实际代码。如果你想只发送部分代码可以先选中 region执行M-x gptel-send-region。这个命令会把选中的文本作为上下文发送并且保留上下文中的主模式信息便于模型识别语言。4.2 发送函数、定义或 Org 条目除了 buffer 和 regionGptel 还提供了一些感知结构性上下文的命令。例如在 Emacs Lisp 中可以发送当前 defun在 Org-mode 中可以发送当前 heading 下的子树。常见的命令如下gptel-send-defun发送当前光标所在的函数定义。gptel-send-org-element发送 Org 元素。gptel-send-file发送指定文件内容。gptel-send-region-to-gptel经典区域发送。这样你就不需要手动裁剪代码块模型可以获取较精确的局部上下文进而生成更准确的回答。4.3 设置系统提示词与角色在 Gptel 会话中你可以调用M-x gptel-set-system-prompt来设置系统提示词。系统提示词决定了模型的行为方式例如“你是一个资深 Python 工程师回答尽量简洁并给出代码示例”。每个会话可以有不同的系统提示词非常灵活。此外Gptel 也支持在配置中预设多个系统提示词并通过 transient 菜单快速切换。你可以在gptel-prompt-alist中定义常用提示模板。(setq gptel-prompt-alist ((default . You are a helpful assistant.) (code-review . You are a senior software engineer. Review the code for bugs and style issues.) (explain . Explain the given code or text in simple terms.)))4.4 异步流式输出与取消Gptel 使用异步请求响应期间 Emacs 仍然可以继续编辑其他 buffer。如果模型输出过长你可以按C-c C-c发送请求后在等待过程中做别的事如果想中断生成可以执行M-x gptel-abort或点击中断键。这个体验和网页端的“停止生成”按钮类似。需要留意的是在 Gptel 会话内部调用gptel-abort只取消当前请求之前的对话记录依然保留。如果你发现 Emacs 卡顿通常不是 Gptel 的问题而是网络请求同步化或别的外部插件引起的。5. 实战案例用 Gptel 完成代码生成与重构5.1 场景设定假设我们正在开发一个简单的 Python 工具用于处理 CSV 文件合并。传统做法是手动编写所有代码但现在我们想用 Gptel 辅助完成。我们准备先在空文件里实现一个函数读取多个 CSV 文件按列合并。要求使用 pandas但代码中没有安装 pandas 时希望代码有友好的提示。我们会利用 Gptel 的上下文能力分三步完成在 Python buffer 中写一个函数签名和注释。使用gptel-send-region把这段“待实现”的骨架发给模型。让模型返回完整实现然后手动或自动插入代码。5.2 编写骨架并发送上下文在 Emacs 中新建/tmp/merge_csv.py输入以下内容import pandas as pd def merge_csv_files(file_paths: list[str], output_path: str) - None: 合并多个 CSV 文件按第一列对齐。 参数: file_paths: CSV 文件路径列表。 output_path: 合并后输出文件路径。 # TODO: 在这里实现合并逻辑 pass选中整个函数执行M-x gptel-send-region。在生成的 Gptel buffer 中发送指令“请实现这个函数要求支持不同 CSV 的不同列并保留缺失值。给出完整代码。”5.3 模型返回与代码插入模型可能会返回类似下面的代码import pandas as pd def merge_csv_files(file_paths: list[str], output_path: str) - None: 合并多个 CSV 文件按第一列对齐。 if not file_paths: raise ValueError(file_paths cannot be empty) dataframes [] for path in file_paths: try: df pd.read_csv(path) except FileNotFoundError: print(fWarning: {path} not found, skipping.) continue dataframes.append(df) if not dataframes: raise ValueError(No valid CSV files to merge.) # 按第一列做 outer merge保留所有行 merged dataframes[0] for df in dataframes[1:]: merged pd.merge(merged, df, onmerged.columns[0], howouter) merged.to_csv(output_path, indexFalse)你可以手动把这段代码粘贴回/tmp/merge_csv.py也可以使用 Gptel 提供的编辑功能。5.4 使用 gptel-rewrite 直接改写代码Gptel 的gptel-rewrite命令非常实用。选中代码后执行M-x gptel-rewrite它会让你输入一个改写指令比如“添加异常处理”“转换成异步方式”“优化性能”模型返回结果后你可以选择替换原区域或者只预览而不改动。这种模式非常适合代码重构。比如选中最开始那个带 TODO 的骨架函数执行gptel-rewrite输入“实现这个函数”模型返回后按y确认替换Gptel 会把原 region 替换为模型生成的内容同时保留 buffer 其余部分。使用gptel-rewrite时要注意它会直接修改你的缓冲区因此建议在修改前保存文件或者使用 Emacs 的 undo 随时回退。6. 进阶集成多后端、Org 模式与编辑工作流6.1 配置多个后端并切换前面我们使用了 OpenAI 默认后端。Gptel 支持通过gptel-backend-alist配置多个后端。下面是一个示例展示了如何配置 OpenAI、Anthropic 与本地 Ollama 三个后端。(use-package gptel :ensure t :config ;; OpenAI 默认后端 (setq gptel-backend-alist ((OpenAI :host api.openai.com :endpoint /v1/chat/completions :key (lambda () (auth-source-pick-first-password :host api.openai.com)) :model gpt-4o-mini :stream t) (Anthropic :host api.anthropic.com :endpoint /v1/messages :key (lambda () (auth-source-pick-first-password :host api.anthropic.com)) :model claude-3-5-sonnet-latest :stream t) (Ollama :host localhost:11434 :endpoint /v1/chat/completions :key ollama :model llama3.1 :stream t))))这段配置中每个后端都包含了请求地址、模型名、认证方式和是否启用流式输出。如果你使用 OpenAI 兼容的本地服务只需把:host改成localhost:11434:key设置为任意值即可。在 Gptel 会话中执行M-x gptel-set-backend可以切换后端执行M-x gptel-set-model可以切换同一后端下的不同模型。也可以先配置gptel-model-alist把不同模型按场景分组。6.2 用 Org-mode 管理对话记录Gptel 的默认模式设置为org-mode后每个会话 buffer 都是一个 Org 文件对话结构会按照 heading 和 block 组织。你可以用 Org 原生的折叠、导出功能把对话记录导出为 HTML、PDF 或 Markdown。这非常适合写技术文档时保留 AI 回答的参考资料。此外Gptel 还提供gptel-send-org-element命令可以把当前 Org 条目包括子树发送给模型。结合 Org Babel你甚至可以让 Gptel 生成的代码直接进入源块然后通过org-babel-execute-src-block执行形成“提问-生成-执行”的闭环。6.3 与补全框架组合实现类 Copilot 效果Gptel 本身不是补全引擎但它可以和company-mode、corfu等补全框架配合在光标位置插入模型补全结果。你可以通过gptel-request或gptel-completion-at-point实现代码补全。这种方式比完整的 AI 插件更轻量适合那些不喜欢把编辑器变得过重的用户。不过如果追求和 Copilot 一样的高频补全体验建议还是配合专门的补全工具例如copilot.el、codeium.el或lsp-bridge。Gptel 的价值更多在于对话式交互和上下文重构二者可以并行使用。7. 常见问题与排查思路7.1 错误表格问题现象常见原因解决思路请求后无响应API key 未正确配置检查gptel-api-key或 auth-source 能否取到密码提示 “401 Unauthorized”key 无效或权限不足重新生成 API key确认后端环境变量是否生效提示 “404 Not Found”endpoint 或模型名不正确核对后端地址和模型名查看服务端文档请求超时网络代理未设置或远程服务慢配置 Emacs 代理或将超时时间调大Emacs 卡顿并发请求过多或同步回调减少同时请求数升级 Emacs 版本流式输出不生效后端不支持流式接口将:stream设为nil返回内容被截断token 上限设置过小增大gptel-max-tokens参数中文乱码或编码错误缓冲区编码不匹配设置set-language-environment UTF-87.2 网络代理与认证在国内网络环境下访问部分海外 API 可能需要配置代理。Emacs 可以使用内置的url库代理设置(setq url-proxy-services ((http . 127.0.0.1:7890) (https . 127.0.0.1:7890)))同时request库和gptel的curl后端也会读取环境变量HTTP_PROXY和HTTPS_PROXY。可以根据实际代理端口修改。这里需要提醒一点涉及代理时请确保你使用的是合法合规的网络接入方式不要在受限网络环境中绕过访问限制。7.3 无法加载 gptel 包如果安装后M-x gptel提示找不到命令可能是包没有正确加载。你可以执行M-x list-packages查看是否已经安装也可以在*Messages*buffer 中查看报错。常见原因是 MELPA 源刷新失败或 use-package 配置写在了package-initialize之前。确保配置顺序正确(package-initialize) (use-package gptel :ensure t)7.4 API 参数兼容性不同后端对参数支持不一致。例如 OpenAI 支持temperature、top_p、max_tokens而某些本地服务可能忽略这些字段。如果你在切换后端时发现模型行为异常可以先关闭流式、减少参数再逐步开启。8. 最佳实践与工程建议8.1 安全与密钥管理严禁把 API key 写入公开或同步的配置仓库中。推荐使用auth-source或系统钥匙串并确保密钥只存在于本地。如果需要共享配置可以使用gptel-api-key的符号引用让用户各自填写。同时不要轻易把敏感代码或内部数据发送给外部 LLM 服务。在发送前检查 region 是否包含密钥、数据库连接字符串等敏感信息。对于严格保密的项目建议只在本地部署的小模型服务上使用 Gptel。8.2 上下文管理和 Token 控制大模型的输入输出都有 token 限制。当上下文过长时不仅消耗 token还可能降低回答的准确性。建议发送给模型的代码尽量精简。如果只是局部问题使用gptel-send-region而不是整个文件。为每个会话设定合适的系统提示词减少无关指令。可以在配置中调整gptel-max-tokens例如(setq gptel-max-tokens 4096)8.3 会话管理与复用长期使用会积累很多会话 buffer。建议定期清理不再需要的 Gptel buffer或使用gptel-save命令保存重要会话。如果你的磁盘空间不大可以通过gptel-kill-all-sessions删除所有会话但这会丢失未保存的对话内容执行前需要确认。8.4 保持包版本更新Gptel 迭代很快新版本会修复 bug、增加对新模型的支持。建议定期执行M-x package-refresh-contents后升级包。如果某个旧版本配置失效升级后注意阅读NEWS文件看看是否有需要迁移的配置项。8.5 用宏或函数封装常用请求如果你经常重复执行某些请求比如“检查当前代码的潜在 bug”可以用 Emacs Lisp 封装成一个自定义命令调用gptel-request并传入系统提示词。这样既能提升效率也方便团队共享。(defun my/gptel-review-current-function () Send the current defun to GPTel for code review. (interactive) (gptel-send-region (point) (save-excursion (beginning-of-defun) (mark-defun) (point)) 请作为资深工程师检查这段代码的潜在问题和优化建议。))把这个函数绑定到方便的快键键上比如C-c g r就能快速完成一次代码评审。9. 总结与后续方向通过本文你应该已经理解了 Gptel 在 Emacs 中的定位它并不仅仅是把 ChatGPT 搬进编辑器而是把编辑器本身变成了模型交互的上下文来源。它最核心的用法是“发送上下文-获得反馈-无缝应用”这大大减少了在网页端和编辑器之间切换的成本。下一步你可以继续探索 Gptel 的更多细节比如如何配置多轮多模态输入如何在 org-dynamic-block 中嵌入 Gptel 调用如何与transient菜单深度定制。如果身边有同事也使用 Emacs可以一起整理一套适合团队的 Gptel 配置模板把模型选择、提示词模板、密钥管理统一起来。如果这篇教程对你有所帮助不妨收藏备用后续遇到配置问题时也方便随时查阅。