Gptel：Emacs 原生 LLM 客户端

gptel 是一个简单的 Emacs 大语言模型聊天客户端，支持多种模型和后端。它秉承 Emacs 的理念，可随时使用，并能以统一方式在任何缓冲区中运行。

常规用法：（YouTube 演示）

另请参阅 Armin Darvish 制作的这段 YouTube 演示（2 分钟）。

可在 Emacs 中的任何位置与 LLM 交互（任意缓冲区、Shell、迷你缓冲区等）。

LLM 的响应采用 Markdown 或 Org 标记格式。

支持多个相互独立的对话、一次性的临时交互，以及介于两者之间的各种使用方式。

支持工具调用，为 LLM 提供智能体能力。

支持使用 mcp.el 集成模型上下文协议（MCP）。

支持多模态输入（包括图片和文档）。

支持 LLM 响应中的“推理”内容。

可将聊天保存为普通的 Markdown、Org 或文本文件，并在之后恢复。

继续对话时，可以编辑之前的提示词或 LLM 响应。这些内容会重新发送给模型。

支持自省，因此你可以准确查看将要发送的内容，并在发送前检查和修改请求。

可以在中间阶段暂停多阶段请求，并在之后恢复。

不喜欢 gptel 的工作流？你可以通过简单的 API，基于任何受支持的模型或后端创建自己的工作流。

gptel 会在 Curl 可用时使用它，否则回退到内置的 url-retrieve，从而无需外部依赖也能运行。

安装 Straight 手动安装 Doom Emacs Spacemacs

设置 OpenAI 其他 LLM 后端 （可选）使用 =authinfo= 保护 API 密钥 （可选）从环境变量读取 API 密钥 OpenAI（ChatGPT plus/pro 订阅）Azure GPT4All Ollama Open WebUI Gemini Llama.cpp 或 Llamafile Kagi（FastGPT 和 Summarizer）together.ai Anyscale Perplexity Anthropic（Claude）Groq Mistral Le Chat OpenRouter PrivateGPT DeepSeek Sambanova（Deepseek）Cerebras Github Models Novita AI xAI AI/ML API GitHub CopilotChat AWS Bedrock Moonshot（Kimi）

其他 LLM 后端 （可选）使用 =authinfo= 保护 API 密钥 （可选）从环境变量读取 API 密钥 OpenAI（ChatGPT plus/pro 订阅）Azure GPT4All Ollama Open WebUI Gemini Llama.cpp 或 Llamafile Kagi（FastGPT 和 Summarizer）together.ai Anyscale Perplexity Anthropic（Claude）Groq Mistral Le Chat OpenRouter PrivateGPT DeepSeek Sambanova（Deepseek）Cerebras Github Models Novita AI xAI AI/ML API GitHub CopilotChat AWS Bedrock Moonshot（Kimi）

（可选）使用 =authinfo= 保护 API 密钥

（可选）从环境变量读取 API 密钥

OpenAI（ChatGPT plus/pro 订阅）

Llama.cpp 或 Llamafile

Kagi（FastGPT 和 Summarizer）

用法 在任意缓冲区中：在专用聊天缓冲区中：在请求中包含媒体（图片、文档或纯文本文件）保存和恢复聊天会话 设置选项（后端、模型、请求参数、系统提示词等）在请求中包含更多上下文 处理“推理”内容 工具调用 定义 gptel 工具 选择工具 LLM 工具集合 模型上下文协议（MCP）集成 重写、重构或填充某个区域 Org mode 的额外便利功能 自省（检查、调试或修改请求）

在专用聊天缓冲区中：在请求中包含媒体（图片、文档或纯文本文件）保存和恢复聊天会话

在请求中包含媒体（图片、文档或纯文本文件）

保存和恢复聊天会话

设置选项（后端、模型、请求参数、系统提示词等）

在请求中包含更多上下文

处理“推理”内容

工具调用 定义 gptel 工具 选择工具 LLM 工具集合 模型上下文协议（MCP）集成

模型上下文协议（MCP）集成

重写、重构或填充某个区域

Org mode 的额外便利功能

自省（检查、调试或修改请求）

常见问题 聊天缓冲区 UI 我希望窗口在响应插入时自动滚动 我希望光标在响应插入后移动到下一个提示词处 我希望更改提示词和 LLM 响应的格式 gptel 如何区分用户提示词与 LLM 响应？Transient 菜单行为 我希望设置 gptel 选项，但仅应用于当前缓冲区 我希望保存 Transient 菜单选项，这样只需设置一次 使用 Transient 菜单会留下多余的窗口 可以更改 Transient 菜单的按键绑定吗？（Doom Emacs）由于与 Org mode 存在按键冲突，从 gptel 菜单发送查询失败 其他问题 我希望以 gptel-send 或选项菜单不支持的方式使用 gptel （ChatGPT）我遇到错误“(HTTP/2 429) You exceeded your current quota” 为什么还要再做一个 LLM 客户端？

聊天缓冲区 UI 我希望窗口在响应插入时自动滚动 我希望光标在响应插入后移动到下一个提示词处 我希望更改提示词和 LLM 响应的格式 gptel 如何区分用户提示词与 LLM 响应？

我希望窗口在响应插入时自动滚动

我希望光标在响应插入后移动到下一个提示词处

我希望更改提示词和 LLM 响应的格式

gptel 如何区分用户提示词与 LLM 响应？

Transient 菜单行为 我希望设置 gptel 选项，但仅应用于当前缓冲区 我希望保存 Transient 菜单选项，这样只需设置一次 使用 Transient 菜单会留下多余的窗口 可以更改 Transient 菜单的按键绑定吗？（Doom Emacs）由于与 Org mode 存在按键冲突，从 gptel 菜单发送查询失败

我希望设置 gptel 选项，但仅应用于当前缓冲区

我希望保存 Transient 菜单选项，这样只需设置一次

使用 Transient 菜单会留下多余的窗口

可以更改 Transient 菜单的按键绑定吗？

（Doom Emacs）由于与 Org mode 存在按键冲突，从 gptel 菜单发送查询失败

其他问题 我希望以 gptel-send 或选项菜单不支持的方式使用 gptel （ChatGPT）我遇到错误“(HTTP/2 429) You exceeded your current quota” 为什么还要再做一个 LLM 客户端？

我希望以 gptel-send 或选项菜单不支持的方式使用 gptel

（ChatGPT）我遇到错误“(HTTP/2 429) You exceeded your current quota”

为什么还要再做一个 LLM 客户端？

其他配置 选项预设 自动将预设应用于请求

选项预设 自动将预设应用于请求

自动将预设应用于请求

替代方案 使用 gptel 的软件包

注意：gptel 需要 Transient 0.7.8 或更高版本。Transient 是内置软件包，Emacs 默认不会更新它。请确保 package-install-upgrade-built-in 为 true，或者手动更新 Transient。

发布版本：在 Emacs 中执行 M-x package-install ⏎ gptel。

开发快照：将 MELPA 或 NonGNU-devel ELPA 添加到软件包源列表，然后使用 M-x package-install ⏎ gptel 安装。

可选：安装 markdown-mode。

(straight-use-package 'gptel)

注意：gptel 需要 Transient 0.7.8 或更高版本。Transient 是内置软件包，Emacs 默认不会更新它。请确保 package-install-upgrade-built-in 为 true，或者手动更新 Transient。

克隆或下载此仓库，然后对仓库目录运行 M-x package-install-file⏎。

(package! gptel :recipe (:nonrecursive t))

(use-package! gptel
 :config
 (setq! gptel-api-key "your key"))

“your key”可以是 API 密钥本身，也可以是一个返回密钥的函数（更安全）。设置 gptel-api-key 并非必需；如果找不到密钥，系统会要求你输入。

此外，Doom Emacs 还提供了一个由 gptel 驱动的内置 :tools llm 模块。请在 init.el 的 doom! 块中启用它：

(doom! :tools llm)

这会安装 gptel，并提供预配置的按键绑定（<leader> o l）、用于生成提交消息的 magit 集成（在提交缓冲区中使用 M-g），以及 gptel-quick 和 gptel-magit 软件包。运行 doom/help-modules（<leader> h d m）并选择 :tools llm，即可查看完整文档。

在 .spacemacs 文件中，将 llm-client 添加到 dotspacemacs-configuration-layers。

(llm-client :variables
            llm-client-enable-gptel t)

gptel 支持多种 LLM 提供商：

获取一个 OpenAI API 密钥。

可选：将 gptel-api-key 设置为该密钥。你也可以选择更安全的方式，例如：

将其设置为一个返回密钥的自定义函数。

保留默认值 gptel-api-key-from-auth-source 函数，该函数会从 ~/.authinfo 读取密钥。（参见 authinfo 详情）

OpenAI 后端已开箱即用地配置好。如果你想使用其他 LLM 后端（例如 Ollama、Claude/Anthropic 或 Gemini），需要先注册并配置它们。

例如，注册后端通常如下所示：

(gptel-make-anthropic "Claude" :stream t :key gptel-api-key)

注册此后端后，你将在 gptel 的菜单中看到以“Claude:”为前缀的模型名称。

有关你所使用的 LLM 提供商（包括本地 LLM）的详细信息，请参见下文。

你可以使用 Emacs 内置的 authinfo 支持来存储 gptel 所需的 API 密钥。将 API 密钥添加到 ~/.authinfo，并让 gptel-api-key 保持默认值。默认情况下，API 端点的 DNS 名称（例如“api.openai.com”）用作 HOST，“apikey”用作 USER。

machine api.openai.com login apikey password sk-secret-openai-api-key-goes-here
machine api.anthropic.com login apikey password sk-secret-anthropic-api-key-goes-here

或者，你可以使用如下函数，从 Emacs 环境中的变量（例如 OPENAI_API_KEY）获取 API 密钥：

(defun gptel-api-key-from-environment (&optional var)
  (lambda ()
    (getenv (or var                     ;provided key
                (thread-first           ;or fall back to <TYPE>_API_KEY
                  (type-of gptel-backend)
                  (symbol-name)
                  (substring 6)
                  (upcase)
                  (concat "_API_KEY"))))))

然后，在定义后端时，将 :key 设置为相应的环境变量：

(gptel-make-anthropic "My-Claude-backend"
  :key (gptel-api-key-from-environment "ANTHROPIC_API_KEY"))

如果未提供环境变量：

(gptel-make-gemini "My-Gemini-backend"
  :key (gptel-api-key-from-environment))

它会尝试根据后端类型推断密钥，也就是说，使用 Gemini 后端时会尝试使用 GEMINI_API_KEY，其他后端以此类推。

包含对 OpenAI Codex 模型的访问支持。使用以下代码注册后端：

(gptel-make-openai-oauth "OpenAI-sub") ;Any name of your choosing

系统会根据需要提示你登录 OpenAI。（你也可以使用 M-x gptel-openai-oauth-login 手动登录。）

如果通过代理使用它，可以指定主机名、协议等：

(gptel-make-openai-oauth "OpenAI-sub"
  :host "my.openai-proxy.tld"
  :protocol "http")

如需设置更多参数，请参阅 gptel-make-openai-oauth 的文档。

使用 gptel 时，可以从菜单中选择此后端。（参见“用法”。）

上述代码会使该后端可供选择。如果希望将其设为 gptel 的默认后端，可以把它设置为 gptel-backend 的值。请使用以下代码替代上述代码：

(setq gptel-model 'gpt-5.4-mini
      gptel-backend (gptel-make-openai-oauth "OpenAI-sub"))

使用以下代码注册后端：

(gptel-make-azure "Azure-1"             ;Name, whatever you'd like
  :protocol "https"                     ;Optional -- https is the default
  :host "YOUR_RESOURCE_NAME.openai.azure.com"
  :endpoint "/openai/deployments/YOUR_DEPLOYMENT_NAME/chat/completions?api-version=2023-05-15" ;or equivalent
  :stream t                             ;Enable streaming responses
  :key #'gptel-api-key
  :models '(gpt-3.5-turbo gpt-4))

如需设置更多参数，请参阅 gptel-make-azure 的文档。

使用 gptel 时，可以从菜单中选择此后端。（参见“用法”。）

上述代码会使该后端可供选择。如果希望将其设为 gptel 的默认后端，可以把它设置为 gptel-backend 的值。请使用以下代码替代上述代码。

;; OPTIONAL configuration
(setq
 gptel-model 'gpt-3.5-turbo
 gptel-backend (gptel-make-azure "Azure-1"
                 :protocol "https"
                 :host "YOUR_RESOURCE_NAME.openai.azure.com"
                 :endpoint "/openai/deployments/YOUR_DEPLOYMENT_NAME/chat/completions?api-version=2023-05-15"
                 :stream t
                 :key #'gptel-api-key
                 :models '(gpt-3.5-turbo gpt-4)))

使用以下代码注册后端：

(gptel-make-gpt4all "GPT4All"           ;Name of your choosing
 :protocol "http"
 :host "localhost:4891"                 ;Where it's running
 :models '(mistral-7b-openorca.Q4_0.gguf)) ;Available models

以上为必需参数，更多信息请参阅 gptel-make-gpt4all 的文档。

使用 gptel 时，可以从菜单中选择此后端（参见“用法”）。

上述代码会使该后端可供选择。如果希望将其设为 gptel 的默认后端，可以把它设置为 gptel-backend 的值。请使用以下代码替代上述代码。此外，你可能还需要增大响应的 token 数量，因为 GPT4All 默认使用非常短的响应（往往会被截断）。

;; OPTIONAL configuration
(setq
 gptel-max-tokens 500
 gptel-model 'mistral-7b-openorca.Q4_0.gguf
 gptel-backend (gptel-make-gpt4all "GPT4All"
                 :protocol "http"
                 :host "localhost:4891"
                 :models '(mistral-7b-openorca.Q4_0.gguf)))

使用以下代码注册后端：

(gptel-make-ollama "Ollama"             ;Any name of your choosing
  :host "localhost:11434"               ;Where it's running
  :stream t                             ;Stream responses
  :models '(mistral:latest))          ;List of models

以上为必需参数，更多信息请参阅 gptel-make-ollama 的文档。

使用 gptel 时，可以从菜单中选择此后端（参见“用法”）。

上述代码会使该后端可供选择。如果希望将其设为 gptel 的默认后端，可以把它设置为 gptel-backend 的值。请使用以下代码替代上述代码。

;; OPTIONAL configuration
(setq
 gptel-model 'mistral:latest
 gptel-backend (gptel-make-ollama "Ollama"
                 :host "localhost:11434"
                 :stream t
                 :models '(mistral:latest)))

Open WebUI 是一个开源的自托管系统，提供多用户 Web 聊天界面，以及用于访问 LLM 的 API 端点，尤其适合访问运行在 Ollama 等推理服务器上的本地 LLM。

由于它提供了兼容 OpenAI 的端点，因此可以使用 gptel-make-openai 将其注册为后端。

例如，可以使用以下形式，为通过 HTTP 在 3000 端口提供服务的本地 Open WebUI 实例注册后端：

(gptel-make-openai "OpenWebUI"
  :host "localhost:3000"
  :protocol "http"
  :key "KEY_FOR_ACCESSING_OPENWEBUI"
  :endpoint "/api/chat/completions"
  :stream t
  :models '("gemma3n:latest"))

或者，如果你在本地网络中的另一台主机（box.local）上运行 Open WebUI，并通过 HTTPS 和自签名证书提供服务，则可以使用以下配置：

(gptel-make-openai "OpenWebUI"
  :host "box.local"
  :curl-args '("--insecure") ; needed for self-signed certs
  :key "KEY_FOR_ACCESSING_OPENWEBUI"
  :endpoint "/api/chat/completions"
  :stream t
  :models '("gemma3n:latest"))

要在 Open WebUI 中找到 API 密钥，请依次点击左下角的用户名、Settings、Account，然后点击 API Keys 部分中的 Show。

如需了解更多配置选项，请参阅 gptel-make-openai 的文档。

使用 gptel 时，可以从菜单中选择此后端（参见“用法”）。

上述代码会使该后端可供选择。如果希望将其设为 gptel 的默认后端，可以把它设置为 gptel-backend 的值。请使用以下代码替代上述代码。

;; OPTIONAL configuration
(setq
 gptel-model "gemma3n:latest"
 gptel-backend (gptel-make-openai "OpenWebUI"
                 :host "localhost:3000"
                 :protocol "http"
                 :key "KEY_FOR_ACCESSING_OPENWEBUI"
                 :endpoint "/api/chat/completions"
                 :stream t
                 :models '("gemma3n:latest")))

使用以下代码注册后端：

;; :key can be a function that returns the API key.
(gptel-make-gemini "Gemini" :key "YOUR_GEMINI_API_KEY" :stream t)

以上为必需参数，更多信息请参阅 gptel-make-gemini 的文档。

使用 gptel 时，可以从菜单中选择此后端（参见“用法”）。

上述代码会使该后端可供选择。如果希望将其设为 gptel 的默认后端，可以把它设置为 gptel-backend 的值。请使用以下代码替代上述代码。

;; OPTIONAL configuration
(setq
 gptel-model 'gemini-2.5-pro-exp-03-25
 gptel-backend (gptel-make-gemini "Gemini"
                 :key "YOUR_GEMINI_API_KEY"
                 :stream t))

（如果使用 llamafile，请运行服务器模式的 llamafile，而不是“命令行 llamafile”，并使用支持文本生成的模型。）

使用以下代码注册后端：

;; Llama.cpp offers an OpenAI compatible API
(gptel-make-openai "llama-cpp"          ;Any name
  :stream t                             ;Stream responses
  :protocol "http"
  :host "localhost:8000"                ;Llama.cpp server location
  :models '(test))                    ;Any names, doesn't matter for Llama

以上为必需参数，更多信息请参阅 gptel-make-openai 的文档。

使用 gptel 时，可以从菜单中选择此后端（参见“用法”）。

上述代码会使该后端可供选择。如果希望将其设为 gptel 的默认后端，可以把它设置为 gptel-backend 的值。请使用以下代码替代上述代码。

;; OPTIONAL configuration
(setq
 gptel-model   'test
 gptel-backend (gptel-make-openai "llama-cpp"
                 :stream t
                 :protocol "http"
                 :host "localhost:8000"
                 :models '(test)))

Kagi 的 FastGPT 模型和 Universal Summarizer 均受支持。以下是一些注意事项：

Universal Summarizer：如果光标所在位置有 URL，摘要器将对该 URL 的内容进行摘要。否则，发送给模型的上下文与往常相同：从缓冲区开头到光标位置的文本；如果区域处于激活状态，则发送该区域的内容。

Kagi 模型不支持多轮对话，交互是“一次性”的。它们也不支持流式响应。

使用以下代码注册后端：

(gptel-make-kagi "Kagi"                    ;any name
  :key "YOUR_KAGI_API_KEY")                ;can be a function that returns the key

以上是必需参数，更多信息请参阅 gptel-make-kagi 的文档。

使用 gptel 时，你可以从瞬态菜单中选择此后端和模型（fastgpt/summarizer）。

上述代码使该后端可供选择。如果希望将其设为 gptel 的默认后端，可以将其设为 gptel-backend 的值。请使用以下配置替代上述代码。

;; OPTIONAL configuration
(setq
 gptel-model 'fastgpt
 gptel-backend (gptel-make-kagi "Kagi"
                 :key "YOUR_KAGI_API_KEY"))

除 fastgpt 外，还可选择 summarize:cecil、summarize:agnes、summarize:daphne 和 summarize:muriel。各摘要引擎之间的区别已在相关文档中说明。

使用以下代码注册后端：

;; Together.ai offers an OpenAI compatible API
(gptel-make-openai "TogetherAI"         ;Any name you want
  :host "api.together.xyz"
  :key "your-api-key"                   ;can be a function that returns the key
  :stream t
  :models '(;; has many more, check together.ai
            mistralai/Mixtral-8x7B-Instruct-v0.1
            codellama/CodeLlama-13b-Instruct-hf
            codellama/CodeLlama-34b-Instruct-hf))

使用 gptel 时，你可以从菜单中选择此后端（参见“使用方法”）。

上述代码使该后端可供选择。如果希望将其设为 gptel 的默认后端，可以将其设为 gptel-backend 的值。请使用以下配置替代上述代码。

;; OPTIONAL configuration
(setq
 gptel-model   'mistralai/Mixtral-8x7B-Instruct-v0.1
 gptel-backend
 (gptel-make-openai "TogetherAI"         
   :host "api.together.xyz"
   :key "your-api-key"                   
   :stream t
   :models '(;; has many more, check together.ai
             mistralai/Mixtral-8x7B-Instruct-v0.1
             codellama/CodeLlama-13b-Instruct-hf
             codellama/CodeLlama-34b-Instruct-hf)))

使用以下代码注册后端：

;; Anyscale offers an OpenAI compatible API
(gptel-make-openai "Anyscale"           ;Any name you want
  :host "api.endpoints.anyscale.com"
  :key "your-api-key"                   ;can be a function that returns the key
  :models '(;; has many more, check anyscale
            mistralai/Mixtral-8x7B-Instruct-v0.1))

使用 gptel 时，你可以从菜单中选择此后端（参见“使用方法”）。

上述代码使该后端可供选择。如果希望将其设为 gptel 的默认后端，可以将其设为 gptel-backend 的值。请使用以下配置替代上述代码。

;; OPTIONAL configuration
(setq
 gptel-model   'mistralai/Mixtral-8x7B-Instruct-v0.1
 gptel-backend
 (gptel-make-openai "Anyscale"
                 :host "api.endpoints.anyscale.com"
                 :key "your-api-key"
                 :models '(;; has many more, check anyscale
                           mistralai/Mixtral-8x7B-Instruct-v0.1)))

使用以下代码注册后端：

(gptel-make-perplexity "Perplexity"     ;Any name you want
  :key "your-api-key"                   ;can be a function that returns the key
  :stream t)                            ;If you want responses to be streamed

使用 gptel 时，你可以从菜单中选择此后端（参见“使用方法”）。

上述代码使该后端可供选择。如果希望将其设为 gptel 的默认后端，可以将其设为 gptel-backend 的值。请使用以下配置替代上述代码。

;; OPTIONAL configuration
(setq
 gptel-model   'sonar
 gptel-backend (gptel-make-perplexity "Perplexity"
                 :key "your-api-key" :stream t))

使用以下代码注册后端：

(gptel-make-anthropic "Claude"          ;Any name you want
  :stream t                             ;Streaming responses
  :key "your-api-key")

:key 可以是一个返回密钥的函数（更安全）。

使用 gptel 时，你可以从菜单中选择此后端（参见“使用方法”）。

上述代码使该后端可供选择。如果希望将其设为 gptel 的默认后端，可以将其设为 gptel-backend 的值。请使用以下配置替代上述代码。

;; OPTIONAL configuration
(setq
 gptel-model 'claude-3-sonnet-20240229 ;  "claude-3-opus-20240229" also available
 gptel-backend (gptel-make-anthropic "Claude"
                 :stream t :key "your-api-key"))

要以“思考”模式使用 Claude 3.7 Sonnet 模型，可以定义第二个 Claude 后端，并通过 UI 或 elisp 选择它：

(gptel-make-anthropic "Claude-thinking" ;Any name you want
  :key "your-API-key"
  :stream t
  :models '(claude-sonnet-4-20250514 claude-3-7-sonnet-20250219)
  :request-params '(:thinking (:type "enabled" :budget_tokens 2048)
                    :max_tokens 4096))

对于这种用法，你可以在此分别通过 :budget_tokens 和 :max_tokens 键设置推理预算 token 数和最大 token 数。

你可以通过 gptel 的菜单或 gptel-include-reasoning 控制是否以及如何显示推理输出，参见“处理推理内容”。

使用以下代码注册后端：

;; Groq offers an OpenAI compatible API
(gptel-make-openai "Groq"               ;Any name you want
  :host "api.groq.com"
  :endpoint "/openai/v1/chat/completions"
  :stream t
  :key "your-api-key"                   ;can be a function that returns the key
  :models '(gemma-7b-it
            llama3-8b-8192
            mixtral-8x7b-32768
            openai/gpt-oss-20b
            openai/gpt-oss-120b
            qwen/qwen3.6-27b))

使用 gptel 时，你可以从菜单中选择此后端（参见“使用方法”）。请注意，Groq 的速度足够快，因此即使将 :stream 设为 nil，仍然可以获得近乎即时的响应。