一大模型集成平臺(tái)部署與配置實(shí)戰(zhàn)指南)
1. 項(xiàng)目概述為什么需要一個(gè)統(tǒng)一的大模型集成平臺(tái)如果你最近在折騰大語言模型不管是想用本地部署的 Llama 3 跑點(diǎn)私活還是想調(diào)用云端的 GPT-4 處理復(fù)雜任務(wù)大概率會(huì)面臨一個(gè)頭疼的問題切換成本太高。每個(gè)平臺(tái)都有自己的 API 格式、認(rèn)證方式和計(jì)費(fèi)規(guī)則寫一套代碼適配一個(gè)模型換一個(gè)就得重寫調(diào)試起來更是費(fèi)時(shí)費(fèi)力。這感覺就像家里每個(gè)電器都得配一個(gè)專屬插座麻煩不說還占地方。OpenClaw 就是為了解決這個(gè)“插座不通用”的問題而生的。你可以把它理解為一個(gè)“萬能適配器”或者“智能接線板”。它的核心目標(biāo)很簡(jiǎn)單讓你用一套統(tǒng)一的、簡(jiǎn)單的接口去調(diào)用背后五花八門的大模型服務(wù)。無論是你本地電腦上用 Ollama 跑的 Mistral還是通過 OpenRouter 聚合的 Claude、GPT-4甚至是公司內(nèi)網(wǎng)的私有模型在 OpenClaw 這里它們都被抽象成了同一個(gè)“模型”概念。你只需要告訴 OpenClaw“用這個(gè)模型處理這段文本”它就會(huì)幫你處理好所有繁瑣的通信、格式轉(zhuǎn)換和錯(cuò)誤重試。我最初接觸 OpenClaw 是因?yàn)閳F(tuán)隊(duì)內(nèi)部模型使用混亂。有人寫腳本調(diào) OpenAI有人用 curl 測(cè)試 Ollama還有人在研究如何接入國內(nèi)的大模型平臺(tái)。代碼重復(fù)、密鑰管理混亂、響應(yīng)格式不統(tǒng)一維護(hù)起來簡(jiǎn)直是噩夢(mèng)。OpenClaw 的出現(xiàn)讓我們終于可以把所有模型的調(diào)用收斂到一個(gè)標(biāo)準(zhǔn)化、可維護(hù)的服務(wù)里。這次實(shí)踐我就帶你從零開始打通從本地 Ollama 到云端 OpenRouter 的完整鏈路讓你也能輕松駕馭這個(gè)強(qiáng)大的集成工具。2. 核心設(shè)計(jì)思路OpenClaw 的架構(gòu)與核心概念拆解在動(dòng)手之前我們得先搞清楚 OpenClaw 是怎么工作的。它不是另一個(gè)大模型而是一個(gè)中間層一個(gè)代理。理解它的架構(gòu)能幫你更好地使用它甚至在出問題時(shí)快速定位。2.1 核心架構(gòu)路由、適配與統(tǒng)一OpenClaw 的架構(gòu)可以清晰地分為三層接口層、路由與適配層、供應(yīng)商層。接口層是你與 OpenClaw 交互的地方。它通常提供一個(gè)兼容 OpenAI API 格式的 HTTP 接口。這意味著如果你之前寫過調(diào)用chat.completions.create的代碼那么幾乎不用修改只需要把請(qǐng)求的base_url指向你的 OpenClaw 服務(wù)地址就能無縫切換。這極大地降低了遷移和學(xué)習(xí)的成本。路由與適配層是 OpenClaw 的大腦。這是最核心的部分它主要做兩件事路由根據(jù)你的請(qǐng)求比如你在代碼里指定的model參數(shù)是gpt-4還是llama3:8b決定這個(gè)請(qǐng)求應(yīng)該轉(zhuǎn)發(fā)給后端的哪個(gè)具體的模型服務(wù)。適配將你發(fā)送的標(biāo)準(zhǔn) OpenAI 格式的請(qǐng)求“翻譯”成后端目標(biāo)模型服務(wù)能理解的格式。比如發(fā)給 Ollama 的請(qǐng)求體和發(fā)給 Anthropic Claude 的請(qǐng)求體結(jié)構(gòu)是不同的OpenClaw 負(fù)責(zé)完成這個(gè)轉(zhuǎn)換。同樣它也會(huì)把各個(gè)供應(yīng)商返回的、五花八門的響應(yīng)統(tǒng)一“翻譯”回標(biāo)準(zhǔn)的 OpenAI 格式返回給你。供應(yīng)商層就是實(shí)際提供模型能力的后端服務(wù)比如本地運(yùn)行的 Ollama 服務(wù)器、OpenRouter 的 API 網(wǎng)關(guān)、或是直接配置的 OpenAI、Anthropic 等。這種設(shè)計(jì)的精妙之處在于“解耦”。你的應(yīng)用程序只和 OpenClaw 的標(biāo)準(zhǔn)接口對(duì)話完全不用關(guān)心后端是哪個(gè)模型、在哪里運(yùn)行。你想把llama3:8b換成claude-3-haiku只需要在 OpenClaw 的配置里改一個(gè)映射關(guān)系你的應(yīng)用代碼一行都不用動(dòng)。2.2 關(guān)鍵概念模型、供應(yīng)商與路由映射要配置 OpenClaw必須理解這三個(gè)核心概念它們構(gòu)成了配置文件的骨架。模型這是你給應(yīng)用程序暴露的抽象概念。你可以起任何名字比如my-fast-chat、code-expert。這個(gè)名稱對(duì)你和你的應(yīng)用有意義即可。供應(yīng)商這是實(shí)際提供模型計(jì)算能力的后端平臺(tái)。OpenClaw 預(yù)置了眾多供應(yīng)商的實(shí)現(xiàn)如openai、anthropic、ollama、openrouter、azure-openai等。每個(gè)供應(yīng)商都需要配置對(duì)應(yīng)的 API 密鑰、Base URL 等連接信息。路由映射這是連接“模型”和“供應(yīng)商”的橋梁。它告訴 OpenClaw“當(dāng)用戶請(qǐng)求名為my-fast-chat的模型時(shí)請(qǐng)將其路由到openrouter這個(gè)供應(yīng)商并且使用該供應(yīng)商平臺(tái)上名為claude-3-haiku的實(shí)際模型”。一個(gè)簡(jiǎn)單的映射關(guān)系看起來是這樣的my-fast-chat (應(yīng)用程序使用的模型名) - openrouter (供應(yīng)商) - claude-3-haiku (供應(yīng)商處的真實(shí)模型名)注意這里有一個(gè)初學(xué)者極易混淆的點(diǎn)。在配置 OpenRouter 或 Azure OpenAI 時(shí)你實(shí)際上需要配置兩次“模型名”。一次是在供應(yīng)商配置里指定該供應(yīng)商平臺(tái)上的“默認(rèn)模型”或“模型列表”另一次是在路由映射里精確指定使用哪個(gè)模型。很多配置錯(cuò)誤都源于此。3. 環(huán)境準(zhǔn)備與 OpenClaw 部署實(shí)戰(zhàn)理論清楚了我們開始動(dòng)手。部署 OpenClaw 有多種方式從最簡(jiǎn)單的 Docker 一鍵部署到從源碼編譯我們將覆蓋最實(shí)用的兩種。3.1 基礎(chǔ)環(huán)境與依賴檢查無論選擇哪種部署方式你的機(jī)器上都需要具備以下基礎(chǔ)環(huán)境Docker 與 Docker Compose這是目前最推薦、最無痛的部署方式。確保你的 Docker 守護(hù)進(jìn)程正在運(yùn)行。# 檢查 Docker 和 Docker Compose 版本 docker --version docker-compose --version如果未安裝請(qǐng)根據(jù)你的操作系統(tǒng)Ubuntu/CentOS/macOS參考官方文檔安裝。對(duì)于國內(nèi)用戶務(wù)必配置 Docker 鏡像加速器否則拉取鏡像會(huì)非常緩慢。Git用于克隆項(xiàng)目倉庫?？捎玫木W(wǎng)絡(luò)OpenClaw 需要訪問互聯(lián)網(wǎng)以下載 Docker 鏡像以及后續(xù)連接云端供應(yīng)商如 OpenRouter。如果部署在受限網(wǎng)絡(luò)環(huán)境需要提前準(zhǔn)備好代理或鏡像。3.2 方案一使用 Docker Compose 快速部署推薦這是最快、最標(biāo)準(zhǔn)化、最易于維護(hù)的部署方式。OpenClaw 官方提供了完善的docker-compose.yml文件。步驟 1獲取部署文件# 克隆 OpenClaw 倉庫如果網(wǎng)絡(luò)不暢可以在 GitHub 上直接下載 ZIP 包 git clone https://github.com/openclaw-ai/openclaw.git cd openclaw步驟 2配置環(huán)境變量OpenClaw 的核心配置通過環(huán)境變量文件.env管理。首先復(fù)制示例文件cp .env.example .env然后用文本編輯器打開.env文件。你需要重點(diǎn)關(guān)注以下幾個(gè)變量OPENCLAW_HOST服務(wù)綁定的主機(jī)默認(rèn)0.0.0.0即可表示監(jiān)聽所有網(wǎng)絡(luò)接口。OPENCLAW_PORT服務(wù)端口默認(rèn)3000。確保該端口沒有被其他程序占用。OPENCLAW_LOG_LEVEL日志級(jí)別開發(fā)調(diào)試可以設(shè)為DEBUG生產(chǎn)環(huán)境建議INFO。OPENCLAW_CONFIG_FILE配置文件路徑Docker 部署時(shí)通常映射到容器內(nèi)的/app/config.yaml我們稍后配置。步驟 3準(zhǔn)備配置文件Docker Compose 文件已經(jīng)將宿主機(jī)的./config目錄映射到了容器內(nèi)的/app/config。所以我們只需要在項(xiàng)目根目錄下創(chuàng)建config文件夾并在里面放置我們的config.yaml。mkdir -p config touch config/config.yaml現(xiàn)在先讓config.yaml空著我們會(huì)在下一章詳細(xì)填充內(nèi)容。步驟 4啟動(dòng)服務(wù)在項(xiàng)目根目錄即有docker-compose.yml的目錄下執(zhí)行docker-compose up -d-d參數(shù)表示在后臺(tái)運(yùn)行。首次運(yùn)行會(huì)拉取 OpenClaw 的 Docker 鏡像可能需要一些時(shí)間。步驟 5驗(yàn)證服務(wù)服務(wù)啟動(dòng)后可以通過以下命令檢查狀態(tài)和日志# 查看容器狀態(tài) docker-compose ps # 查看實(shí)時(shí)日志 docker-compose logs -f openclaw # 測(cè)試接口是否通暢 curl http://localhost:3000/v1/models如果看到返回一個(gè) JSON 格式的模型列表初始可能是空的說明 OpenClaw 服務(wù)已經(jīng)成功運(yùn)行。實(shí)操心得使用 Docker 部署時(shí)經(jīng)常遇到權(quán)限問題導(dǎo)致配置文件無法讀取。一個(gè)排查技巧是進(jìn)入容器內(nèi)部檢查文件是否存在且內(nèi)容正確docker exec -it openclaw-openclaw-1 cat /app/config/config.yaml。另外修改config.yaml后需要重啟容器才能生效docker-compose restart openclaw。3.3 方案二從源碼安裝與運(yùn)行如果你需要深度定制或想在非 Docker 環(huán)境運(yùn)行可以選擇源碼安裝。前提條件確保系統(tǒng)已安裝Python 3.10和Pip。步驟 1克隆并安裝依賴git clone https://github.com/openclaw-ai/openclaw.git cd openclaw pip install -e . # 使用開發(fā)模式安裝方便修改代碼 # 或者安裝生產(chǎn)依賴 # pip install -r requirements.txt步驟 2配置與運(yùn)行同樣需要準(zhǔn)備.env文件和config.yaml文件放置于項(xiàng)目根目錄或指定路徑。 然后通過環(huán)境變量指定配置文件路徑并啟動(dòng)export OPENCLAW_CONFIG_FILE./config.yaml openclaw run或者直接使用命令參數(shù)openclaw run --config ./config.yaml避坑指南源碼安裝最常見的問題是 Python 環(huán)境沖突。強(qiáng)烈建議使用venv或conda創(chuàng)建獨(dú)立的虛擬環(huán)境。此外某些依賴如httpx,pydantic的特定版本可能存在兼容性問題如果啟動(dòng)報(bào)錯(cuò)可以嘗試根據(jù)錯(cuò)誤信息調(diào)整requirements.txt中的版本號(hào)。4. 核心配置解析連接 Ollama 與 OpenRouter服務(wù)跑起來了但現(xiàn)在是“光桿司令”背后沒有可用的模型。接下來就是最關(guān)鍵的步驟編寫config.yaml配置文件把本地 Ollama 和云端 OpenRouter 接進(jìn)來。4.1 配置本地 Ollama 供應(yīng)商首先確保你的本地已經(jīng)安裝并運(yùn)行了 Ollama。你可以在終端執(zhí)行ollama serve來啟動(dòng)服務(wù)它默認(rèn)監(jiān)聽11434端口。然后編輯config.yaml文件# config.yaml # 1. 定義供應(yīng)商 providers: # 定義一個(gè)名為 local-ollama 的供應(yīng)商類型是 ollama - id: local-ollama type: ollama config: # Ollama 服務(wù)的地址如果 Ollama 運(yùn)行在本機(jī)就是這個(gè)地址 api_base: http://host.docker.internal:11434 # Ollama 通常不需要 API 密鑰除非你配置了身份驗(yàn)證 api_key: # 可選的模型列表用于發(fā)現(xiàn)和健康檢查 models: - id: llama3:8b name: Meta Llama 3 8B - id: mistral:7b name: Mistral 7B - id: qwen2.5:7b name: Qwen 2.5 7B # 2. 定義路由規(guī)則 routes: # 當(dāng)請(qǐng)求的模型名是 llama3 時(shí)路由到 local-ollama 供應(yīng)商并使用其下的 llama3:8b 模型 - name: llama3 provider: local-ollama model: llama3:8b # 另一個(gè)路由規(guī)則 - name: mistral provider: local-ollama model: mistral:7b關(guān)鍵點(diǎn)解析api_base: 這里使用了host.docker.internal。這是一個(gè) Docker 內(nèi)部的主機(jī)名指向宿主機(jī)的本地網(wǎng)絡(luò)。因?yàn)?OpenClaw 運(yùn)行在 Docker 容器內(nèi)要訪問宿主機(jī)的 Ollama 服務(wù)必須用這個(gè)地址。如果你是源碼直接運(yùn)行這里應(yīng)改為http://localhost:11434。models: 這個(gè)列表不是必須的但它有助于 OpenClaw 的管理界面如果有展示可用模型并進(jìn)行前置的健康檢查。routes:name是你自定義的、暴露給應(yīng)用調(diào)用的模型標(biāo)識(shí)符。model必須與 Ollama 中拉取ollama pull的模型名稱完全一致。保存配置后重啟 OpenClaw 服務(wù)docker-compose restart openclaw?，F(xiàn)在你的應(yīng)用就可以通過向http://localhost:3000/v1/chat/completions發(fā)送請(qǐng)求并指定model參數(shù)為llama3來調(diào)用本地的 Llama 3 8B 模型了。4.2 配置云端 OpenRouter 供應(yīng)商OpenRouter 是一個(gè)聚合了眾多主流大模型如 GPT-4, Claude, Gemini 等的 API 平臺(tái)使用統(tǒng)一的接口和計(jì)費(fèi)。首先你需要去 OpenRouter 官網(wǎng)注冊(cè)賬號(hào)并獲取 API Key。獲取 OpenRouter API Key:訪問 OpenRouter 官網(wǎng)并登錄。在控制臺(tái)找到API Keys部分。創(chuàng)建一個(gè)新的 Key并妥善保存。配置config.yaml: 我們?cè)趧偛诺呐渲没A(chǔ)上添加 OpenRouter 供應(yīng)商和路由。# config.yaml (續(xù)接上一部分) providers: - id: local-ollama type: ollama config: api_base: http://host.docker.internal:11434 models: - id: llama3:8b name: Meta Llama 3 8B - id: mistral:7b name: Mistral 7B # 新增 OpenRouter 供應(yīng)商 - id: cloud-openrouter type: openrouter config: # OpenRouter 的 API 端點(diǎn) api_base: https://openrouter.ai/api/v1 # 替換成你從官網(wǎng)獲取的真實(shí) API Key api_key: sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # 可選為通過 OpenRouter 發(fā)出的請(qǐng)求添加自定義請(qǐng)求頭例如指定推薦來源 # headers: # X-Title: My Awesome App # 可以在這里預(yù)定義一些 OpenRouter 上的模型但不是必須的 # models: # - id: openai/gpt-4-turbo # - id: anthropic/claude-3-haiku routes: - name: llama3 provider: local-ollama model: llama3:8b - name: mistral provider: local-ollama model: mistral:7b # 新增 OpenRouter 路由規(guī)則 - name: gpt4 # 給你的應(yīng)用使用的名字 provider: cloud-openrouter # 這里的 model 必須是 OpenRouter 支持的完整模型標(biāo)識(shí)符 model: openai/gpt-4-turbo - name: fast-claude provider: cloud-openrouter model: anthropic/claude-3-haiku - name: smart-gemini provider: cloud-openrouter model: google/gemini-pro配置要點(diǎn)與避坑模型標(biāo)識(shí)符必須精確OpenRouter 的模型 ID 格式通常是供應(yīng)商/模型名如openai/gpt-4-turbo。一定要去 OpenRouter 的模型列表頁面核對(duì)準(zhǔn)確的 ID寫錯(cuò)一個(gè)字都會(huì)導(dǎo)致路由失敗。API Key 安全永遠(yuǎn)不要將真實(shí)的 API Key 提交到版本控制系統(tǒng)如 Git。.env文件通常被.gitignore忽略但config.yaml可能不會(huì)。最佳實(shí)踐是將api_key作為環(huán)境變量注入?？梢孕薷呐渲脼閏onfig: api_base: https://openrouter.ai/api/v1 api_key: ${OPENROUTER_API_KEY} # 從環(huán)境變量讀取然后在.env文件中設(shè)置OPENROUTER_API_KEYsk-or-v1-...。網(wǎng)絡(luò)連通性確保部署 OpenClaw 的服務(wù)器能夠訪問https://openrouter.ai。對(duì)于國內(nèi)服務(wù)器這可能是一個(gè)挑戰(zhàn)需要自行解決網(wǎng)絡(luò)問題。配置完成后再次重啟 OpenClaw。現(xiàn)在你的服務(wù)就同時(shí)具備了調(diào)用本地輕量模型和云端頂級(jí)模型的能力。5. 應(yīng)用集成與調(diào)用實(shí)戰(zhàn)配置好了我們來實(shí)際調(diào)用一下看看效果。OpenClaw 兼容 OpenAI API所以我們可以使用任何 OpenAI SDK 來調(diào)用。5.1 使用 Python 進(jìn)行調(diào)用這里以最常用的openaiPython 庫為例。首先安裝庫pip install openai。# test_openclaw.py from openai import OpenAI import os # 初始化客戶端將 base_url 指向你的 OpenClaw 服務(wù) client OpenAI( base_urlhttp://localhost:3000/v1, # OpenClaw 的兼容端點(diǎn) api_keynot-needed # OpenClaw 如果未啟用鑒權(quán)這里可以填任意值。如果配置了全局鑒權(quán)則需填寫對(duì)應(yīng)的密鑰。 ) # 1. 調(diào)用本地 Ollama 的 Llama 3 模型 print( 調(diào)用本地 Llama3 ) try: response client.chat.completions.create( modelllama3, # 對(duì)應(yīng) config.yaml 中 routes 的 name messages[ {role: user, content: 用一句話介紹你自己。} ], max_tokens100, streamFalse # 先測(cè)試非流式 ) print(response.choices[0].message.content) except Exception as e: print(f調(diào)用失敗: {e}) # 2. 調(diào)用云端 OpenRouter 的 GPT-4 模型 print(\n 調(diào)用云端 GPT-4 ) try: response client.chat.completions.create( modelgpt4, # 對(duì)應(yīng) config.yaml 中 routes 的 name messages[ {role: user, content: 什么是量子計(jì)算用通俗的語言解釋。} ], max_tokens150, streamFalse ) print(response.choices[0].message.content) except Exception as e: print(f調(diào)用失敗: {e}) # 3. 測(cè)試流式響應(yīng)更適合生成長文本 print(\n 流式調(diào)用 Claude Haiku ) try: stream client.chat.completions.create( modelfast-claude, messages[ {role: user, content: 寫一首關(guān)于春天的五言絕句。} ], max_tokens50, streamTrue # 開啟流式 ) for chunk in stream: if chunk.choices[0].delta.content is not None: print(chunk.choices[0].delta.content, end, flushTrue) print() # 換行 except Exception as e: print(f\n流式調(diào)用失敗: {e})運(yùn)行這個(gè)腳本python test_openclaw.py你應(yīng)該能看到分別來自本地模型和云端模型的回復(fù)。這直觀地證明了 OpenClaw 的統(tǒng)一網(wǎng)關(guān)作用。5.2 在現(xiàn)有項(xiàng)目中集成如果你已經(jīng)有一個(gè)使用 OpenAI SDK 的項(xiàng)目集成 OpenClaw 簡(jiǎn)單到令人發(fā)指。通常只需要修改一行代碼——初始化客戶端時(shí)的base_url。之前直連 OpenAI:client OpenAI(api_keyyour-openai-key)之后通過 OpenClaw:client OpenAI( base_urlhttp://your-openclaw-server:3000/v1, api_keyyour-openclaw-global-key # 如果 OpenClaw 配置了鑒權(quán) )你項(xiàng)目里所有調(diào)用client.chat.completions.create、client.embeddings.create等方法的代碼都無需改動(dòng)只需要通過model參數(shù)指定你在 OpenClaw 中配置的路由名稱如llama3,gpt4即可。這種無縫切換的能力對(duì)于 A/B 測(cè)試不同模型、或在模型服務(wù)故障時(shí)快速降級(jí)到備用模型具有巨大的價(jià)值。6. 高級(jí)配置與生產(chǎn)級(jí)優(yōu)化基礎(chǔ)功能跑通后我們可以看看如何讓 OpenClaw 更強(qiáng)大、更穩(wěn)定適用于生產(chǎn)環(huán)境。6.1 負(fù)載均衡與故障轉(zhuǎn)移當(dāng)某個(gè)模型調(diào)用量很大或者為了高可用你可能需要配置負(fù)載均衡。OpenClaw 支持在路由級(jí)別配置多個(gè)供應(yīng)商端點(diǎn)。例如假設(shè)你有兩個(gè)都部署了llama3:8b模型的 Ollama 服務(wù)可能在不同的機(jī)器上你可以這樣配置providers: - id: ollama-server-1 type: ollama config: api_base: http://192.168.1.100:11434 - id: ollama-server-2 type: ollama config: api_base: http://192.168.1.101:11434 routes: - name: llama3-loadbalanced # 使用負(fù)載均衡策略 strategy: load_balance targets: - provider: ollama-server-1 model: llama3:8b weight: 1 # 權(quán)重 - provider: ollama-server-2 model: llama3:8b weight: 1 # 兩個(gè)服務(wù)器權(quán)重相同平均分配流量strategy還可以設(shè)置為failover故障轉(zhuǎn)移這樣當(dāng)?shù)谝粋€(gè)供應(yīng)商失敗時(shí)會(huì)自動(dòng)嘗試第二個(gè)提高了服務(wù)的魯棒性。6.2 速率限制與成本控制對(duì)接云端 API成本和用量控制至關(guān)重要。OpenClaw 允許你為路由設(shè)置速率限制和預(yù)算。routes: - name: gpt4-limited provider: cloud-openrouter model: openai/gpt-4-turbo # 速率限制每分鐘最多 10 次請(qǐng)求每秒最多 2 次 rate_limit: requests_per_minute: 10 requests_per_second: 2 # 成本控制設(shè)置每個(gè)用戶或全局的預(yù)算如果供應(yīng)商支持成本信息 # budget: # 此功能可能依賴供應(yīng)商接口和 OpenClaw 版本 # max_amount: 10.00 # 最大花費(fèi) 10 美元 # currency: USD這可以有效防止某個(gè)接口被意外刷爆導(dǎo)致巨額賬單。6.3 請(qǐng)求/響應(yīng)轉(zhuǎn)換與中間件這是 OpenClaw 非常強(qiáng)大的一個(gè)功能。你可以在請(qǐng)求到達(dá)供應(yīng)商前或響應(yīng)返回給客戶端前對(duì)數(shù)據(jù)進(jìn)行修改。場(chǎng)景示例 1為所有發(fā)送給 OpenRouter 的請(qǐng)求添加系統(tǒng)提示。routes: - name: claude-with-system provider: cloud-openrouter model: anthropic/claude-3-sonnet request_transforms: - type: add_message # 添加消息 config: message: role: system content: 你是一個(gè)專業(yè)的翻譯官請(qǐng)將所有用戶的輸入翻譯成英文后再進(jìn)行回答。 position: prepend # 添加到消息列表開頭場(chǎng)景示例 2攔截包含敏感詞的請(qǐng)求。routes: - name: safe-chat provider: local-ollama model: llama3:8b request_transforms: - type: block_if_contains # 如果包含則阻塞 config: contains: [敏感詞1, 敏感詞2] message: 請(qǐng)求包含不當(dāng)內(nèi)容已被攔截。 # 返回給客戶端的消息場(chǎng)景示例 3統(tǒng)一所有響應(yīng)的格式。response_transforms: - type: set_metadata # 設(shè)置元數(shù)據(jù) config: key: processed_by value: openclaw_gateway通過這些轉(zhuǎn)換器你可以實(shí)現(xiàn)審計(jì)、內(nèi)容過濾、數(shù)據(jù)標(biāo)準(zhǔn)化、A/B測(cè)試分流等復(fù)雜邏輯而無需修改客戶端或供應(yīng)商的代碼。7. 監(jiān)控、日志與問題排查一個(gè)穩(wěn)定的服務(wù)離不開可觀測(cè)性。OpenClaw 提供了多種方式來監(jiān)控其運(yùn)行狀態(tài)。7.1 內(nèi)置健康檢查與指標(biāo)OpenClaw 通常提供以下端點(diǎn)GET /health基礎(chǔ)健康檢查返回服務(wù)狀態(tài)。GET /metricsPrometheus 格式的指標(biāo)端點(diǎn)如果啟用可以監(jiān)控請(qǐng)求量、延遲、錯(cuò)誤率等。GET /v1/models列出當(dāng)前配置的所有可用路由模型。定期調(diào)用這些端點(diǎn)或?qū)⑵浼傻侥愕谋O(jiān)控系統(tǒng)如 Prometheus Grafana中是保障服務(wù)穩(wěn)定的基礎(chǔ)。7.2 日志分析OpenClaw 的日志是排查問題的第一手資料。通過docker-compose logs -f openclaw或查看日志文件你可以看到詳細(xì)的請(qǐng)求處理流程。關(guān)鍵日志模式Routing request to model: XXXX看到這個(gè)說明請(qǐng)求已進(jìn)入并確定了路由目標(biāo)。Calling provider: XXXX with model: YYYY正在調(diào)用具體的供應(yīng)商。Provider XXX returned status: 200供應(yīng)商調(diào)用成功。Provider XXX returned error: ...供應(yīng)商調(diào)用失敗錯(cuò)誤信息會(huì)在這里顯示這是診斷問題的關(guān)鍵。將日志級(jí)別設(shè)為DEBUG可以獲得更詳細(xì)的信息包括完整的請(qǐng)求和響應(yīng)體注意可能包含敏感數(shù)據(jù)生產(chǎn)環(huán)境慎用。7.3 常見問題排查清單以下是我在實(shí)戰(zhàn)中遇到的一些典型問題及解決方法問題現(xiàn)象可能原因排查步驟調(diào)用/v1/models返回空列表1. 配置文件路徑錯(cuò)誤2. 配置文件語法錯(cuò)誤YAML格式3. 服務(wù)未成功加載配置1. 檢查OPENCLAW_CONFIG_FILE環(huán)境變量或啟動(dòng)參數(shù)。2. 使用在線 YAML 校驗(yàn)器檢查config.yaml。3. 查看啟動(dòng)日志確認(rèn)有無配置加載錯(cuò)誤。調(diào)用模型返回404或模型未找到1. 路由name拼寫錯(cuò)誤2. 請(qǐng)求的model參數(shù)與路由name不匹配1. 核對(duì)curl http://localhost:3000/v1/models返回的列表。2. 檢查代碼中model參數(shù)是否與config.yaml中routes[*].name完全一致。調(diào)用本地 Ollama 超時(shí)或連接拒絕1. Docker 網(wǎng)絡(luò)問題host.docker.internal不可用2. Ollama 服務(wù)未運(yùn)行3. 防火墻/端口限制1. 在 OpenClaw 容器內(nèi)執(zhí)行curl http://host.docker.internal:11434/api/tags測(cè)試連通性。2. 在宿主機(jī)執(zhí)行ollama list確認(rèn)服務(wù)正常。3. 源碼運(yùn)行時(shí)將api_base改為http://localhost:11434。調(diào)用 OpenRouter 返回401或4031. API Key 錯(cuò)誤或過期2. API Key 未設(shè)置或環(huán)境變量未注入3. 賬戶余額不足或受限1. 登錄 OpenRouter 檢查 Key 狀態(tài)。2. 檢查 OpenClaw 日志確認(rèn)請(qǐng)求頭中是否攜帶了正確的Authorization。3. 檢查 OpenRouter 控制臺(tái)的用量和余額。響應(yīng)格式不符合 OpenAI 標(biāo)準(zhǔn)1. 供應(yīng)商適配器存在 Bug2. 供應(yīng)商 API 發(fā)生變更1. 查看 OpenClaw 日志中供應(yīng)商返回的原始響應(yīng)。2. 嘗試直接調(diào)用供應(yīng)商 API對(duì)比響應(yīng)差異。3. 升級(jí) OpenClaw 到最新版本或查閱相關(guān) Issue。流式響應(yīng)不工作或中斷1. 客戶端處理流式響應(yīng)的代碼有誤2. 網(wǎng)絡(luò)代理或中間件干擾了 SSE 連接1. 先用簡(jiǎn)單的curl或httpx測(cè)試流式端點(diǎn)。2. 檢查是否有 Nginx 等反向代理需要額外配置來支持text/event-stream。一個(gè)具體的排錯(cuò)案例我曾遇到調(diào)用 OpenRouter 一直超時(shí)。日志顯示Calling provider: cloud-openrouter...之后就沒了下文。首先我直接在服務(wù)器上用curl測(cè)試 OpenRouter API發(fā)現(xiàn)很快返回401說明網(wǎng)絡(luò)是通的。然后檢查 OpenClaw 日志的DEBUG級(jí)別發(fā)現(xiàn)請(qǐng)求確實(shí)發(fā)出了但一直沒有響應(yīng)。最后發(fā)現(xiàn)是 OpenClaw 容器的 DNS 解析有問題無法解析openrouter.ai這個(gè)域名。通過在 Docker Compose 文件中顯式配置 DNS 服務(wù)器如8.8.8.8解決了問題。8. 安全加固與生產(chǎn)部署建議將 OpenClaw 暴露在公網(wǎng)或用于生產(chǎn)環(huán)境前必須考慮安全。啟用 API 鑒權(quán)默認(rèn)情況下OpenClaw 可能不需要 API Key。在生產(chǎn)中你必須在配置中啟用全局或路由級(jí)別的鑒權(quán)。# 在 config.yaml 的根層級(jí)或特定 provider 下 auth: type: bearer api_keys: - your-super-secret-production-key-here客戶端調(diào)用時(shí)必須在請(qǐng)求頭中攜帶Authorization: Bearer your-super-secret-production-key-here。使用 HTTPS永遠(yuǎn)不要通過 HTTP 暴露服務(wù)。使用 Nginx 或 Caddy 作為反向代理配置 SSL/TLS 證書可以使用 Let‘s Encrypt 免費(fèi)獲取。限制訪問 IP在反向代理或防火墻層面只允許可信的客戶端 IP 地址訪問 OpenClaw 的端口。隔離配置與密鑰如前所述使用環(huán)境變量或密鑰管理服務(wù)如 Vault來管理config.yaml中的敏感信息切勿硬編碼。資源限制在 Docker Compose 中為容器設(shè)置 CPU 和內(nèi)存限制防止單個(gè)異常請(qǐng)求耗盡主機(jī)資源。# docker-compose.yml services: openclaw: # ... deploy: resources: limits: cpus: 1 memory: 1G定期更新關(guān)注 OpenClaw 項(xiàng)目的 Releases及時(shí)更新到新版本以獲取功能更新和安全補(bǔ)丁。經(jīng)過以上步驟你應(yīng)該已經(jīng)擁有了一個(gè)功能完整、配置靈活、具備生產(chǎn)潛力的統(tǒng)一大模型網(wǎng)關(guān)。從本地測(cè)試到云端集成從基礎(chǔ)調(diào)用到高級(jí)管控OpenClaw 用一個(gè)簡(jiǎn)潔的配置化解了多模型管理的復(fù)雜性。它可能不是解決所有問題的銀彈但在構(gòu)建需要靈活切換、統(tǒng)一管控大模型能力的應(yīng)用時(shí)它無疑是一個(gè)極具價(jià)值的基石性組件。 OpenClaw：統(tǒng)一大模型集成平臺(tái)部署與配置實(shí)戰(zhàn)指南
1. 項(xiàng)目概述為什么需要一個(gè)統(tǒng)一的大模型集成平臺(tái)如果你最近在折騰大語言模型不管是想用本地部署的 Llama 3 跑點(diǎn)私活還是想調(diào)用云端的 GPT-4 處理復(fù)雜任務(wù)大概率會(huì)面臨一個(gè)頭疼的問題切換成本太高。每個(gè)平臺(tái)都有自己的 API 格式、認(rèn)證方式和計(jì)費(fèi)規(guī)則寫一套代碼適配一個(gè)模型換一個(gè)就得重寫調(diào)試起來更是費(fèi)時(shí)費(fèi)力。這感覺就像家里每個(gè)電器都得配一個(gè)專屬插座麻煩不說還占地方。OpenClaw 就是為了解決這個(gè)“插座不通用”的問題而生的。你可以把它理解為一個(gè)“萬能適配器”或者“智能接線板”。它的核心目標(biāo)很簡(jiǎn)單讓你用一套統(tǒng)一的、簡(jiǎn)單的接口去調(diào)用背后五花八門的大模型服務(wù)。無論是你本地電腦上用 Ollama 跑的 Mistral還是通過 OpenRouter 聚合的 Claude、GPT-4甚至是公司內(nèi)網(wǎng)的私有模型在 OpenClaw 這里它們都被抽象成了同一個(gè)“模型”概念。你只需要告訴 OpenClaw“用這個(gè)模型處理這段文本”它就會(huì)幫你處理好所有繁瑣的通信、格式轉(zhuǎn)換和錯(cuò)誤重試。我最初接觸 OpenClaw 是因?yàn)閳F(tuán)隊(duì)內(nèi)部模型使用混亂。有人寫腳本調(diào) OpenAI有人用 curl 測(cè)試 Ollama還有人在研究如何接入國內(nèi)的大模型平臺(tái)。代碼重復(fù)、密鑰管理混亂、響應(yīng)格式不統(tǒng)一維護(hù)起來簡(jiǎn)直是噩夢(mèng)。OpenClaw 的出現(xiàn)讓我們終于可以把所有模型的調(diào)用收斂到一個(gè)標(biāo)準(zhǔn)化、可維護(hù)的服務(wù)里。這次實(shí)踐我就帶你從零開始打通從本地 Ollama 到云端 OpenRouter 的完整鏈路讓你也能輕松駕馭這個(gè)強(qiáng)大的集成工具。2. 核心設(shè)計(jì)思路OpenClaw 的架構(gòu)與核心概念拆解在動(dòng)手之前我們得先搞清楚 OpenClaw 是怎么工作的。它不是另一個(gè)大模型而是一個(gè)中間層一個(gè)代理。理解它的架構(gòu)能幫你更好地使用它甚至在出問題時(shí)快速定位。2.1 核心架構(gòu)路由、適配與統(tǒng)一OpenClaw 的架構(gòu)可以清晰地分為三層接口層、路由與適配層、供應(yīng)商層。接口層是你與 OpenClaw 交互的地方。它通常提供一個(gè)兼容 OpenAI API 格式的 HTTP 接口。這意味著如果你之前寫過調(diào)用chat.completions.create的代碼那么幾乎不用修改只需要把請(qǐng)求的base_url指向你的 OpenClaw 服務(wù)地址就能無縫切換。這極大地降低了遷移和學(xué)習(xí)的成本。路由與適配層是 OpenClaw 的大腦。這是最核心的部分它主要做兩件事路由根據(jù)你的請(qǐng)求比如你在代碼里指定的model參數(shù)是gpt-4還是llama3:8b決定這個(gè)請(qǐng)求應(yīng)該轉(zhuǎn)發(fā)給后端的哪個(gè)具體的模型服務(wù)。適配將你發(fā)送的標(biāo)準(zhǔn) OpenAI 格式的請(qǐng)求“翻譯”成后端目標(biāo)模型服務(wù)能理解的格式。比如發(fā)給 Ollama 的請(qǐng)求體和發(fā)給 Anthropic Claude 的請(qǐng)求體結(jié)構(gòu)是不同的OpenClaw 負(fù)責(zé)完成這個(gè)轉(zhuǎn)換。同樣它也會(huì)把各個(gè)供應(yīng)商返回的、五花八門的響應(yīng)統(tǒng)一“翻譯”回標(biāo)準(zhǔn)的 OpenAI 格式返回給你。供應(yīng)商層就是實(shí)際提供模型能力的后端服務(wù)比如本地運(yùn)行的 Ollama 服務(wù)器、OpenRouter 的 API 網(wǎng)關(guān)、或是直接配置的 OpenAI、Anthropic 等。這種設(shè)計(jì)的精妙之處在于“解耦”。你的應(yīng)用程序只和 OpenClaw 的標(biāo)準(zhǔn)接口對(duì)話完全不用關(guān)心后端是哪個(gè)模型、在哪里運(yùn)行。你想把llama3:8b換成claude-3-haiku只需要在 OpenClaw 的配置里改一個(gè)映射關(guān)系你的應(yīng)用代碼一行都不用動(dòng)。2.2 關(guān)鍵概念模型、供應(yīng)商與路由映射要配置 OpenClaw必須理解這三個(gè)核心概念它們構(gòu)成了配置文件的骨架。模型這是你給應(yīng)用程序暴露的抽象概念。你可以起任何名字比如my-fast-chat、code-expert。這個(gè)名稱對(duì)你和你的應(yīng)用有意義即可。供應(yīng)商這是實(shí)際提供模型計(jì)算能力的后端平臺(tái)。OpenClaw 預(yù)置了眾多供應(yīng)商的實(shí)現(xiàn)如openai、anthropic、ollama、openrouter、azure-openai等。每個(gè)供應(yīng)商都需要配置對(duì)應(yīng)的 API 密鑰、Base URL 等連接信息。路由映射這是連接“模型”和“供應(yīng)商”的橋梁。它告訴 OpenClaw“當(dāng)用戶請(qǐng)求名為my-fast-chat的模型時(shí)請(qǐng)將其路由到openrouter這個(gè)供應(yīng)商并且使用該供應(yīng)商平臺(tái)上名為claude-3-haiku的實(shí)際模型”。一個(gè)簡(jiǎn)單的映射關(guān)系看起來是這樣的my-fast-chat (應(yīng)用程序使用的模型名) - openrouter (供應(yīng)商) - claude-3-haiku (供應(yīng)商處的真實(shí)模型名)注意這里有一個(gè)初學(xué)者極易混淆的點(diǎn)。在配置 OpenRouter 或 Azure OpenAI 時(shí)你實(shí)際上需要配置兩次“模型名”。一次是在供應(yīng)商配置里指定該供應(yīng)商平臺(tái)上的“默認(rèn)模型”或“模型列表”另一次是在路由映射里精確指定使用哪個(gè)模型。很多配置錯(cuò)誤都源于此。3. 環(huán)境準(zhǔn)備與 OpenClaw 部署實(shí)戰(zhàn)理論清楚了我們開始動(dòng)手。部署 OpenClaw 有多種方式從最簡(jiǎn)單的 Docker 一鍵部署到從源碼編譯我們將覆蓋最實(shí)用的兩種。3.1 基礎(chǔ)環(huán)境與依賴檢查無論選擇哪種部署方式你的機(jī)器上都需要具備以下基礎(chǔ)環(huán)境Docker 與 Docker Compose這是目前最推薦、最無痛的部署方式。確保你的 Docker 守護(hù)進(jìn)程正在運(yùn)行。# 檢查 Docker 和 Docker Compose 版本 docker --version docker-compose --version如果未安裝請(qǐng)根據(jù)你的操作系統(tǒng)Ubuntu/CentOS/macOS參考官方文檔安裝。對(duì)于國內(nèi)用戶務(wù)必配置 Docker 鏡像加速器否則拉取鏡像會(huì)非常緩慢。Git用于克隆項(xiàng)目倉庫?？捎玫木W(wǎng)絡(luò)OpenClaw 需要訪問互聯(lián)網(wǎng)以下載 Docker 鏡像以及后續(xù)連接云端供應(yīng)商如 OpenRouter。如果部署在受限網(wǎng)絡(luò)環(huán)境需要提前準(zhǔn)備好代理或鏡像。3.2 方案一使用 Docker Compose 快速部署推薦這是最快、最標(biāo)準(zhǔn)化、最易于維護(hù)的部署方式。OpenClaw 官方提供了完善的docker-compose.yml文件。步驟 1獲取部署文件# 克隆 OpenClaw 倉庫如果網(wǎng)絡(luò)不暢可以在 GitHub 上直接下載 ZIP 包 git clone https://github.com/openclaw-ai/openclaw.git cd openclaw步驟 2配置環(huán)境變量OpenClaw 的核心配置通過環(huán)境變量文件.env管理。首先復(fù)制示例文件cp .env.example .env然后用文本編輯器打開.env文件。你需要重點(diǎn)關(guān)注以下幾個(gè)變量OPENCLAW_HOST服務(wù)綁定的主機(jī)默認(rèn)0.0.0.0即可表示監(jiān)聽所有網(wǎng)絡(luò)接口。OPENCLAW_PORT服務(wù)端口默認(rèn)3000。確保該端口沒有被其他程序占用。OPENCLAW_LOG_LEVEL日志級(jí)別開發(fā)調(diào)試可以設(shè)為DEBUG生產(chǎn)環(huán)境建議INFO。OPENCLAW_CONFIG_FILE配置文件路徑Docker 部署時(shí)通常映射到容器內(nèi)的/app/config.yaml我們稍后配置。步驟 3準(zhǔn)備配置文件Docker Compose 文件已經(jīng)將宿主機(jī)的./config目錄映射到了容器內(nèi)的/app/config。所以我們只需要在項(xiàng)目根目錄下創(chuàng)建config文件夾并在里面放置我們的config.yaml。mkdir -p config touch config/config.yaml現(xiàn)在先讓config.yaml空著我們會(huì)在下一章詳細(xì)填充內(nèi)容。步驟 4啟動(dòng)服務(wù)在項(xiàng)目根目錄即有docker-compose.yml的目錄下執(zhí)行docker-compose up -d-d參數(shù)表示在后臺(tái)運(yùn)行。首次運(yùn)行會(huì)拉取 OpenClaw 的 Docker 鏡像可能需要一些時(shí)間。步驟 5驗(yàn)證服務(wù)服務(wù)啟動(dòng)后可以通過以下命令檢查狀態(tài)和日志# 查看容器狀態(tài) docker-compose ps # 查看實(shí)時(shí)日志 docker-compose logs -f openclaw # 測(cè)試接口是否通暢 curl http://localhost:3000/v1/models如果看到返回一個(gè) JSON 格式的模型列表初始可能是空的說明 OpenClaw 服務(wù)已經(jīng)成功運(yùn)行。實(shí)操心得使用 Docker 部署時(shí)經(jīng)常遇到權(quán)限問題導(dǎo)致配置文件無法讀取。一個(gè)排查技巧是進(jìn)入容器內(nèi)部檢查文件是否存在且內(nèi)容正確docker exec -it openclaw-openclaw-1 cat /app/config/config.yaml。另外修改config.yaml后需要重啟容器才能生效docker-compose restart openclaw。3.3 方案二從源碼安裝與運(yùn)行如果你需要深度定制或想在非 Docker 環(huán)境運(yùn)行可以選擇源碼安裝。前提條件確保系統(tǒng)已安裝Python 3.10和Pip。步驟 1克隆并安裝依賴git clone https://github.com/openclaw-ai/openclaw.git cd openclaw pip install -e . # 使用開發(fā)模式安裝方便修改代碼 # 或者安裝生產(chǎn)依賴 # pip install -r requirements.txt步驟 2配置與運(yùn)行同樣需要準(zhǔn)備.env文件和config.yaml文件放置于項(xiàng)目根目錄或指定路徑。 然后通過環(huán)境變量指定配置文件路徑并啟動(dòng)export OPENCLAW_CONFIG_FILE./config.yaml openclaw run或者直接使用命令參數(shù)openclaw run --config ./config.yaml避坑指南源碼安裝最常見的問題是 Python 環(huán)境沖突。強(qiáng)烈建議使用venv或conda創(chuàng)建獨(dú)立的虛擬環(huán)境。此外某些依賴如httpx,pydantic的特定版本可能存在兼容性問題如果啟動(dòng)報(bào)錯(cuò)可以嘗試根據(jù)錯(cuò)誤信息調(diào)整requirements.txt中的版本號(hào)。4. 核心配置解析連接 Ollama 與 OpenRouter服務(wù)跑起來了但現(xiàn)在是“光桿司令”背后沒有可用的模型。接下來就是最關(guān)鍵的步驟編寫config.yaml配置文件把本地 Ollama 和云端 OpenRouter 接進(jìn)來。4.1 配置本地 Ollama 供應(yīng)商首先確保你的本地已經(jīng)安裝并運(yùn)行了 Ollama。你可以在終端執(zhí)行ollama serve來啟動(dòng)服務(wù)它默認(rèn)監(jiān)聽11434端口。然后編輯config.yaml文件# config.yaml # 1. 定義供應(yīng)商 providers: # 定義一個(gè)名為 local-ollama 的供應(yīng)商類型是 ollama - id: local-ollama type: ollama config: # Ollama 服務(wù)的地址如果 Ollama 運(yùn)行在本機(jī)就是這個(gè)地址 api_base: http://host.docker.internal:11434 # Ollama 通常不需要 API 密鑰除非你配置了身份驗(yàn)證 api_key: # 可選的模型列表用于發(fā)現(xiàn)和健康檢查 models: - id: llama3:8b name: Meta Llama 3 8B - id: mistral:7b name: Mistral 7B - id: qwen2.5:7b name: Qwen 2.5 7B # 2. 定義路由規(guī)則 routes: # 當(dāng)請(qǐng)求的模型名是 llama3 時(shí)路由到 local-ollama 供應(yīng)商并使用其下的 llama3:8b 模型 - name: llama3 provider: local-ollama model: llama3:8b # 另一個(gè)路由規(guī)則 - name: mistral provider: local-ollama model: mistral:7b關(guān)鍵點(diǎn)解析api_base: 這里使用了host.docker.internal。這是一個(gè) Docker 內(nèi)部的主機(jī)名指向宿主機(jī)的本地網(wǎng)絡(luò)。因?yàn)?OpenClaw 運(yùn)行在 Docker 容器內(nèi)要訪問宿主機(jī)的 Ollama 服務(wù)必須用這個(gè)地址。如果你是源碼直接運(yùn)行這里應(yīng)改為http://localhost:11434。models: 這個(gè)列表不是必須的但它有助于 OpenClaw 的管理界面如果有展示可用模型并進(jìn)行前置的健康檢查。routes:name是你自定義的、暴露給應(yīng)用調(diào)用的模型標(biāo)識(shí)符。model必須與 Ollama 中拉取ollama pull的模型名稱完全一致。保存配置后重啟 OpenClaw 服務(wù)docker-compose restart openclaw?，F(xiàn)在你的應(yīng)用就可以通過向http://localhost:3000/v1/chat/completions發(fā)送請(qǐng)求并指定model參數(shù)為llama3來調(diào)用本地的 Llama 3 8B 模型了。4.2 配置云端 OpenRouter 供應(yīng)商OpenRouter 是一個(gè)聚合了眾多主流大模型如 GPT-4, Claude, Gemini 等的 API 平臺(tái)使用統(tǒng)一的接口和計(jì)費(fèi)。首先你需要去 OpenRouter 官網(wǎng)注冊(cè)賬號(hào)并獲取 API Key。獲取 OpenRouter API Key:訪問 OpenRouter 官網(wǎng)并登錄。在控制臺(tái)找到API Keys部分。創(chuàng)建一個(gè)新的 Key并妥善保存。配置config.yaml: 我們?cè)趧偛诺呐渲没A(chǔ)上添加 OpenRouter 供應(yīng)商和路由。# config.yaml (續(xù)接上一部分) providers: - id: local-ollama type: ollama config: api_base: http://host.docker.internal:11434 models: - id: llama3:8b name: Meta Llama 3 8B - id: mistral:7b name: Mistral 7B # 新增 OpenRouter 供應(yīng)商 - id: cloud-openrouter type: openrouter config: # OpenRouter 的 API 端點(diǎn) api_base: https://openrouter.ai/api/v1 # 替換成你從官網(wǎng)獲取的真實(shí) API Key api_key: sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # 可選為通過 OpenRouter 發(fā)出的請(qǐng)求添加自定義請(qǐng)求頭例如指定推薦來源 # headers: # X-Title: My Awesome App # 可以在這里預(yù)定義一些 OpenRouter 上的模型但不是必須的 # models: # - id: openai/gpt-4-turbo # - id: anthropic/claude-3-haiku routes: - name: llama3 provider: local-ollama model: llama3:8b - name: mistral provider: local-ollama model: mistral:7b # 新增 OpenRouter 路由規(guī)則 - name: gpt4 # 給你的應(yīng)用使用的名字 provider: cloud-openrouter # 這里的 model 必須是 OpenRouter 支持的完整模型標(biāo)識(shí)符 model: openai/gpt-4-turbo - name: fast-claude provider: cloud-openrouter model: anthropic/claude-3-haiku - name: smart-gemini provider: cloud-openrouter model: google/gemini-pro配置要點(diǎn)與避坑模型標(biāo)識(shí)符必須精確OpenRouter 的模型 ID 格式通常是供應(yīng)商/模型名如openai/gpt-4-turbo。一定要去 OpenRouter 的模型列表頁面核對(duì)準(zhǔn)確的 ID寫錯(cuò)一個(gè)字都會(huì)導(dǎo)致路由失敗。API Key 安全永遠(yuǎn)不要將真實(shí)的 API Key 提交到版本控制系統(tǒng)如 Git。.env文件通常被.gitignore忽略但config.yaml可能不會(huì)。最佳實(shí)踐是將api_key作為環(huán)境變量注入?？梢孕薷呐渲脼閏onfig: api_base: https://openrouter.ai/api/v1 api_key: ${OPENROUTER_API_KEY} # 從環(huán)境變量讀取然后在.env文件中設(shè)置OPENROUTER_API_KEYsk-or-v1-...。網(wǎng)絡(luò)連通性確保部署 OpenClaw 的服務(wù)器能夠訪問https://openrouter.ai。對(duì)于國內(nèi)服務(wù)器這可能是一個(gè)挑戰(zhàn)需要自行解決網(wǎng)絡(luò)問題。配置完成后再次重啟 OpenClaw。現(xiàn)在你的服務(wù)就同時(shí)具備了調(diào)用本地輕量模型和云端頂級(jí)模型的能力。5. 應(yīng)用集成與調(diào)用實(shí)戰(zhàn)配置好了我們來實(shí)際調(diào)用一下看看效果。OpenClaw 兼容 OpenAI API所以我們可以使用任何 OpenAI SDK 來調(diào)用。5.1 使用 Python 進(jìn)行調(diào)用這里以最常用的openaiPython 庫為例。首先安裝庫pip install openai。# test_openclaw.py from openai import OpenAI import os # 初始化客戶端將 base_url 指向你的 OpenClaw 服務(wù) client OpenAI( base_urlhttp://localhost:3000/v1, # OpenClaw 的兼容端點(diǎn) api_keynot-needed # OpenClaw 如果未啟用鑒權(quán)這里可以填任意值。如果配置了全局鑒權(quán)則需填寫對(duì)應(yīng)的密鑰。 ) # 1. 調(diào)用本地 Ollama 的 Llama 3 模型 print( 調(diào)用本地 Llama3 ) try: response client.chat.completions.create( modelllama3, # 對(duì)應(yīng) config.yaml 中 routes 的 name messages[ {role: user, content: 用一句話介紹你自己。} ], max_tokens100, streamFalse # 先測(cè)試非流式 ) print(response.choices[0].message.content) except Exception as e: print(f調(diào)用失敗: {e}) # 2. 調(diào)用云端 OpenRouter 的 GPT-4 模型 print(\n 調(diào)用云端 GPT-4 ) try: response client.chat.completions.create( modelgpt4, # 對(duì)應(yīng) config.yaml 中 routes 的 name messages[ {role: user, content: 什么是量子計(jì)算用通俗的語言解釋。} ], max_tokens150, streamFalse ) print(response.choices[0].message.content) except Exception as e: print(f調(diào)用失敗: {e}) # 3. 測(cè)試流式響應(yīng)更適合生成長文本 print(\n 流式調(diào)用 Claude Haiku ) try: stream client.chat.completions.create( modelfast-claude, messages[ {role: user, content: 寫一首關(guān)于春天的五言絕句。} ], max_tokens50, streamTrue # 開啟流式 ) for chunk in stream: if chunk.choices[0].delta.content is not None: print(chunk.choices[0].delta.content, end, flushTrue) print() # 換行 except Exception as e: print(f\n流式調(diào)用失敗: {e})運(yùn)行這個(gè)腳本python test_openclaw.py你應(yīng)該能看到分別來自本地模型和云端模型的回復(fù)。這直觀地證明了 OpenClaw 的統(tǒng)一網(wǎng)關(guān)作用。5.2 在現(xiàn)有項(xiàng)目中集成如果你已經(jīng)有一個(gè)使用 OpenAI SDK 的項(xiàng)目集成 OpenClaw 簡(jiǎn)單到令人發(fā)指。通常只需要修改一行代碼——初始化客戶端時(shí)的base_url。之前直連 OpenAI:client OpenAI(api_keyyour-openai-key)之后通過 OpenClaw:client OpenAI( base_urlhttp://your-openclaw-server:3000/v1, api_keyyour-openclaw-global-key # 如果 OpenClaw 配置了鑒權(quán) )你項(xiàng)目里所有調(diào)用client.chat.completions.create、client.embeddings.create等方法的代碼都無需改動(dòng)只需要通過model參數(shù)指定你在 OpenClaw 中配置的路由名稱如llama3,gpt4即可。這種無縫切換的能力對(duì)于 A/B 測(cè)試不同模型、或在模型服務(wù)故障時(shí)快速降級(jí)到備用模型具有巨大的價(jià)值。6. 高級(jí)配置與生產(chǎn)級(jí)優(yōu)化基礎(chǔ)功能跑通后我們可以看看如何讓 OpenClaw 更強(qiáng)大、更穩(wěn)定適用于生產(chǎn)環(huán)境。6.1 負(fù)載均衡與故障轉(zhuǎn)移當(dāng)某個(gè)模型調(diào)用量很大或者為了高可用你可能需要配置負(fù)載均衡。OpenClaw 支持在路由級(jí)別配置多個(gè)供應(yīng)商端點(diǎn)。例如假設(shè)你有兩個(gè)都部署了llama3:8b模型的 Ollama 服務(wù)可能在不同的機(jī)器上你可以這樣配置providers: - id: ollama-server-1 type: ollama config: api_base: http://192.168.1.100:11434 - id: ollama-server-2 type: ollama config: api_base: http://192.168.1.101:11434 routes: - name: llama3-loadbalanced # 使用負(fù)載均衡策略 strategy: load_balance targets: - provider: ollama-server-1 model: llama3:8b weight: 1 # 權(quán)重 - provider: ollama-server-2 model: llama3:8b weight: 1 # 兩個(gè)服務(wù)器權(quán)重相同平均分配流量strategy還可以設(shè)置為failover故障轉(zhuǎn)移這樣當(dāng)?shù)谝粋€(gè)供應(yīng)商失敗時(shí)會(huì)自動(dòng)嘗試第二個(gè)提高了服務(wù)的魯棒性。6.2 速率限制與成本控制對(duì)接云端 API成本和用量控制至關(guān)重要。OpenClaw 允許你為路由設(shè)置速率限制和預(yù)算。routes: - name: gpt4-limited provider: cloud-openrouter model: openai/gpt-4-turbo # 速率限制每分鐘最多 10 次請(qǐng)求每秒最多 2 次 rate_limit: requests_per_minute: 10 requests_per_second: 2 # 成本控制設(shè)置每個(gè)用戶或全局的預(yù)算如果供應(yīng)商支持成本信息 # budget: # 此功能可能依賴供應(yīng)商接口和 OpenClaw 版本 # max_amount: 10.00 # 最大花費(fèi) 10 美元 # currency: USD這可以有效防止某個(gè)接口被意外刷爆導(dǎo)致巨額賬單。6.3 請(qǐng)求/響應(yīng)轉(zhuǎn)換與中間件這是 OpenClaw 非常強(qiáng)大的一個(gè)功能。你可以在請(qǐng)求到達(dá)供應(yīng)商前或響應(yīng)返回給客戶端前對(duì)數(shù)據(jù)進(jìn)行修改。場(chǎng)景示例 1為所有發(fā)送給 OpenRouter 的請(qǐng)求添加系統(tǒng)提示。routes: - name: claude-with-system provider: cloud-openrouter model: anthropic/claude-3-sonnet request_transforms: - type: add_message # 添加消息 config: message: role: system content: 你是一個(gè)專業(yè)的翻譯官請(qǐng)將所有用戶的輸入翻譯成英文后再進(jìn)行回答。 position: prepend # 添加到消息列表開頭場(chǎng)景示例 2攔截包含敏感詞的請(qǐng)求。routes: - name: safe-chat provider: local-ollama model: llama3:8b request_transforms: - type: block_if_contains # 如果包含則阻塞 config: contains: [敏感詞1, 敏感詞2] message: 請(qǐng)求包含不當(dāng)內(nèi)容已被攔截。 # 返回給客戶端的消息場(chǎng)景示例 3統(tǒng)一所有響應(yīng)的格式。response_transforms: - type: set_metadata # 設(shè)置元數(shù)據(jù) config: key: processed_by value: openclaw_gateway通過這些轉(zhuǎn)換器你可以實(shí)現(xiàn)審計(jì)、內(nèi)容過濾、數(shù)據(jù)標(biāo)準(zhǔn)化、A/B測(cè)試分流等復(fù)雜邏輯而無需修改客戶端或供應(yīng)商的代碼。7. 監(jiān)控、日志與問題排查一個(gè)穩(wěn)定的服務(wù)離不開可觀測(cè)性。OpenClaw 提供了多種方式來監(jiān)控其運(yùn)行狀態(tài)。7.1 內(nèi)置健康檢查與指標(biāo)OpenClaw 通常提供以下端點(diǎn)GET /health基礎(chǔ)健康檢查返回服務(wù)狀態(tài)。GET /metricsPrometheus 格式的指標(biāo)端點(diǎn)如果啟用可以監(jiān)控請(qǐng)求量、延遲、錯(cuò)誤率等。GET /v1/models列出當(dāng)前配置的所有可用路由模型。定期調(diào)用這些端點(diǎn)或?qū)⑵浼傻侥愕谋O(jiān)控系統(tǒng)如 Prometheus Grafana中是保障服務(wù)穩(wěn)定的基礎(chǔ)。7.2 日志分析OpenClaw 的日志是排查問題的第一手資料。通過docker-compose logs -f openclaw或查看日志文件你可以看到詳細(xì)的請(qǐng)求處理流程。關(guān)鍵日志模式Routing request to model: XXXX看到這個(gè)說明請(qǐng)求已進(jìn)入并確定了路由目標(biāo)。Calling provider: XXXX with model: YYYY正在調(diào)用具體的供應(yīng)商。Provider XXX returned status: 200供應(yīng)商調(diào)用成功。Provider XXX returned error: ...供應(yīng)商調(diào)用失敗錯(cuò)誤信息會(huì)在這里顯示這是診斷問題的關(guān)鍵。將日志級(jí)別設(shè)為DEBUG可以獲得更詳細(xì)的信息包括完整的請(qǐng)求和響應(yīng)體注意可能包含敏感數(shù)據(jù)生產(chǎn)環(huán)境慎用。7.3 常見問題排查清單以下是我在實(shí)戰(zhàn)中遇到的一些典型問題及解決方法問題現(xiàn)象可能原因排查步驟調(diào)用/v1/models返回空列表1. 配置文件路徑錯(cuò)誤2. 配置文件語法錯(cuò)誤YAML格式3. 服務(wù)未成功加載配置1. 檢查OPENCLAW_CONFIG_FILE環(huán)境變量或啟動(dòng)參數(shù)。2. 使用在線 YAML 校驗(yàn)器檢查config.yaml。3. 查看啟動(dòng)日志確認(rèn)有無配置加載錯(cuò)誤。調(diào)用模型返回404或模型未找到1. 路由name拼寫錯(cuò)誤2. 請(qǐng)求的model參數(shù)與路由name不匹配1. 核對(duì)curl http://localhost:3000/v1/models返回的列表。2. 檢查代碼中model參數(shù)是否與config.yaml中routes[*].name完全一致。調(diào)用本地 Ollama 超時(shí)或連接拒絕1. Docker 網(wǎng)絡(luò)問題host.docker.internal不可用2. Ollama 服務(wù)未運(yùn)行3. 防火墻/端口限制1. 在 OpenClaw 容器內(nèi)執(zhí)行curl http://host.docker.internal:11434/api/tags測(cè)試連通性。2. 在宿主機(jī)執(zhí)行ollama list確認(rèn)服務(wù)正常。3. 源碼運(yùn)行時(shí)將api_base改為http://localhost:11434。調(diào)用 OpenRouter 返回401或4031. API Key 錯(cuò)誤或過期2. API Key 未設(shè)置或環(huán)境變量未注入3. 賬戶余額不足或受限1. 登錄 OpenRouter 檢查 Key 狀態(tài)。2. 檢查 OpenClaw 日志確認(rèn)請(qǐng)求頭中是否攜帶了正確的Authorization。3. 檢查 OpenRouter 控制臺(tái)的用量和余額。響應(yīng)格式不符合 OpenAI 標(biāo)準(zhǔn)1. 供應(yīng)商適配器存在 Bug2. 供應(yīng)商 API 發(fā)生變更1. 查看 OpenClaw 日志中供應(yīng)商返回的原始響應(yīng)。2. 嘗試直接調(diào)用供應(yīng)商 API對(duì)比響應(yīng)差異。3. 升級(jí) OpenClaw 到最新版本或查閱相關(guān) Issue。流式響應(yīng)不工作或中斷1. 客戶端處理流式響應(yīng)的代碼有誤2. 網(wǎng)絡(luò)代理或中間件干擾了 SSE 連接1. 先用簡(jiǎn)單的curl或httpx測(cè)試流式端點(diǎn)。2. 檢查是否有 Nginx 等反向代理需要額外配置來支持text/event-stream。一個(gè)具體的排錯(cuò)案例我曾遇到調(diào)用 OpenRouter 一直超時(shí)。日志顯示Calling provider: cloud-openrouter...之后就沒了下文。首先我直接在服務(wù)器上用curl測(cè)試 OpenRouter API發(fā)現(xiàn)很快返回401說明網(wǎng)絡(luò)是通的。然后檢查 OpenClaw 日志的DEBUG級(jí)別發(fā)現(xiàn)請(qǐng)求確實(shí)發(fā)出了但一直沒有響應(yīng)。最后發(fā)現(xiàn)是 OpenClaw 容器的 DNS 解析有問題無法解析openrouter.ai這個(gè)域名。通過在 Docker Compose 文件中顯式配置 DNS 服務(wù)器如8.8.8.8解決了問題。8. 安全加固與生產(chǎn)部署建議將 OpenClaw 暴露在公網(wǎng)或用于生產(chǎn)環(huán)境前必須考慮安全。啟用 API 鑒權(quán)默認(rèn)情況下OpenClaw 可能不需要 API Key。在生產(chǎn)中你必須在配置中啟用全局或路由級(jí)別的鑒權(quán)。# 在 config.yaml 的根層級(jí)或特定 provider 下 auth: type: bearer api_keys: - your-super-secret-production-key-here客戶端調(diào)用時(shí)必須在請(qǐng)求頭中攜帶Authorization: Bearer your-super-secret-production-key-here。使用 HTTPS永遠(yuǎn)不要通過 HTTP 暴露服務(wù)。使用 Nginx 或 Caddy 作為反向代理配置 SSL/TLS 證書可以使用 Let‘s Encrypt 免費(fèi)獲取。限制訪問 IP在反向代理或防火墻層面只允許可信的客戶端 IP 地址訪問 OpenClaw 的端口。隔離配置與密鑰如前所述使用環(huán)境變量或密鑰管理服務(wù)如 Vault來管理config.yaml中的敏感信息切勿硬編碼。資源限制在 Docker Compose 中為容器設(shè)置 CPU 和內(nèi)存限制防止單個(gè)異常請(qǐng)求耗盡主機(jī)資源。# docker-compose.yml services: openclaw: # ... deploy: resources: limits: cpus: 1 memory: 1G定期更新關(guān)注 OpenClaw 項(xiàng)目的 Releases及時(shí)更新到新版本以獲取功能更新和安全補(bǔ)丁。經(jīng)過以上步驟你應(yīng)該已經(jīng)擁有了一個(gè)功能完整、配置靈活、具備生產(chǎn)潛力的統(tǒng)一大模型網(wǎng)關(guān)。從本地測(cè)試到云端集成從基礎(chǔ)調(diào)用到高級(jí)管控OpenClaw 用一個(gè)簡(jiǎn)潔的配置化解了多模型管理的復(fù)雜性。它可能不是解決所有問題的銀彈但在構(gòu)建需要靈活切換、統(tǒng)一管控大模型能力的應(yīng)用時(shí)它無疑是一個(gè)極具價(jià)值的基石性組件。