vim-ai：把 OpenAI 相容 API 接進 Vim 的 Python 外掛

它解決的不是補全，而是把編輯器變成下指令的地方

多數 Vim 使用者遇到的情境很具體：選取一段文字，想改寫、想修文法、想翻譯，然後切到瀏覽器貼上、等回覆、再貼回來。vim-ai 要消掉的就是這段切換。README 把它定位成「adds Artificial Intelligence (AI) capabilities to your Vim and Neovim」，並列出四類能力：生成文字或程式碼、就地編輯選取文字、與 ChatGPT 互動對話、以及生成圖片。

目標讀者是想留在鍵盤上完成這些事的人，而不是想找一套自動補全引擎的人。這個區別很重要，因為外掛的觸發方式是命令，不是游標停頓。你要打 :AI 或 :AIEdit，或是在視覺模式下先選好範圍再下指令。它假設你已經知道自己要什麼，只是不想離開緩衝區。

另一個常被忽略的定位是：它不綁死 OpenAI。README 明確寫著可以整合「any OpenAI-compatible API」，並建議用 OpenRouter 或在本機架 LiteLLM 當代理，藉此接到 Gemini、Claude 或本地模型。對已經有自架端點的人來說，這代表同一組指令可以指向不同後端。

資料流：你選取的內容才是唯一送出去的東西

README 對資料流的描述相當克制但關鍵：「the plugin does not send any of your code behind the scenes. You only share and pay for what you specifically select, for prompts and chat content.」也就是說，送出的內容等於你選取的範圍加上你打的指令，再加上角色設定裡的前置提示。沒有背景索引，沒有整個專案的掃描。

執行路徑上，外掛需要 Vim 或 Neovim 編入 python3 支援，因為主要語言是 Python。金鑰的取得順序在 README 有兩種寫法：預設讀取 ~/.config/openai.token 檔案，或改用 OPENAI_API_KEY 環境變數；檔案裡也可以寫成「金鑰,組織 ID」的形式。金鑰檔案路徑可以用 g:vim_ai_token_file_path 改掉。

角色（role）是這條資料流上的第二個輸入來源。角色定義在 .ini 檔，透過 g:vim_ai_roles_config_file 指定。README 的範例裡，一個 [grammar] 角色只設了 prompt 與 options.temperature，而 [o1-mini] 這種角色則設了 options.model、options.max_completion_tokens、options.temperature 與 options.initial_prompt。也就是說，角色同時可以攜帶提示詞與 API 參數，並且能用 [o1-mini.chat] 這種區段針對單一指令覆寫，例如把 options.stream 設為 0。

Provider 外掛是後來加上的擴充點。README 說 vim-ai「can now be extended with custom provider plugins」，並承認目前可用的不多，同時列出三個第三方 provider：Google Gemini、OpenAI Responses API 相容、以及帶 MCP 支援的 OpenAI provider。這段等於官方自己標注了生態還在早期。

裝起來會踩到的前置條件

第一個門檻不是外掛本身，是 python3。README 在 Prerequisites 直接寫明需要「Vim or Neovim compiled with python3 support」。如果你用的是發行版套件管理器裝的 Vim，這件事不保證成立，得先確認。這是整篇文件裡最容易讓人卡住的一行。

金鑰的設定有兩種路徑，README 給的指令是：

echo "YOUR_OPENAI_API_KEY" > ~/.config/openai.token

或是：

export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"

若要帶組織 ID，兩者都寫成「金鑰,組織 ID」的形式。要改讀取位置，在 .vimrc 裡設 let g:vim_ai_token_file_path = '~/.config/openai.token'。

外掛本身的安裝，README 提供 vim-plug 的 Plug 'madox2/vim-ai'，以及手動放進 Vim 原生套件目錄的做法：Vim 用 ~/.vim/pack/plugins/start/vim-ai，Neovim 用 ~/.local/share/nvim/site/pack/plugins/start/vim-ai，兩者都是 git clone 進去。

裝好之後日常會用到的指令在 README 列得很清楚：:AI 補完文字、:AIEdit 編輯文字、:AIChat 開啟或接續對話、:AIStopChat 中止回應生成、:AIImage 生成圖片。工具類有 :AIRedo 重複上一個 AI 指令，以及 :AIUtilRolesOpen 開角色設定檔、:AIUtilDebugOn 與 :AIUtilDebugOff 切換除錯記錄。README 也提到可以搭配 range 使用，例如 :%AIE fix grammar 針對整個緩衝區。

角色檔的部分，設好 g:vim_ai_roles_config_file 之後，就能用 :AIEdit /grammar 這種寫法套用角色，也能疊加，例如 :AI /o1-mini /grammar helo world!。

角色檔是這個外掛真正的設定介面

把設定集中到 .ini 是 vim-ai 相對有想法的設計。README 的範例顯示，同一個角色可以同時管提示詞與 API 參數，而且能用子區段針對指令細分。這帶來一個實際好處：你可以為不同任務準備不同模型與不同 temperature，例如文法修正用低溫，創意生成用高溫，切換時只打一個斜線加角色名。

但這裡也是文件最薄的地方。README 只給了 grammar 與 o1-mini 兩個範例，其餘指向 roles-example.ini。哪些 options 鍵是有效的、子區段可以細到什麼層級、多個角色疊加時參數衝突怎麼解，這些在提供的材料裡都沒有完整說明。也就是說，角色檔的威力有多大，取決於你願意花多少時間翻範例檔與原始碼。

還有一個容易誤解的地方：README 提到特殊角色 /populate 與 /populate-all，用來在聊天標題列顯示選項，例如 :AIC /populate /gemini。這暗示聊天介面本身帶有可調參數，但這些參數的完整清單同樣不在主文件裡。對只想打一句話就拿到結果的人來說，這些細節可以忽略；對要把 vim-ai 納入團隊工作流的人來說，這是必須先補齊的一塊。

什麼情況下它會讓你失望

最明顯的限制是前置條件本身。沒有 python3 支援的 Vim，這個外掛完全無法運作，而且這不是設定能繞過的，是編譯層級的事。

第二個限制是它不會自動幫你。README 的指令清單裡沒有行內幽靈文字或自動觸發的補全，觸發點永遠是你下的命令。如果你的期待是像 LSP 那樣的即時建議，vim-ai 的模型不吻合，你會覺得它很被動。

第三個限制是成本與網路。README 直說「Usage of the API is not free」，費用取決於 token 數量，也就是你送出與收到的文字量。它同時強調只送選取內容，這降低了外洩面，但沒有消除成本：一個 :%AIE 對整個緩衝區下指令，送出的就是整個緩衝區。

第四個限制是 provider 生態。README 自己承認可用的第三方 provider 外掛不多，並公開徵求開發者。這代表如果你要接的不是 OpenAI 或 Gemini，而是某個冷門端點，你得自己寫，或退回到 OpenAI 相容代理這條路。

最後一個是角色檔的除錯體驗。文件提供了 :AIUtilDebugOn 與 :AIUtilDebugOff，這說明作者知道設定出錯時需要看記錄，但主文件並沒有描述常見的失敗訊息長什麼樣。

替代路線：代理層與原生外掛的差別

README 自己提出的替代方案是代理層：用 OpenRouter 或在本機架 LiteLLM，把它當成 OpenAI 相容端點，再由 vim-ai 連上去。這條路線的差別在於責任歸屬。vim-ai 只負責把選取內容與指令組成請求，模型路由、金鑰輪替、多家供應商切換全部交給代理層處理。好處是 vim-ai 這一側的設定幾乎不用動；代價是你多了一個要維護的服務，而且它掛掉時編輯器裡的指令會直接失敗。

另一條路線是改用 provider 外掛。README 列出的 Google provider 就是官方推薦的參考實作，作者也請新 provider 的作者開 PR 更新清單。這條路線把供應商差異收進外掛內部，設定留在 Vim 這一側。差別在於你得信任第三方外掛的維護狀況，而 README 對這點並沒有提供任何品質保證。

還有一條是根本不用外掛：直接呼叫 API 再把結果貼回緩衝區。這保留了完全的控制權，但把 vim-ai 想解決的那段切換又加回來了。三條路線的取捨其實是同一個問題：你願意把多少供應商細節放在 Vim 裡面。

維護成本、授權與版本狀態

授權是 MIT，這對商業環境相對友善，但要留意的是外掛本身不包含 API 使用權，OpenAI 或任何代理服務的條款與計費是另一份合約。README 沒有提到任何資料保留政策，只說明了送出範圍。若你的程式碼有合規限制，這一點必須自己向供應商確認，本文無法代為判斷。

維護面上，提供的資料顯示最後一次推送是 2026-03-11，專案未封存，預設分支為 main，主要語言是 Python。這幾項只能說明專案在該時間點仍有活動，不能推論品質或支援速度。資料中沒有檢索到任何 release，這意味著你可能得直接追 main 分支，而不是釘在版本標籤上。對需要可重現建置的團隊來說，這是採用前該先確認的事。

升級成本主要落在兩處：角色檔的 options 鍵，以及 provider 外掛的介面。前者因為是你自己寫的 .ini，改動時要人工比對；後者因為 README 說生態尚在早期，介面若變動，第三方 provider 需要跟著更新。這兩處都不是自動化的，升級前值得先讀 diff。

編輯結論

如果你已經長期在 Vim 或 Neovim 內工作，而且願意維護一份 roles.ini 與一個 OpenAI 相容端點，vim-ai 是少數把生成、就地改寫與聊天三件事都收進同一組指令的外掛，值得裝起來試。若你的環境沒有 python3 支援，或你只想做 LSP 式的行內補全，它就不是對的工具，因為這裡的觸發點是 :AI 與 :AIEdit 這類明確指令，而不是自動提示。採用前先確認三件事：Vim 或 Neovim 是否編入 python3、金鑰要放 ~/.config/openai.token 還是走 OPENAI_API_KEY 環境變數、以及 g:vim_ai_roles_config_file 指向的 .ini 裡選了哪個模型與 max_completion_tokens。這三項沒定下來，後面的成本與行為都無從預估。

官方來源

1. Issues
2. License: MIT
3. madox2/vim-ai on GitHub
4. README