從今天起，它不再是冷冰冰的代碼，而是你專屬的、7x24小時隨時待命的 AI 實習生！

文章作者、來源：Draco 正在 VibeCoding 

OpenClaw V3 新手起飛指南 🚀

✨ 寫在前面：

這是一份專門為你精簡提煉的“保姆級”新手指南。

我們剔除了早期不需要懂的底層配置和部署邏輯，為你找到了一條最平緩的入門曲線 (Sweet Spot)：

從零基礎 -> 拿到 API -> 成功安裝 -> 接入飛書 -> 安全防洩漏 -> 學會用技能

準備好了嗎？繫好安全帶，我們要發車了！

第一部分：揭開面紗（OpenClaw 到底是什麼）

🎯 本章目標：學完這章，你能向朋友清楚解釋OpenClaw是什麼、能做什麼、不能做什麼

⏱️ 預計時間：3分鐘

本章你將學會什麼

• 用一句話向朋友解釋OpenClaw是什麼

• 三個真實場景，理解它能幫你做什麼

• 澄清常見誤解，知道它不能做什麼

• 為什麼2026年它突然火了

• 根據你的需求，選擇最適合的閱讀路徑

1.1 一句話解釋：你的AI助理，住在你的電腦裡

想象一下：你招了一個實習生，這個實習生特別聰明，能幫你查資料、寫文檔、整理數據，還能24小時在線。但你不需要給它交社保，也不用擔心它跳槽。

OpenClaw就是這個實習生，只不過它住在你的電腦裡。

更準確地說：

OpenClaw是一個AI智能體平臺（Agent Platform），讓你能在自己的電腦上運行AI助理，並把它接入到你日常使用的工具裡——比如飛書、Telegram。

幾個核心概念，先混個臉熟（後面章節會詳細講）：

• Agent（智能體）：能自主執行任務的AI程序，就像一個帶工具箱的實習生。你告訴它"幫我整理今天的會議紀要"，它會自己決定用什麼工具、分幾步完成。

• Gateway（網關）：系統的總調度室，負責消息路由和協調。默認地址是127.0.0.1:18789，就是你電腦上開的一個端口。

• Channel（渠道）：連接各種聊天平臺的接口，比如飛書、Telegram。

• Tool（工具）：Agent能調用的具體功能，比如讀寫文件、執行命令、搜索網頁。

• Skill（技能）：告訴Agent什麼時候用什麼工具的"說明書"。

別慌，這些詞現在看著陌生，用幾遍就熟了。

1.2 它能做什麼：三個真實場景

光說概念太虛，來看三個真實的使用場景。

1.2.1 場景一：自動整理日報（拯救打工人）

小王每天下班前要發日報，總結今天做了什麼。以前他要翻聊天記錄、看郵件、回憶一天的工作，至少花20分鐘。

現在他@飛書裡的OpenClaw機器人：

"幫我整理今天的日報，從項目群提取關鍵進展，從郵件提取待跟進事項。"

機器人自動：

1. 讀取指定群聊的今日消息

2. 提取關鍵信息

3. 按格式生成日報

4. 發到指定文檔

省下的20分鐘，小王可以準時下班了。

1.2.2 場景二：查資料寫報告（研究員的福音）

小李需要寫一篇行業分析報告，涉及大量資料蒐集。以前他要在十幾個網站間來回切換，複製粘貼到手軟。

現在他告訴OpenClaw：

"搜索2025年AI編程助手的市場規模，整理成表格，包含數據來源。"

Agent自動：

1. 調用搜索工具查找資料

2. 訪問多個網頁提取信息

3. 整理成結構化表格

4. 標註數據來源

小李從"體力活"中解放出來，專注在分析和判斷上。

1.2.3 場景三：飛書裡@它辦事（團隊協作神器）

團隊群裡經常有人問：

• "誰能查一下上個月的銷售數據？"

• "幫忙翻譯一下這個英文文檔"

• "把這份PDF轉成Markdown"

現在直接在群裡@機器人：

"@小助手 把剛才發的PDF轉成Markdown格式"

機器人立即處理，把結果發回群裡。

不用麻煩同事，不用切換工具，在聊天中就把事辦了。

1.3 它不是什麼：澄清常見誤解

OpenClaw很強大，但它不是萬能的。以下幾個誤解，越早澄清越好。

1.3.1 誤解一：它是ChatGPT替代品

不是。

ChatGPT是一個AI對話產品，你打開網頁就能聊。OpenClaw是一個平臺，讓你能搭建自己的AI助理。

你可以這樣理解：

• ChatGPT = 一個訓練有素的客服

• OpenClaw = 一個可以訓練自己客服的系統

實際上，OpenClaw可以接入ChatGPT的API，也可以接入Claude、KIMI、MiniMax等其他模型。它是模型的使用者，不是模型的競爭者。

1.3.2 誤解二：它是雲端服務，數據存在別人服務器上

不是。

這是OpenClaw最大的特點之一：它運行在你的電腦上。

• 你的聊天記錄存在本地

• 你的文件處理在本地完成

• 你的API Key不會經過第三方服務器

對於擔心數據隱私的企業和個人，這是巨大的優勢。

⚠️ 注意：雖然OpenClaw本身在本地運行，但它調用AI模型時需要聯網。你的消息會發送到對應的AI服務商（如OpenAI、KIMI等）。

1.3.3 誤解三：它會自己上網亂買東西、亂髮郵件

不會。

OpenClaw的設計理念是最小權限原則。默認情況下，它什麼都不能做。

• 想讓它讀寫文件？你需要明確授權

• 想讓它發郵件？你需要配置郵件工具

• 想讓它執行命令？你需要開啟沙箱並設置權限

而且，高風險操作可以設置二次確認，確保它不會"自作主張"。

1.4 為什麼2026年它突然火了

AI Agent的概念不是2026年才有的，為什麼現在才火？

1.4.1 原因一：大模型能力到了"可用"的臨界點

2024年的GPT-4和Claude 3已經很強，但還不夠穩定。2025-2026年的模型（Claude Opus 4.6/Sonnet 4.6、GPT-5.3-Codex、KIMI K2.5等）在理解複雜指令和穩定輸出格式上有了質的飛躍。

簡單說：以前的AI助理經常"聽不懂人話"，現在的能聽懂了。

1.4.2 原因二：工程化工具成熟了

光有聰明的大腦不夠，還需要：

• 穩定的消息收發機制

• 可靠的工具調用框架

• 安全的權限管理系統

• 友好的配置界面

OpenClaw把這些工程難題都解決了，讓普通用戶也能搭起自己的AI助理。

1.4.3 原因三：從"玩具"到"工具"的轉變

早期的AI Agent更多是極客的玩具，現在它們真的能解決實際工作問題。

• 整理日報節省20分鐘

• 查資料寫報告節省2小時

• 自動化數據處理節省半天

當省下的時間超過學習成本時，普及就水到渠成了。

1.5 閱讀路線圖：三種讀者的最短路徑

這本書有17章，但你不需要全部讀完。根據你的需求，選擇最適合的路徑：

1.5.1 路徑A：我只想快速用起來（推薦所有人先走這條）

目標：在飛書裡@AI機器人，讓它幫你辦事

閱讀順序：

1. 第1章（本章）→ 瞭解是什麼

2. 第2章 → 準備API Key

3. 第3章 → 安裝OpenClaw

4. 第5章 → 接入飛書

5. 第6章 → 配置安全策略

預計時間：2-3小時

1.5.2 路徑B：我想深度定製，讓它做特定任務

目標：讓AI助理完成我的專屬任務（如數據分析、報告生成）

閱讀順序：

1. 先完成路徑A（基礎必須打牢）

2. 第10章 → 瞭解Tools能做什麼

3. 第11章 → 使用現成Skills

4. 第12章 → 寫第一個Skill

5. 第13章 → 進階優化

預計時間：1-2天

1.5.3 路徑C：我是技術用戶，想部署到服務器

目標：在服務器上穩定運行，團隊共享使用

閱讀順序：

1. 先完成路徑A（瞭解基礎）

2. 第7章 → 模型配置優化

3. 第8章 → 配置文件深入

4. 第9章 → 安全與沙箱

5. 第15章 → 多Workspace配置

6. 第16章 → 部署與運維

預計時間：2-3天

本部分小結

來，我們回顧一下：

1. OpenClaw是什麼：一個AI智能體平臺，讓你的電腦上運行AI助理

2. 它能做什麼：整理日報、查資料寫報告、飛書裡@它辦事

3. 它不能做什麼：不是ChatGPT替代品、不是純雲端服務、不會擅自行動

4. 為什麼現在火了：大模型能力成熟 + 工程化工具完善 + 真正解決工作問題

5. 怎麼開始：根據你的需求選擇路徑A、B或C

動手試試

1. 向一位朋友解釋OpenClaw是什麼，用本章的"帶工具箱的實習生"類比

2. 思考：你日常工作中有哪些重複性任務，可能適合交給AI助理？

3. 根據1.5節的路線圖，確定你要走哪條路徑

第二部分：開工準備（你只需要這三樣東西）

🎯 本章目標：學完這章，你能確認自己具備開始的所有條件，並準備好API Key

⏱️ 預計時間：10分鐘

本章你將學會什麼

• 確認你的電腦滿足運行條件

• 理解API Key是什麼，以及怎麼獲取

• 國內三家Coding Plan的詳細申請步驟（KIMI/MiniMax/GLM）

• 備選方案（OpenRouter/Anthropic）

• 提前預覽最終效果

2.1 別慌，你只需要這三樣東西

很多技術書一上來就列一堆要求，看得人想放棄。咱們換個方式：

你只需要三樣東西：

1. 一臺能上網的電腦（Windows/Mac/Linux都行）

2. 一個API Key（別被這個詞嚇到，就是一串密碼）

3. 10分鐘時間（和一點點耐心）

沒了。不需要你是程序員，不需要你懂AI，不需要買服務器。

2.2 第一樣東西：一臺電腦

2.2.1 系統要求

簡單說：只要是近5年的電腦，基本都能跑。

2.2.2 網絡要求

你需要能訪問：

• npm registry（安裝OpenClaw）

• 你選擇的AI服務商（如KIMI、MiniMax等）

國內用戶注意：OpenClaw本身不需要翻牆，但部分AI服務商可能需要。

2.3 第二樣東西：一個API Key

2.3.1 API Key是什麼？

API Key（應用編程接口密鑰），聽起來很高大上，其實就是一串密碼。

類比一下：

• 飯店的VIP卡 → 證明你有資格享受服務

• 小區的門禁卡 → 證明你有權限進入

• API Key → 證明你有權限調用AI服務

每次OpenClaw讓AI幫你幹活，都要出示這個Key。AI服務商根據Key來：

1. 確認你是誰

2. 計算你用了多少額度

3. 決定是否響應你的請求

2.3.2 國內三家Coding Plan（推薦）

對於國內用戶，我推薦優先選擇以下三家。它們都有專門針對開發者的 Coding Plan，且本章統一使用國內站口徑（不使用國際站路徑）。

2.3.2.1 方案A：KIMI Coding Plan（推薦）

5pMQBY

申請步驟：

1. 訪問 https://www.kimi.com/code

2. 登錄/註冊KIMI賬號

3. 點擊"訂閱Coding Plan"

4. 完成支付（支持支付寶/微信）

5. 進入控制檯，點擊"創建API Key"

6. 複製生成的Key（以sk-開頭）

💡 提示：Key創建後只顯示一次，務必保存好。如果丟了，只能重新創建。

2.3.2.2 方案B：MiniMax Coding Plan（推薦）

Cu5XmF

申請步驟：

1. 訪問 https://platform.minimaxi.com/subscribe/coding-plan

2. 註冊/登錄賬號

3. 完成實名認證（需要身份證）

4. 訂閱Coding Plan

5. 進入"API管理"頁面

6. 創建API Key並複製

2.3.2.3 方案C：GLM Coding Plan（推薦）

WUTpwh

申請步驟：

1. 訪問 https://bigmodel.cn/glm-coding

2. 註冊/登錄智譜AI賬號

3. 進入控制檯

4. 點擊"API Keys"菜單

5. 創建新的API Key

6. 複製保存

2.3.3 三家對比表

💡 說明：以上價格均按御三家國內站結算頁口徑記錄；後續如有活動變動，請以實時頁面為準。

2.3.4 備選方案

如果上述三家都不適合你，還有以下選擇：

2.3.4.1 OpenRouter

特點：一個API對接多家模型（Claude、GPT、Llama等）

網址：https://openrouter.ai

適合：想用一個Key調用多種模型的用戶

注意：國內訪問可能需要代理

2.3.4.2 Anthropic（Claude官方）

特點：Claude模型官方API，質量頂尖

網址：https://console.anthropic.com

適合：追求最高質量回復的用戶

注意：國內訪問需要代理，價格較高

2.4 第三樣東西：10分鐘時間

這10分鐘你要做什麼？

保存Key的建議：

1. 不要直接保存在微信/QQ聊天記錄裡

2. 不要截圖保存在相冊裡

3. 推薦保存在：

• 密碼管理器（1Password、Bitwarden等）

• 本地文本文件（放在安全的位置）

• 備忘錄（如果支持加密）

⚠️ 重要：API Key就像銀行卡密碼，洩露了別人就能花你的錢。妥善保管！

2.5 提前看看你會得到什麼

完成本書學習後，你將擁有：

一個能在飛書裡@的AI機器人：

• 私聊問它問題

• 群裡@它辦事

• 讓它幫你整理文檔、查資料

一個可定製的AI助理：

• 根據你的需求寫Skills

• 連接你的常用工具

• 自動化重複工作

完全掌控的數據隱私：

• 所有數據存在本地

• 不經過第三方服務器

• 企業級安全保障

本部分小結

來，檢查一下你的準備清單：

•  一臺能上網的電腦（Windows/Mac/Linux）

•  一個API Key（KIMI/MiniMax/GLM任選其一）

•  10分鐘時間

如果都準備好了

動手試試

1. 確認你的電腦系統版本符合要求

2. 選擇一家Coding Plan，完成API Key申請

3. 把Key保存在安全的地方（推薦密碼管理器）

4. 測試網絡：訪問你選擇的AI服務商控制檯，確認能正常打開

第三部分：極速安裝（5分鐘把神獸接回家）

🎯 本章目標：學完這章，你能完成OpenClaw安裝併發出第一條消息

⏱️ 預計時間：5分鐘

📋 前置要求：已完成第2章（準備工作）

本章你將學會什麼

• 檢查並安裝Node.js環境

• 用一行命令安裝OpenClaw

• 運行嚮導完成初始化配置

• 理解QuickStart和Manual的區別

• 配置國內三家Coding Plan

• 驗證安裝成功併發出第一條消息

3.1 環境檢查：Node.js是什麼？

3.1.1 Node.js簡介

Node.js是一個讓JavaScript能在電腦本地運行的環境。簡單說：

Node.js就像JavaScript的"翻譯官"，讓它能在瀏覽器之外的地方工作。

你不需要深入理解它，只需要確認電腦上已經安裝了。

3.1.2 檢查Node.js版本

打開你的終端（Terminal），輸入：

node --version

期望看到的結果：

v22.x.x

判斷標準：

• ✅ 版本 >= v22：可以繼續

• ❌ 版本

• ❌ 提示"command not found"：需要安裝

3.1.3 如果Node.js不符合要求

macOS安裝/升級

# 使用Homebrew安裝（推薦）brew install node# 如果已安裝但版本低，升級brew upgrade node

Windows安裝/升級

推薦方式：使用winget

winget install OpenJS.NodeJS.LTS

或者手動下載：

1. 訪問 https://nodejs.org

2. 下載LTS版本（長期支持版）

3. 按嚮導安裝

💡 Windows用戶注意：官方推薦在WSL2中運行OpenClaw，能避免很多奇怪問題。WSL2安裝指南：https://docs.microsoft.com/zh-cn/windows/wsl/install

Linux安裝/升級

Ubuntu/Debian：

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -sudo apt-get install -y nodejs

CentOS/RHEL/Fedora：

sudo dnf install nodejs

3.1.4 驗證安裝

安裝完成後，再次檢查：

node --versionnpm --version

兩個命令都應該返回版本號。

⚠️ 常見問題：如果安裝後還是提示"command not found"，嘗試重啟終端或重新登錄系統。

3.2 安裝命令：就一行，複製粘貼

確認Node.js >= v22後，執行安裝命令：

npm install -g openclaw@latest

這行命令在做什麼？

• npm：Node.js的包管理器

• install：安裝

• -g：全局安裝（在任何目錄都能用openclaw命令）

• openclaw@latest：安裝 npm 上當前發佈版（本書核驗凍結點為 v2026.2.17）

等待時間：取決於你的網絡，通常30秒到2分鐘。

3.2.1 驗證安裝成功

openclaw --version

期望看到類似輸出：

2026.2.17

❌ 如果提示"command not found"

可能原因：npm全局路徑未加入系統PATH

解決方法：

1. 重啟終端

2. 如果還不行，檢查npm全局路徑：npm prefix -g

3. 把返回的路徑加入PATH環境變量

3.3 運行嚮導：openclaw onboard

安裝完成後，運行初始化嚮導：

openclaw onboard --install-daemon

參數說明：

• onboard：運行初始化嚮導

• --install-daemon：同時安裝後臺服務（推薦）

3.3.1 嚮導第一步：風險確認 + 已有配置處理

啟動向導後，通常會先看到：

? I understand this is powerful and inherently risky. Continue?❯ Yes  No

這裡選 Yes 繼續。

如果你之前裝過 OpenClaw，還會看到：

Existing config detected...? Config handling❯ Use existing values  Update values  Reset

怎麼選：

• 首次安裝：通常不會出現這一段，直接進入下一步。

• 復裝/換模型：選 Update values（推薦，保留其餘穩定配置）。

• 完全重來：選 Reset（謹慎）。

3.3.2 嚮導第二步：選擇模式（Onboarding mode）

嚮導會問你：

? Onboarding mode❯ QuickStart - Minimal setup, get running fast  Manual - Full control over all settings

怎麼選？

我的建議：第一次選 QuickStart，後面可以隨時改配置。

3.3.3 嚮導第三步：先選模型廠商（Provider）

嚮導會提示你選擇模型提供商：

? Which model provider would you like to use?  OpenAI  Anthropic❯ KIMI  MiniMax  GLM  Other (custom endpoint)

先選你在第2章申請的廠商（KIMI / MiniMax / GLM）。

3.3.4 嚮導第四步：再選鑑權方式（Auth method，容易漏）

在你選完廠商後，通常不會立刻要 Key，而是先進入該廠商的鑑權方式選擇。

常見會看到類似：

?  auth method❯ Coding Plan / OAuth  API Key

國內讀者建議：優先選 Coding Plan 對應項。

• KIMI：優先 Kimi Code API key (subscription) 路徑

• MiniMax：優先 MiniMax OAuth（CN）路徑

• GLM（Z.AI）：優先 Coding-Plan-CN 路徑

3.3.5 嚮導第五步：輸入API Key並選模型

如果選擇KIMI

? Enter your KIMI API Key: [粘貼你的Key]? Select model: ❯ kimi-k2.5

如果選擇MiniMax

? Enter your MiniMax API Key: [粘貼你的Key]? Select model: ❯ MiniMax-M2.5

如果選擇GLM

? Enter your GLM API Key: [粘貼你的Key]? Select model: ❯ glm-5

💡 提示：粘貼API Key時，終端不會顯示任何字符（為了安全），這是正常的。直接粘貼後按回車即可。

3.3.6 嚮導第六步：配置Channel（先Skip！）

在 QuickStart 路徑下，嚮導會直接進入渠道單選列表：

? Select channel (QuickStart)  ...  Feishu/Lark (飛書)  ...❯ Skip for now (You can add channels later via `openclaw channels add`)

首次建議直接選 Skip for now。

為什麼先Skip？

這是多輪實測驗證出的最佳實踐：

1. 先把"TUI裡能穩定對話"跑通

2. 確認模型、鑑權、Gateway都正常

3. 再接入渠道，出錯時能明確判斷是"渠道配置問題"還是"基礎環境問題"

放心，第5章會詳細講飛書接入。

3.3.7 嚮導第七步：配置 Skills（建議開）

Channel 之後，嚮導會進入 Skills 檢查與可選安裝：

Skills statusEligible: ...Missing requirements: ......? Configure skills now? (recommended)❯ Yes  No

首次建議選 Yes，原因很簡單：

現在就把“能自動裝的依賴”裝掉，後面少踩坑。

接下來常見會看到：

? Install missing skill dependencies❯ Skip for now ? Preferred node manager for skill installs❯ npm  pnpm  bun

給新手的默認建議：

1. 如果你只想先跑通主線：可先 Skip for now；

2. 如果你準備立刻玩 Skills：按需勾選安裝項；

3. node manager 選你本機已經在用的那個（不確定就用 npm）。

3.3.8 嚮導第八步：配置 Hooks（建議最小開啟）

Skills 後會進入 Hooks 配置：

Hooks...? Enable hooks?❯ Skip for now  

官方說明裡，Hooks 用來“在某些命令觸發時自動執行動作”（例如 /new 時做會話記憶整理）。

本書建議的最小策略：

1. 首次可先啟用 1 個最核心 hook（最小可用，優先 session-memory，若列表裡有）；

2. 如果你現在還分不清 hook 的作用，也可以先 Skip for now；

3. 先跑通主線，後面在第10章再系統化管理 hooks。

3.3.9 嚮導第九步：選擇 Hatch 方式（關鍵）

在收尾階段，嚮導會給你一個啟動入口選擇：

? How do you want to hatch your bot?❯ Hatch in TUI (recommended)  Open the Web UI  Do this later

怎麼選：

• Hatch in TUI (recommended)：在終端裡直接進入交互（最穩，推薦默認選這個）

• Open the Web UI：打開瀏覽器控制檯（圖形化）

• Do this later：先結束嚮導，稍後再進

為什麼默認選 TUI：

1. 我們無法假設你一定在本機操作；很多讀者是在雲主機/VPS 上跑。

2. 如果是 VPS，Open the Web UI 往往還要做端口轉發，對新手不友好。

3. 選 Hatch in TUI 可以立刻開始對話，不被網絡與端口問題卡住。

3.3.10 嚮導第十步：記錄 Dashboard 鏈接與 Gateway 狀態

在你完成 Hatch 選擇後，嚮導會輸出控制檯訪問信息與網關狀態（如 Web UI、Gateway WS、Gateway: reachable）。

如果你選了 Open the Web UI，一般會直接給出帶 token 的 Dashboard 鏈接並嘗試自動打開瀏覽器。

如果你選了 Do this later，後續可用：

openclaw dashboard --no-open

再次獲取控制檯入口。

3.4 首次對話：先完成 bootstrap（真正初始化）

onboard 完成後，建議先在 TUI 裡完成第一輪 bootstrap 對話。

官方流程會把它當成“把 Agent 變成你的 Agent”的關鍵動作（源碼裡有 Wake up, my friend! 引導）。

這一步建議你主動講清楚下面 5 件事：

1. 你是誰：怎麼稱呼你、你的時區和工作語言。

2. 你要它扮演什麼角色：比如“我的技術寫作助手”。

3. 你平時的工作場景：常用工具、文件目錄、溝通方式（飛書/郵件等）。

4. 你的偏好：回答風格、長度、是否先給結論。

5. 你的邊界：哪些操作必須先確認、哪些內容不要碰。

這一步做得越清楚，後續它越像“你自己的實例”，而不是“一個通用聊天機器人”。

💡 你也可以把這些信息落盤到工作區裡的 BOOTSTRAP.md / IDENTITY.md / USER.md / SOUL.md，讓後續會話更穩定。

3.5 Bootstrap 後，再發第一條“低上下文”消息

完成 bootstrap 後，建議先發一條不依賴你工作背景的消息做冒煙測試。

推薦你先用這條：

請給我一個“今天就能執行”的 5 條待辦清單（每條不超過 18 個字），並按優先級排序。

如果你想測“查詢能力”，可再補一條：

請告訴我北京今天的天氣，並給出穿衣建議（1 句話）。

按回車發送。

期望的回覆：

它應該直接給出結構化結果（清單或天氣建議），而不是繼續做泛泛自我介紹。

如果看到回覆，恭喜你！安裝成功！

3.6 如果出錯了怎麼辦

3.6.1 問題一：Gateway啟動失敗

症狀：嚮導提示Gateway failed to start

可能原因：

1. 端口18789被佔用

2. 權限不足

3. 配置文件錯誤

解決方法：

# 查看端口占用lsof -i :18789# 或者換端口啟動openclaw gateway start --port 18790

3.6.2 問題二：發送消息無回覆

症狀：消息發送後，一直顯示"正在輸入"但沒有回覆

可能原因：

1. API Key錯誤

2. 網絡不通

3. 模型服務異常

解決方法：

# 檢查配置openclaw config get# 檢查模型連接openclaw doctor# 查看日誌openclaw logs

3.6.3 問題三：Web UI打不開

症狀：瀏覽器訪問127.0.0.1:18789顯示無法連接

可能原因：

1. Gateway沒啟動

2. 防火牆阻擋

3. 地址輸錯

解決方法：

# 確認Gateway在運行openclaw status# 如果未運行，手動啟動openclaw gateway start

本部分小結

來，回顧一下今天的成果：

1. ✅ 檢查了Node.js環境（>= v22）

2. ✅ 安裝了OpenClaw（npm install -g openclaw@latest）

3. ✅ 運行了初始化嚮導（openclaw onboard --install-daemon）

4. ✅ 配置了國內Coding Plan（KIMI/MiniMax/GLM）

5. ✅ 在收尾階段選擇了 Hatch in TUI (recommended)（默認推薦）

6. ✅ 完成了首次 bootstrap（把實例初始化成“你的實例”）

7. ✅ 發出了第一條業務消息！

動手試試

1. 在 TUI 裡繼續對話，補充你的工作邊界、偏好與禁區（完成 bootstrap）

2. 讓它基於你的真實場景給出一個可執行清單（例如今天待辦）

3. 如果你在本機環境，再額外打開 Dashboard/Web UI 對照體驗一次

4. 如果安裝過程中遇到問題，記錄錯誤信息，對照第4章排查

第四部分：飛書接入（讓它能在群裡陪你聊天）

🎯 本章目標：學完這章，你能在飛書裡@AI機器人，讓它幫你辦事

⏱️ 預計時間：30分鐘

📋 前置要求：已完成第3章（安裝成功，並在TUI完成bootstrap首輪對話）

本章你將學會什麼

• 在飛書開放平臺創建企業應用

• 獲取App ID和App Secret

• 配置權限（含批量導入JSON）

• 理解"先發布→再配置→再開長連接"的關鍵時序

• 在OpenClaw側配置飛書渠道

• 完成配對並驗證收發

5.1 為什麼第3章讓你先Skip Channel

還記得第3章的配置嚮導嗎？我們在Channel那一步選擇了Skip。

這不是省略，而是有意為之。

實測經驗告訴我們：

• 先把"TUI裡能穩定對話"跑通，確認模型、鑑權、Gateway都正常

• 再做渠道接入，出錯時就能明確判斷是"渠道配置問題"還是"基礎環境問題"

• 這種"兩段式"路徑成功率更高，也更容易排錯

如果你已經完成第3章，並且在 TUI 裡完成了 bootstrap 初始化，這一章就是你的下一步。

5.2 飛書接入的整體流程

不管你接的是哪家平臺，基本都遵循同一條流水線：

1. 平臺側建應用（拿到憑證）

2. OpenClaw側配置渠道（openclaw channels add）

3. 啟動Gateway並驗證收發

4. 配對/白名單放行

5. 再做群聊策略、提及策略和風控

你可以把這5步理解為"固定骨架"。本章先把飛書走通，其他渠道請走補充章或官方渠道文檔。

5.3 階段一：飛書私聊機器人（降低複雜度）

本節按兩段走：

1. 第一階段：飛書私聊機器人可穩定收發

2. 第二階段：飛書群聊裡@機器人可回覆

為什麼要分兩段？

排障時，私聊比群聊簡單得多。先確保私聊通，再搞群聊，能大幅降低複雜度。

5.4 Step 1：在飛書開放平臺創建應用

5.4.1 打開平臺並創建企業應用

1. 打開飛書開放平臺：https://open.feishu.cn/app

2. 登錄你的飛書賬號（需要有企業管理員權限）

3. 點擊"創建企業自建應用"

創建企業應用

1. 填寫應用信息：

• 應用名稱：建議用"AI助手"或"OpenClaw"

• 應用描述：內部使用的AI助手

• 圖標：可以上傳一個機器人圖標

5.4.2 獲取App ID與App Secret

創建完成後，進入應用詳情頁：

1. 點擊左側"憑證與基礎信息"

2. 記錄以下信息：

• App ID（形如cli_xxxxxxxxxxxxxxxx）

• App Secret（點擊"查看"按鈕顯示）

獲取憑據

⚠️ 重要：App Secret務必保密，不要截圖外傳，不要發到群裡。洩露了別人就能控制你的機器人。

5.4.3 權限配置（批量導入）

這是最容易出錯的步驟，仔細跟著做。

1. 點擊左側"權限管理"

2. 點擊"批量導入權限"

3. 粘貼以下內容：

{  "scopes": {    "tenant": [      "aily:file:read",      "aily:file:write",      "application:application.app_message_stats.overview:readonly",      "application:application:self_manage",      "application:bot.menu:write",      "contact:user.employee_id:readonly",      "corehr:file:download",      "event:ip_list",      "im:chat.access_event.bot_p2p_chat:read",      "im:chat.members:bot_access",      "im:message",      "im:message.group_at_msg:readonly",      "im:message.p2p_msg:readonly",      "im:message:readonly",      "im:message:send_as_bot",      "im:resource"    ],    "user": [      "aily:file:read",      "aily:file:write",      "im:chat.access_event.bot_p2p_chat:read"    ]  }}

1. 點擊"確定"

配置權限

這些權限是做什麼的？

5.4.4 啟用Bot能力

1. 點擊左側"應用能力"

2. 找到"機器人"卡片，點擊"啟用"

3. 設置機器人名稱（建議和應用名稱一致）

4. 點擊"保存"

啟用 Bot 能力

5.4.5 首次發佈應用（⚠️ 關鍵步驟！）

切記：這一步必須在開啟長連接之前完成！

實測經驗：如果還沒先發布應用就直接開啟"長連接訂閱"，通常會持續失敗。

發佈步驟：

1. 點擊左側"版本管理與發佈"

2. 點擊"創建版本"

3. 填寫版本信息：

• 版本號：1.0.0

• 更新說明：初始版本

4. 點擊"保存"

5. 點擊"申請發佈"

6. 等待企業管理員審批（如果是你自己的企業，通常自動通過）

💡 提示：審批通過後，應用狀態會變為"已發佈"。這時候才能進行下一步。

5.5 Step 2：在OpenClaw配置飛書

5.5.1 啟用飛書插件

先查看插件列表：

openclaw plugins list

如果存在feishu且狀態是disabled，啟用它：

openclaw plugins enable feishu

💡 提示：官方文檔也給出openclaw plugins install @openclaw/feishu。但結合本書的實測，優先啟用內置插件更穩定。

5.5.2 交互式添加Channel

運行命令：

openclaw channels add

按提示完成配置：

問題1：選擇渠道類型

? Select channel type:❯ Feishu/Lark (飛書)  Telegram  WebChat  ...

選擇Feishu/Lark (飛書)

問題2：輸入App ID

? Enter Feishu App ID: cli_xxxxxxxxxxxxxxxx

粘貼你在5.4.2獲取的App ID

問題3：輸入App Secret

? Enter Feishu App Secret: [粘貼Secret]

粘貼你在5.4.2獲取的App Secret（粘貼時不顯示字符，這是正常的）

問題4：選擇飛書域名

? Which Feishu domain?❯ feishu.cn (國內版)  larksuite.com (國際版)

國內用戶選feishu.cn

問題5：群聊策略

? Group chat policy:❯ disabled (先不通群聊)  enabled

先選disabled，等私聊通了再開群聊。

問題6：需要mention才回復？

? Require mention in group chats?❯ yes (群裡需要@才回復)  no

選yes，避免機器人在群裡亂說話。

5.5.3 驗證配置

配置完成後，查看Channel列表：

openclaw channels list

應該顯示：

NAME    TYPE    STATUSfeishu  feishu  configured

5.6 Step 3：開啟事件訂閱（長連接）

5.6.1 關鍵時序（⚠️ 血的教訓）

正確的時序是：

1. ✅ 飛書側：創建應用 → 配置權限 → 發佈應用

2. ✅ OpenClaw側：channels add配置渠道

3. ✅ OpenClaw側：啟動Gateway

4. ✅ 飛書側：開啟事件訂閱（長連接）

5. ✅ 飛書側：配置事件訂閱地址

如果順序錯了，長連接會訂閱失敗，表現為"消息發出去，機器人沒反應"。

5.6.2 啟動Gateway

openclaw gateway start

確認輸出：

✓ Gateway started on http://127.0.0.1:18789

5.6.3 在飛書平臺開啟事件訂閱

1. 回到飛書開放平臺

2. 點擊左側"事件與回調"

3. 在"事件訂閱方式"中，選擇"長連接"

配置事件訂閱

1. 點擊"保存"

5.6.4 添加事件訂閱

在"訂閱事件"區域，點擊"添加事件"：

1. 搜索im.message.receive_v1

2. 勾選並確認添加

這個事件表示"收到消息時通知我"。

5.7 Step 4：配對與放行

5.7.1 私聊機器人觸發配對

在飛書裡：

1. 搜索你的機器人名稱

2. 進入私聊界面

3. 發送任意消息，比如"你好"

這時候消息還到不了 OpenClaw，因為需要先“配對”。

在默認 dmPolicy: pairing 下，機器人會在飛書私聊裡直接回一條配對提示，裡面包含一段配對碼（Pairing code）。

這就是對用戶最直觀、最容易拿到 code 的路徑。

5.7.2 方式A（推薦）：直接用私聊裡的配對碼批准

讓用戶把飛書私聊裡看到的 Pairing code 發給管理員（或你自己複製）。

然後在終端執行：

openclaw pairing approve feishu 

例如：

openclaw pairing approve feishu A1B2C3D4

（把 A1B2C3D4 替換成飛書私聊裡看到的真實配對碼）

5.7.3 方式B（備選）：在OpenClaw裡查配對請求

如果你沒看到私聊裡的 code，或者想二次核對，再在終端運行：

openclaw pairing list feishu

應該顯示：

Code      ID          Meta        RequestedA1B2C3D4  ou_xxx...   {...}       2026-02-18T10:10:00.000Z

再執行批准：

openclaw pairing approve feishu A1B2C3D4

（把 A1B2C3D4 換成上一步看到的真實配對碼 Code）

5.7.4 驗證私聊

回到飛書，再次發送消息：

你好，請介紹一下你自己

期望結果：機器人回覆消息！

5.8 Step 5：開啟群聊（可選）

私聊通了之後，可以開啟群聊功能。

5.8.1 修改Channel配置

openclaw channels add --channel feishu

修改：

• groupChat: enabled

• requireMention: true

5.8.2 把機器人拉進群

1. 在飛書裡創建一個群

2. 點擊"添加機器人"

3. 搜索你的機器人名稱

4. 添加進群

5.8.3 群裡@機器人測試

在群裡發送：

@AI助手 你好

期望結果：機器人回覆消息！

5.9 驗收清單

完成本章後，你應該能：

•  在飛書開放平臺創建併發布企業應用

•  獲取App ID和App Secret

•  配置權限並啟用Bot能力

•  在OpenClaw側配置飛書Channel

•  開啟長連接訂閱

•  完成配對並批准

•  私聊機器人能收到回覆

•  （可選）群聊@機器人能收到回覆

本部分小結

飛書接入的核心要點：

1. 先發布，再開長連接 —— 時序錯了會訂閱失敗

2. 先私聊，再群聊 —— 降低排障複雜度

3. 配對要批准 —— 安全第一，不讓陌生人隨便用

4. 權限要配全 —— JSON批量導入最省事

動手試試

1. 在飛書裡和機器人私聊，測試各種功能

2. 嘗試讓機器人幫你整理一段文字

3. 如果公司有測試群，把機器人拉進去試試@功能

4. 記錄遇到的問題，對照本章排查

第五部分：安全防護（別讓它在公司大群亂回消息）

🎯 本章目標：學完這章，你能掌握飛書渠道的安全配置，避免"機器人亂回"的尷尬

⏱️ 預計時間：20分鐘

📋 前置要求：已完成第5章（飛書基礎接入）

本章你將學會什麼

• 理解三種私聊策略的區別（pairing/allowlist/all）

• 掌握群聊策略配置（requireMention的重要性）

• 配置白名單（allowFrom/groupAllowFrom）

• 上線前的風控checklist

• 解決長連接訂閱失敗、消息不回、@沒反應等常見問題

6.1 為什麼需要安全配置

先講一個"血的教訓"：

某公司把OpenClaw機器人接入飛書，沒做安全配置。結果機器人被拉進一個有500人的大群，有人@它問了個敏感問題，機器人直接回復了內部數據。群裡瞬間炸了。

安全問題不是"會不會發生"，而是"什麼時候發生"。

本章的配置，就是給你的機器人上把鎖。

6.2 私聊策略：誰能和機器人說話

OpenClaw提供三種私聊策略，在配置Channel時選擇：

6.2.1 策略一：pairing（推薦）

機制：用戶必須先發送消息申請配對，管理員批准後才能對話

適用場景：

• 企業內部使用

• 需要控制誰能使用機器人

• 安全第一的場景

配置方式：

openclaw channels add --channel feishu

設置privateChat: pairing

用戶流程：

1. 用戶私聊機器人發送任意消息

2. 消息被攔截，提示"等待管理員批准"

3. 管理員先執行 openclaw pairing list feishu 獲取 Code，再執行 openclaw pairing approve feishu

4. 用戶才能正常對話

6.2.2 策略二：allowlist

機制：只有白名單裡的用戶能和機器人對話

適用場景：

• 明確知道誰需要用機器人

• 人數不多的小團隊

配置方式：

{  "privateChat": "allowlist",  "allowFrom": ["user1@company.com", "user2@company.com"]}

6.2.3 策略三：all（不推薦）

機制：任何人都能和機器人對話

適用場景：

• 公開演示

• 內部完全信任的環境

風險：

• 任何人都能消耗你的API額度

• 任何人都能看到機器人的回覆

6.3 群聊策略：別讓它亂回消息

6.3.1 requireMention：群聊的保險栓

這個配置強烈建議開啟！

機制：機器人在群裡只回復@它的消息，無視其他消息

為什麼重要？

想象這個場景：

• 群裡500人，聊得熱火朝天

• 機器人監聽所有消息

• 有人隨口說了句"幫我查一下上個月的銷售額"

• 機器人以為是命令，開始執行...

配置方式：

openclaw channels add --channel feishu

設置requireMention: true

6.3.2 群聊白名單：誰能拉機器人進群

即使開啟了requireMention，也建議配置群聊白名單：

{  "groupChat": "enabled",  "groupAllowFrom": ["group1_id", "group2_id"],  "requireMention": true}

怎麼獲取群ID？

在飛書群裡，點擊群設置 → 群信息，可以看到群ID。

6.4 風控checklist：上線前的5個檢查項

在把機器人正式投入使用前，按這個清單檢查：

6.4.1 Checklist

•  私聊策略：確認是pairing或allowlist，不是all

•  群聊策略：確認開啟了requireMention

•  群聊白名單：確認只允許必要的群使用

•  API額度：確認有足夠的餘額，設置預算上限

•  敏感工具：確認高風險工具（如執行命令）已限制或關閉

6.4.2 設置預算上限

# 查看當前預算設置openclaw config get budget.monthly# 設置月度預算上限（美元）openclaw config set budget.monthly 50

6.4.3 限制高風險工具

在配置文件中，限制Agent能使用的工具：

{  "agents": {    "default": {      "tools": {        "allow": ["read_file", "write_file", "search_web"],        "deny": ["execute_command", "send_email"]      }    }  }}

6.5 常見問題排查

6.5.1 問題一：長連接訂閱失敗

症狀：飛書平臺顯示"長連接訂閱失敗"或"連接超時"

可能原因：

1. 應用未發佈就開啟長連接

2. Gateway未啟動

3. 網絡不通

解決步驟：

1. 確認應用已發佈（版本管理與發佈 → 狀態為"已發佈"）

2. 確認Gateway在運行：

openclaw status

3. 重啟長連接：

• 在飛書平臺關閉長連接，保存

• 再開啟長連接，保存

6.5.2 問題二：消息發出去，機器人沒反應

症狀：飛書裡發消息，機器人不回覆

排查流程：

1. 檢查Gateway狀態   openclaw status2. 檢查Channel狀態   openclaw channels list3. 檢查配對狀態   openclaw pairing list feishu4. 查看日誌   openclaw logs

常見原因：

• 用戶未配對（狀態pending）

• 私聊策略是allowlist但用戶不在列表裡

• 群聊沒開requireMention但用戶沒@機器人

6.5.3 問題三：@機器人沒反應

症狀：群裡@機器人，但它不回覆

排查步驟：

1. 確認requireMention配置為true

2. 確認@的是正確的機器人（不是同名機器人）

3. 檢查機器人是否在群裡（可能被移出）

4. 查看日誌確認收到消息：

openclaw logs --follow

6.5.4 問題四：機器人回覆很慢

症狀：消息發出去，要等很久才收到回覆

可能原因：

1. 模型響應慢

2. 網絡延遲

3. Skill執行耗時

優化建議：

• 切換到響應更快的模型（如MiniMax）

• 檢查網絡連接

• 簡化Skill的調用鏈

6.5.5 問題五：機器人亂回消息

症狀：機器人在不該回復的時候回覆了

立即處理：

1. 臨時禁用Channel：

openclaw config set channels.feishu.enabled false

2. 檢查配置：

• 私聊策略是否太寬鬆

• 群聊是否沒開requireMention

• 白名單是否配置正確

3. 修復配置後重新啟用：

openclaw config set channels.feishu.enabled true

6.6 安全配置最佳實踐

6.6.1 企業級部署建議

{  "channels": {    "feishu": {      "privateChat": "pairing",      "groupChat": "enabled",      "groupAllowFrom": ["approved_group_1", "approved_group_2"],      "requireMention": true,      "maxMessageLength": 2000,      "rateLimit": {        "perUser": 30,        "perGroup": 100      }    }  }}

6.6.2 個人使用建議

{  "channels": {    "feishu": {      "privateChat": "pairing",      "groupChat": "disabled",      "requireMention": true    }  }}

本部分小結

安全配置的核心原則：

1. 寧可多確認一次 —— pairing策略雖然麻煩，但安全

2. 群聊必須@才回 —— requireMention是保險栓

3. 白名單限制範圍 —— 明確誰能用、在哪用

4. 預算上限防刷爆 —— 避免一覺醒來賬單驚人

動手試試

1. 檢查你當前的飛書配置，對照6.4的checklist

2. 如果私聊策略是all，改成pairing

3. 確認requireMention已開啟

4. 設置一個月度預算上限

5. 邀請一位同事測試配對流程

第六部分：挑選大腦（KIMI、MiniMax、GLM 怎麼選）

🎯 本章目標：學完這章，你能根據需求選擇最適合的模型，並正確配置

⏱️ 預計時間：20分鐘

📋 前置要求：已完成第3章（基礎安裝）

本章你將學會什麼

• 國內三家Coding Plan的能力對比

• KIMI Coding Plan的詳細配置步驟

• MiniMax Coding Plan的詳細配置步驟

• GLM Coding Plan的詳細配置步驟

• 模型切換與回退配置

• 成本監控方法

7.1 三家對比（國內站口徑）

7.1.1 快速對比表

💡 說明：本章只使用御三家國內站口徑；價格會隨活動變動，購買前請以結算頁實時顯示為準。

7.1.2 我的建議

先選你已開通套餐的一家（最穩妥）

先跑通、再優化，是對小白最友好的路徑。先用已開通套餐的那一家完成第3章的安裝和首輪對話，避免在起步階段增加變量。

如果三家都能用，再按任務類型切：

• 長文檔整理、長上下文問答：先試 moonshot/kimi-k2.5

• 響應速度優先、需要快速往返：先試 minimax/MiniMax-M2.5

• 通用型任務、希望策略更均衡：先試 zai/glm-5

上述建議是實操經驗路徑，不是官方性能排名；最終以你自己的任務實測為準。

7.2 KIMI Coding Plan配置

7.2.1 獲取API Key

1. 訪問 https://www.kimi.com/code

2. 登錄/註冊KIMI賬號

3. 點擊"訂閱Coding Plan"

4. 完成支付（支持支付寶/微信）

5. 進入控制檯，點擊"API管理"

6. 點擊"創建API Key"

7. 複製生成的Key（以sk-開頭）

7.2.2 在OpenClaw配置KIMI

方式一：通過嚮導配置

openclaw onboard

選擇KIMI，粘貼API Key。

方式二：手動配置

# 先完成 KIMI 鑑權openclaw onboard --auth-choice kimi-code-api-key# 設置默認模型（provider/model）openclaw models set moonshot/kimi-k2.5

7.2.3 KIMI可用模型

推薦：日常使用選kimi-k2.5，複雜推理再切kimi-k2-thinking。

7.3 MiniMax Coding Plan配置

7.3.1 獲取API Key

1. 訪問 https://platform.minimaxi.com/subscribe/coding-plan

2. 註冊/登錄賬號

3. 完成實名認證（按頁面提示）

4. 訂閱Coding Plan

5. 進入"API管理"頁面

6. 創建API Key並複製

7.3.2 在OpenClaw配置MiniMax

通過嚮導配置：

openclaw onboard

選擇MiniMax，粘貼API Key。

手動配置：

# 先完成 MiniMax 鑑權（優先 Coding Plan/OAuth）openclaw onboard --auth-choice minimax-portal# 設置默認模型（provider/model）openclaw models set minimax/MiniMax-M2.5

7.3.3 MiniMax可用模型

推薦：默認選minimax/MiniMax-M2.5，追求速度再切 Lightning。

7.4 GLM Coding Plan配置

7.4.1 獲取API Key

1. 訪問 https://bigmodel.cn/glm-coding

2. 註冊/登錄智譜AI賬號

3. 進入控制檯

4. 點擊"API Keys"菜單

5. 創建新的API Key

6. 複製保存

7.4.2 在OpenClaw配置GLM

通過嚮導配置：

openclaw onboard

選擇GLM，粘貼API Key。

手動配置：

# 先完成 Z.AI 鑑權（GLM）openclaw onboard --auth-choice zai-api-key# 設置默認模型（provider/model）openclaw models set zai/glm-5

7.4.3 GLM可用模型

推薦：默認選zai/glm-5，輕任務可切zai/glm-4.7-flash。

7.5 模型切換與回退

7.5.1 配置主模型和備用模型

OpenClaw支持配置主模型（primary）和備用模型（fallbacks）：

{  "models": {    "primary": {      "provider": "kimi",      "model": "kimi-k2.5",      "apiKey": "sk-xxx"    },    "fallbacks": [      {        "provider": "minimax",        "model": "MiniMax-M2.5",        "apiKey": "xxx"      },      {        "provider": "glm",        "model": "glm-5",        "apiKey": "xxx"      }    ]  }}

工作原理：

1. 優先使用primary模型

2. 如果primary失敗（如額度用完、服務異常），自動切換到fallbacks[0]

3. 如果fallbacks[0]也失敗，切換到fallbacks[1]

4. 以此類推

7.5.2 動態切換模型

在對話中臨時切換模型：

@agent 使用MiniMax回答這個問題

或在配置中設置規則：

{  "routing": {    "byTask": {      "coding": "kimi",      "quickReply": "minimax",      "longDoc": "kimi"    }  }}

7.6 成本監控

7.6.1 設置預算上限

# 設置月度預算（美元）openclaw config set budget.monthly 50# 設置單日預算openclaw config set budget.daily 5

達到預算上限後，OpenClaw會：

• 發送警告通知

• 暫停非必要調用

• 保留緊急功能

7.6.2 查看使用統計

# 查看本月使用情況openclaw gateway usage-cost# 輸出示例：# Provider    Requests    Tokens    Cost(USD)# kimi        1,234       5.2M      $12.34# minimax     567         2.1M      $5.67# Total                   7.3M      $18.01

7.6.3 成本控制技巧

1. 選擇合適的模型

• 簡單任務用輕量模型（zai/glm-4.7-flash）

• 複雜任務才用強模型（moonshot/kimi-k2.5）

2. 限制上下文長度

{  "models": {    "primary": {      "