給AI智能體裝上外掛OpenHands MCP服務(wù)器配置完全指南健康檢查與密鑰管理一次講清【免費下載鏈接】OpenHands OpenHands: AI-Driven Development項目地址: https://gitcode.com/GitHub_Trending/ope/OpenHands給 AI 智能體裝上外掛靠的就是 MCPModel Context Protocol模型上下文協(xié)議。它讓 OpenHands 這類 AI 編程智能體能夠連接外部工具服務(wù)器——查數(shù)據(jù)庫、調(diào) API、操作瀏覽器全都變成智能體可以一鍵調(diào)用的手和腳。而 OpenHands 為 MCP 服務(wù)器提供了完整的配置面板、健康檢查與密鑰管理能力三種傳輸方式、一鍵連接測試、OAuth 授權(quán)、自動脫敏的報錯信息新手也能放心配置。上面這張圖就是 OpenHands 的Customize定制區(qū)域左側(cè)導航中的MCP Servers選項正是本篇指南的主戰(zhàn)場。旁邊的 Getting started 列表里也有一項 Connect an MCP integration點進去就進入 MCP 的世界。什么是 MCP 服務(wù)器為什么你的智能體需要它 MCP 可以理解為智能體世界的USB 接口標準智能體是主機MCP 服務(wù)器是外設(shè)每個服務(wù)器通過標準協(xié)議向智能體暴露一組工具Tools智能體在對話中按需調(diào)用這些工具獲得遠超只會寫代碼的能力。OpenHands 支持三種接入方式見 mcp-server.ts類型適用場景需要填什么stdio本地命令行工具npm/pip 安裝后啟動命令 command 參數(shù) args 環(huán)境變量 envsse遠程服務(wù)器Server-Sent Events 協(xié)議URL 請求頭 headersshttp遠程服務(wù)器Streamable HTTP新一代標準URL 請求頭 headers本地開發(fā)環(huán)境Local backend下連接測試會在你的 agent-server 上真實地啟動命令或發(fā)起連接結(jié)果可信云端模式下則跳過本地探測直接保存失敗會在對話運行時暴露實現(xiàn)見 mcp-service.api.ts。一鍵安裝從市場裝服務(wù)器或手動添加自定義服務(wù)器 OpenHands 的 MCP 頁面路由定義在 mcp.tsx分兩區(qū)Marketplace市場瀏覽、搜索、篩選現(xiàn)成的 MCP 服務(wù)器點卡片即可安裝OAuth 類服務(wù)器還能直接彈出授權(quán)窗口Installed已安裝卡片式管理已裝服務(wù)器——測試連接、查看健康狀態(tài)、編輯、刪除。市場卡片與已安裝卡片分別由 marketplace-card.tsx 和 installed-server-card.tsx 渲染。添加/刪除服務(wù)器走的是專門的 mutation 鉤子use-add-mcp-server.ts、use-delete-mcp-server.ts。幾個值得知道的細節(jié)規(guī)格來自 specs/mcp-settings.md稀疏變更增/改/刪某個服務(wù)器時只會提交包含該服務(wù)器的請求其他服務(wù)器及其密鑰原樣保留不會被順手覆蓋改密鑰要顯式不填保留原值填了替換清空刪除界面上的脫敏占位符永遠不會被當作真實數(shù)據(jù)提交回去。健康檢查四種狀態(tài)一眼看懂服務(wù)器是否靠譜 每個已安裝服務(wù)器卡片上都有一個健康指示燈狀態(tài)模型定義在 mcp-health.ts狀態(tài)含義你該做什么unchecked還沒檢查過點一下測試按鈕checking正在探測稍等OAuth 類最長約 120 秒healthy / verified連接成功且只讀探針工具調(diào)用成功密鑰真實有效 ?放心用healthy / connectivity-only能連上、能列出工具但沒做密鑰級驗證基本可用注意權(quán)限類報錯failed檢查失敗附分類錯誤按kind對癥處理核心邏輯在 probe-mcp-server-health.ts 中調(diào)用McpService.testServer做非破壞性連接探測再解讀結(jié)果。verified 為什么更高級對目錄中帶有只讀探針工具的服務(wù)器例如一個只讀查詢 API 的工具OpenHands 會真的調(diào)用一次該工具。調(diào)用成功說明密鑰不只是格式對了而是真的能用——這就是verified與connectivity-only的區(qū)別界面會如實標注絕不悄悄升級。失敗時的智能歸類如果錯誤文本里出現(xiàn) 401/403、unauthorized、invalid token 等字樣系統(tǒng)會自動把錯誤歸類為credentials密鑰問題提示你檢查憑證而不是讓你對著一個連接失敗瞎猜同樣見 probe-mcp-server-health.ts。界面?zhèn)鹊挠嗛喤c探測動作由 use-mcp-server-health.ts 提供卡片實時跟隨狀態(tài)變化改完配置點一下就會重新探測。密鑰管理你的 Token 如何被保護 MCP 配置里最常填的就是密鑰。OpenHands 對它的處理可以總結(jié)成三層1. 四種認證策略auth在 mcp-auth.ts 定義表單側(cè)實現(xiàn)在 mcp-server-form.tsxapi_key標準 API 密鑰頭bearerAuthorization: Bearer tokenbasic用戶名 密碼header自定義請求頭最靈活oauth2完整 OAuth 2.0 流程支持彈出授權(quán)窗口、回調(diào)提交與狀態(tài)輪詢見 mcp-service.api.ts并內(nèi)置 120 秒超時保護。2. 加密存儲 脫敏顯示密鑰在設(shè)置中加密往返瀏覽器里拿到的多是脫敏占位值REDACTED真實值只在服務(wù)端解密界面上每個敏感字段旁有Also save as secret開關(guān)save-as-secret-toggle.tsx勾選后該字段值同時進入密鑰管理體系表單對密鑰做了專門的合法性校驗見 mcp-credential-validation.ts。3. 報錯自動脫敏安全網(wǎng)即使密鑰加密存儲后端錯誤信息仍可能回聲出明文 token。redact-mcp-secrets.ts 會收集該服務(wù)器配置中所有可能的密鑰值env、headers、auth、甚至 URL 中內(nèi)嵌的用戶名/密碼/查詢參數(shù)從錯誤文本里逐個替換成占位符再用通用模式兜底識別 GitHub PAT、Slack token、JWT 等常見格式。也就是說你在界面上看到的任何一條報錯都是脫敏版密鑰不會意外暴露。實戰(zhàn)排錯清單連接失敗先查這5處 ?癥狀最可能原因處理建議credentials類失敗 / 401/403密鑰錯誤或過期重新生成 tokenOAuth 類點重新授權(quán)connection失敗URL 拼錯、端口不通、服務(wù)器沒啟動本地服務(wù)器確認 command 能手動跑通遠程確認可訪問連接成功但對話中工具報錯密鑰權(quán)限不足對照服務(wù)器文檔補權(quán)限此時健康狀態(tài)多為 connectivity-onlyOAuth 一直轉(zhuǎn)圈授權(quán)窗口未點確認 / 回調(diào)被攔截確認彈窗內(nèi)完成登錄授權(quán)別關(guān)窗口云端模式保存后行為異常云端不暴露本地探測預(yù)期行為具體失敗會在運行時可見錯誤文案到用戶友好提示的映射參考 mcp-test-error-message.ts 與 mcp-health.ts。寫在最后小工具大杠桿 花十分鐘配置好一個 MCP 服務(wù)器你的 AI 智能體就多了一整套外掛技能。OpenHands 把最容易翻車的兩個環(huán)節(jié)——健康檢查與密鑰管理——做到了開箱即用verified 級別的真實驗證、連接級與密鑰級狀態(tài)區(qū)分、加密存儲加報錯脫敏的安全閉環(huán)。下一步可以試試在 Customize → MCP Servers 里裝上第一個服務(wù)器看著它的健康燈從灰色變成綠色——那一刻你的智能體就完成了身體升級。更多開發(fā)背景可閱讀 docs/README.md 與 docs/architecture.md。【免費下載鏈接】OpenHands OpenHands: AI-Driven Development項目地址: https://gitcode.com/GitHub_Trending/ope/OpenHands創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考