OpenClaw

OpenClaw 是執行在個人裝置上的開源 AI 助手。它透過 Gateway 統一管理模型、工作階段、工具和訊息管道，並提供終端機 TUI 與瀏覽器 Control UI。將 AGTCloud 新增為 Custom Provider 後，OpenClaw 可以透過 OpenAI Chat Completions 相容入口呼叫目前 API Key 可用的模型。

本教學只完成本機安裝、模型串接、Gateway 啟動和基本驗證。訊息管道、遠端 Gateway、ClawHub 外掛、Skills、MCP、定時任務和多代理功能不在本頁說明。

準備工作

開始前，請確認你已經：

• 準備一台受 OpenClaw 支援的 macOS、Linux、WSL2 或 Windows 裝置；
• 在 API Keys 頁面建立 AGTCloud API Key；
• 從模型廣場複製目前 Key 可見、且支援 Chat Completions 的模型 ID；
• 準備一個不包含正式環境憑證和敏感原始碼的測試目錄。

MODEL_ID 是需要替換的預留位置。若要測試工具呼叫，請選擇目前 API Key 可見且明確支援工具呼叫的模型。

安裝 OpenClaw

OpenClaw 官方安裝器可以在需要時準備受支援的 Node.js 執行環境。已經自行管理 Node.js 的客戶也可以使用 npm 安裝。

curl -fsSL https://openclaw.ai/install.sh | bash

安裝完成後檢查版本和執行環境：

openclaw --version
openclaw doctor

如果安裝器自動開啟引導精靈，可以先退出模型設定步驟，完成下方 AGTCloud Provider 設定後再執行 openclaw onboard --install-daemon。這樣引導程序可以保留已經驗證過的預設模型設定。

安全儲存 API Key

OpenClaw 會讀取 ~/.openclaw/.env 作為全域環境變數回退檔案。先建立該檔案，再寫入 AGTCloud API Key：

~/.openclaw/.env

檔案內容：

AGTCLOUD_API_KEY=your-api-key

該檔案包含真實憑證，不要提交到程式碼倉庫、上傳到雲端硬碟或作為疑難排解附件傳送。

新增 AGTCloud Custom Provider

OpenClaw 將 Custom Provider 儲存到 models.providers。本教學使用增量設定命令合併 agtcloud Provider，不覆蓋現有 openclaw.json。

openclaw config set models.providers.agtcloud \
  '{"baseUrl":"https://api.agtcloud.cn/v1","apiKey":"${AGTCLOUD_API_KEY}","api":"openai-completions","auth":"api-key","authHeader":true,"models":[{"id":"MODEL_ID","name":"MODEL_ID","input":["text"]}]}' \
  --strict-json \
  --merge

設定中的關鍵欄位如下：

教學只把模型聲明為文字輸入，不填寫未經確認的上下文長度、最大輸出、價格、推理或圖片能力。掌握目標模型的真實能力後，可以再按照 OpenClaw 官方模型欄位說明補充中繼資料。

設定模型並檢查設定

將剛剛登記的模型設為預設模型：

openclaw models set agtcloud/MODEL_ID

依次檢查設定檔、Provider 模型和目前預設模型：

openclaw config validate
openclaw models list --provider agtcloud
openclaw models status

如果 config validate 報告無效欄位，請先修復設定，不要繼續啟動 Gateway。若模型清單中沒有 agtcloud/MODEL_ID，請檢查模型是否已經加入 models.providers.agtcloud.models。

需要執行真實連線探測時，可以執行：

openclaw models status --probe

完成本機引導並啟動 Gateway

Provider 設定通過驗證後，執行本機引導並安裝 Gateway 背景常駐程序：

openclaw onboard --install-daemon

如果精靈詢問模型設定，請選擇保留現有模型設定；訊息管道、Web Search、Skills 和其他擴充可以先跳過。首次設定建議保持 Gateway 僅監聽本機，並保留存取驗證。

完成後重新啟動並檢查 Gateway：

openclaw gateway restart
openclaw gateway status

Gateway 無法啟動時，先執行 openclaw config validate 和 openclaw doctor，不要使用開放公網監聽或關閉驗證作為臨時繞過方案。

啟動並驗證連線

開啟 Control UI 或終端機 TUI

使用瀏覽器 Control UI：

openclaw dashboard

或者在終端機連線本機 Gateway：

openclaw tui

驗證基本文字回覆

首次輸入以下內容：

請只回覆：AGTCloud 連線成功。不要呼叫任何工具。

能夠傳回指定文字，說明 Gateway、AGTCloud Provider、API Key 和模型 ID 已建立基本連線。

可選：驗證唯讀工具能力

確認一般對話穩定後，在安全測試專案中輸入：

請讀取 README.md，並用三點概括專案用途。不要修改任何檔案，也不要執行其他命令。

檢查 OpenClaw 提出的每項操作，只核准讀取目標檔案所需的權限。一般對話成功但該步驟失敗，通常表示目標模型或目前相容入口尚未完整支援所需的工具呼叫結構。

新增或切換模型

OpenClaw 的模型引用格式為 provider/model，因此 AGTCloud 模型寫作：

agtcloud/MODEL_ID

Custom Provider 不保證自動讀取 AGTCloud /v1/models 的所有結果。需要增加模型時，應把新的模型物件合併到 models.providers.agtcloud.models，再使用以下命令切換：

openclaw models set agtcloud/MODEL_ID
openclaw gateway restart

修改模型名稱後，應確認該模型對目前 API Key 可見且支援對應協議，否則可能出現模型不存在或不允許使用的錯誤。

常見問題

遇到無法定位的問題時，請記錄 OpenClaw 版本、請求時間、API Base URL、Provider、模型 ID、HTTP 狀態和去識別化錯誤資訊，然後檢視錯誤與疑難排解。不要提交 .env、完整設定備份或任何 API Key。

安全建議

• OpenClaw 面向單一可信操作者設計，不要把未經保護的 Gateway 暴露到公網；
• 首次測試只使用隔離目錄，並逐項審查檔案、命令、網路和工具權限；
• 不在倉庫、截圖、工作階段匯出、記錄或共享設定中儲存 API Key；
• 串接訊息管道、其他使用者或自動化任務前，先閱讀 OpenClaw 官方安全與沙箱文件。

下一步

• API Key 與驗證
• Chat Completions API Reference
• 錯誤與疑難排解
• OpenClaw 官方文件