MaxCompute：MaxCompute AI資料探索用戶端

下載與安裝

介面概覽

用戶端採用三欄布局：

• 左側欄：資源管理區，包含檔案管理、Catalog 瀏覽、資料連線、資料匯入、SQL 知識庫搜尋、查詢歷史、檔案版本歷史等面板，通過左側表徵圖切換。

• 中間地區：SQL 編輯和資料展示區，支援多 Tab 頁並行操作。

• 右側欄：AI 助手面板（MaxMan AI），可展開或收合。

用戶端支援深色和淺色兩種主題，可在設定中切換。

配置資料連線

1. 點擊左側欄的串連表徵圖，開啟資料連線面板。

2. 點擊添加連線按鍵。

3. 填寫串連資訊：

   • 串連名稱：為該串連取一個便於識別的名稱。

   • 地區：從下拉式清單選擇 MaxCompute 專案所在的 Region，或選擇"自訂 Endpoint"手動輸入。

   • 專案名稱：填寫 MaxCompute 的 Project Name。

   • AccessKey ID 和 AccessKey Secret：填寫具有對應專案存取權限的 AccessKey。

4. 點擊測試連接驗證配置是否正確。

5. 測試通過後，點擊儲存。

串連成功後，左側 Catalog 面板會自動載入該專案下的表結構。

執行查詢

1. 按快速鍵 Option+N 或在檔案面板中點擊建立，建立一個 SQL 檔案。

2. 在編輯器中輸入一條查詢語句，例如：

   SELECT * FROM your_table_name LIMIT 10;

3. 按 Cmd+Enter（macOS）執行查詢。

4. 查詢結果將在編輯器下方的結果面板中展示，可以切換表格視圖、圖表視圖或透視表視圖對結果進行分析。

配置 AI 服務

1. 點擊右上方齒輪表徵圖開啟設定。

2. 進入 AI 配置標籤頁。

3. 填寫以下資訊：

   • API URL：AI 服務地址，預設為阿里雲百鍊 https://dashscope.aliyuncs.com/compatible-mode/v1/。

   • API Key：前往阿里雲百鍊控制台首頁，在頁面右上方選擇华北2（北京）地區，進入API Key頁面，單擊创建API Key或複製已有API Key。

   • 模型名稱：預設qwen3-max-2026-01-23，也可填寫其他相容 OpenAI 介面的模型。

4. 點擊儲存。

配置完成後，右側 AI 助手面板即可使用。可以直接輸入自然語言問題開始資料探索。

AI 資料探索

完成以上配置後，在 AI 助手面板中嘗試以下操作：

1. 輸入“查看當前專案有哪些表”，AI 會自動列出當前專案下的表。

2. 選擇一張表，輸入“查看這張表的結構和前 10 條資料”。

3. 看到結果後，輸入一個分析問題，例如“分析這張表中各分區的資料量分布”。

AI 助手會自動規劃執行步驟、產生 SQL、執行查詢並給出分析結論，全程可在介面上觀察執行過程。

建立連結

1. 在左側欄點擊串連表徵圖，開啟資料連線面板。

2. 單擊添加串連。

3. 填寫以下配置項：

   配置項	說明
   串連名稱	自訂名稱，用於在串連列表中區分不同串連。
   地區	選擇 MaxCompute 專案所在的 Region，系統會自動填滿對應的 Endpoint。
   專案名稱	MaxCompute 的 Project Name。
   AccessKey ID	阿里雲帳號的 AccessKey ID。
   AccessKey Secret	阿里雲帳號的 AccessKey Secret。

4. 單擊測試連接，確認串連可用。

5. 單擊儲存完成建立。

串連測試與診斷

點擊測試連接後，用戶端會嘗試串連 MaxCompute 服務並擷取專案資訊。如果串連失敗，請檢查以下事項：

• Endpoint 是否與專案所在 Region 匹配。

• AccessKey 是否正確且未到期。

• 當前網路環境是否可以訪問對應 Region 的 MaxCompute 服務。

• 使用的 AccessKey 對應的帳號是否具有該 Project 的存取權限。

多串連管理

資料連線面板以列表形式展示所有已儲存的串連。可以：

• 切換串連：

  點擊目標串連即可切換當前活動串連。SQL 執行、Catalog 瀏覽、資料匯入等操作都會在當前活動串連下執行。

• 刪除串連：

  點擊串連上的刪除表徵圖，移除該串連。如需修改串連配置，可刪除後重新建立。

支援同時儲存多個不同 Region 或不同 Project 的串連，在生產環境、測試環境、不同商務專案之間快速切換。

SQL 編輯器

用戶端內建基於 Monaco 的 SQL 編輯器，提供接近 IDE 的編輯體驗。

• 文法高亮與智能補全

  編輯器對 MaxCompute SQL 文法進行高亮著色，並在輸入過程中提供上下文感知的智能補全，包括 SQL 關鍵詞、MaxCompute 內建函數、當前串連下的表名和列名。補全列表會根據游標位置自動過濾，輸入表名後緊跟. 會自動彈出該表的列名補全。

• 代碼編輯

  編輯器支援程式碼摺疊功能、括弧配對著色、自動換行、Minimap 代碼縮圖等常用編輯功能。按 Shift+Option+F 可對當前 SQL 進行自動格式化。

SQL 指令碼管理

左側欄的檔案面板映射本地檔案系統中的 SQL 檔案。

• 建立檔案

  按 Option+N（Mac OS） 建立新的 SQL 檔案。

• 開啟檔案

  在檔案面板中點擊已有 SQL 檔案，在編輯器中開啟。

• 儲存檔案

  按 Option+S（Mac OS） 儲存當前編輯內容。

• 多 Tab 操作

  同時開啟多個 SQL 檔案，通過 Tab 頁切換。

SQL 檔案版本管理

用戶端為每個 SQL 檔案維護版本歷史。點擊左側欄的版本歷史表徵圖，可以查看當前檔案的歷史版本列表。

每個版本記錄包括版本號碼、儲存時間和版本類型。版本類型分為兩種：手動儲存（主動儲存時建立）和執行前快照（執行 SQL 前自動建立的備份）。

對版本可執行以下操作：

• 對比差異：雙擊某個版本，開啟 Diff 視圖，對比該版本與當前內容的差異。

• 恢複版本：將檔案內容恢複到指定版本。

• 刪除版本：清理不再需要的歷史版本。

SQL 執行

用戶端提供三種執行方式：

• 全文執行：按 Cmd+Enter，依次執行編輯器中的所有 SQL 陳述式。

• 選中執行：選中一段 SQL 文本後按 Shift+Enter，僅執行選中部分。

• 單句執行：編輯器在每條 SQL 陳述式的行間顯示運行按鈕，點擊即可執行該條語句。

如果 SQL 檔案中包含 SET 語句（如 SET odps.sql.type.system.odps2=true;），用戶端會自動將 SET 配置合并到後續 SQL 陳述式中一起執行。

執行過程中，編輯器下方會展示進度條和運行狀態。執行完成後，DQL（查詢語句）結果以表格形式展示，DDL / DML 等語句展示執行狀態。

查詢結果分析

查詢返回結果後，可通過以下方式深入分析。

查詢歷史

點擊左側欄的歷史表徵圖，可以瀏覽所有已執行查詢的記錄。每條記錄展示執行時間、耗時（毫秒）、SQL 陳述式預覽、執行狀態（成功 / 失敗）和返回行數。點擊某條記錄，可將該 SQL 回填到編輯器中。

查詢歷史支援分頁載入，便於回顧和複用歷史查詢。

Catalog 瀏覽

在左側欄點擊 Catalog 表徵圖，以樹形結構展示當前串連專案下的所有表。展開任意一張表，可以查看該表的列定義（列名、資料類型、注釋）。

右鍵點擊表名，可快速執行以下操作：

• 資料預覽：查看該表的前幾條資料。

• 查看錶結構：展示完整的列資訊、分區鍵、表屬性等。

• 查看錶資訊：展示表容量、記錄數、最近修改時間、許可權等中繼資料。

如果儲存了多個串連，Catalog 會展示所有已串連專案的表結構，便於在多專案之間對照瀏覽。

資料預覽

在 Catalog 中選擇一張表，可直接預覽表中的資料。系統會自動執行一條帶 LIMIT 的查詢語句，將結果以表格形式展示在中間地區。

分區管理

支援在 Catalog 中查看已有的分區列表，同時也支援為分區表添加新分區。

資料匯入

用戶端支援將本地檔案匯入 MaxCompute 表。點擊左側欄的資料匯入表徵圖，進入匯入面板。

資料匯出

查詢結果支援匯出為以下格式：

• CSV：以逗號分隔的文字檔，相容 Excel 等工具。

• JSON：結構化 JSON 格式。

• Parquet：列式儲存格式，適合巨量資料情境下的二次處理。

在查詢結果面板中，點擊匯出按鈕並選擇目標格式即可。

交談模式與 Agent 模式

AI 助手提供兩種工作模式：

交談模式適合快速問答和輕量級操作，例如解釋 SQL 含義、最佳化 SQL 寫法、對當前查詢結果給出洞察建議。您的問題會直接由 AI 產生回複，不涉及多步執行。

Agent 模式適合需要多步驟完成的資料分析任務。AI 會先制定執行計畫（Plan），經您確認後逐步執行，包括查詢中繼資料、產生 SQL、執行查詢、分析結果並輸出結論。

交談模式

在 AI 面板的輸入框中直接輸入問題即可進入交談模式。常用情境包括：

• SQL 產生：描述查詢需求，AI 產生對應的 MaxCompute SQL。

• SQL 最佳化：在編輯器中開啟一段 SQL，請求 AI 給出最佳化建議，最佳化後的 SQL 可一鍵插入編輯器。

• SQL 解釋：選中一段複雜 SQL，讓 AI 逐段解釋邏輯含義。

• 結果洞察：執行查詢後，針對結果資料請求 AI 提供趨勢分析、異常發現等洞察。

Agent 模式

當您提出一個涉及多步操作的分析問題時，AI 自動進入 Agent 模式。

AI 工作區

AI 工作區是 Agent 執行產物的本地持久化空間。每次 AI 分析任務執行過程中產生的中間結果和最終產物，都會自動儲存到工作區中。

應用情境

SQL 片段知識庫

SQL 片段知識庫用於管理可複用的 SQL 模板，適合管理周期性的取數指令碼。將標準化的業務 SQL 維護在知識庫中，配合 AI 的日期改寫能力，可以快速擷取不同時間段的報表資料。將日常使用的 SQL 檔案匯入知識庫，系統會自動從檔案中識別和抽取獨立的 SQL 片段，並為每個片段提取表名、關鍵詞、分區欄位和日期字面量，建立全文索引。

在左側欄點擊搜尋表徵圖，可以按關鍵詞搜尋知識庫中的 SQL 片段。找到後可以將片段插入編輯器執行，也可以通過 AI 助手調用“執行 SQL 片段”能力，讓 AI 自動匹配和改寫日期後執行。

語義層

語義層是 MaxCompute 用戶端與通用 AI 工具的關鍵差異。它將資料庫中的表和列，映射為業務可理解的術語、指標和關聯關係。AI 在產生 SQL 時會參考語義層資訊，從而產出更準確的查詢。

語義層包含以下組成部分：

• 業務術語：定義業務領域的專有名詞及其含義，例如DAU表示日活躍使用者數。

• 實體定義：描述核心業務對象及其對應的表和關鍵字段。

• 指標定義：定義業務指標的計算公式和口徑，例如轉化率 = 下單使用者數 / 訪問使用者數。

• 表關聯關係：描述表之間的 JOIN 關係和關聯鍵。

• 已驗證查詢：經過確認的標準查詢範本，AI 在遇到相似問題時可直接複用。

• 分析劇本（Playbook）：預設的分析情境和步驟模板，指導 AI 按照標準流程完成分析。

內建語義包

用戶端內建了 Information Schema 語義包，覆蓋 MaxCompute 租戶級元倉的常用分析情境，包括儲存壓力診斷、成本壓力診斷、作業效能分析、任務失敗激增分析、使用者角色審計、許可權暴露審計、熱點表觀測和資源配額監控。

啟用該語義包後，直接向 AI 提出元倉分析問題（例如“分析當前專案的儲存 Top 10 表”），AI 會基於語義包中的指標定義和參考查詢產生準確的分析 SQL。

自訂語義包

針對個人業務情境建立自訂語義包。在語義層管理面板中，選擇目標域後，可以逐項編輯術語、實體、指標、關聯關係、已驗證查詢和分析劇本。也可以使用 AI 協助工具功能，基於當前串連的表結構自動產生語義包初稿，再手動調整最佳化。

Blob 檔案瀏覽器

MaxCompute 支援 Blob 類型列儲存二進位檔案資料。用戶端提供檔案瀏覽器介面（需啟用檔案瀏覽器 Beta 開關），以類似檔案管理工具的方式瀏覽 MaxCompute 中儲存 Blob 資料的表。

檔案瀏覽器支援網格視圖和列表視圖切換、麵包屑導航、檔案夾建立和檔案上傳下載。

Blob 檔案匯入

在資料匯入面板中，切換到 Blob 匯入模式，可以通過拖拽方式批量上傳檔案到 MaxCompute 的 Blob 表中。系統會自動提取檔案路徑、名稱、類型等元資訊寫入表的對應列。

如果目標表尚不存在，用戶端會輔助產生包含 Blob 列的建表語句。

多模態檔案預覽

用戶端內建多模態檔案預覽能力，支援以下格式：

系統根據檔案的 MIME 類型自動匹配預覽方式，也支援手動切換。

WebDAV 掛載

用戶端內建 WebDAV 服務，可以將 MaxCompute 中儲存 Blob 檔案的表掛載為作業系統的本地檔案夾。掛載後，可以直接在 Finder 中預覽和下載檔案，無需通過用戶端介面操作。

macOS 掛載方式：

在 Finder 中按 Cmd+K，輸入 http://localhost:8899/dav/，即可以網路檔案夾形式瀏覽 Blob 表中的檔案資料。

OpenClaw Sub-Agent

MaxCompute 用戶端可以作為 OpenClaw 的 Sub-Agent 接入，承接 OpenClaw 下發的資料分析任務。

在這種模式下，OpenClaw 負責總控和任務編排，MaxCompute 用戶端負責專業的資料分析執行。兩者的協作優勢在於：

• 安全隔離：MaxCompute 的串連認證資訊保留在用戶端本地管理，OpenClaw 側不需要配置 AccessKey。

• 證據鏈完整：OpenClaw 側保持簡潔的對話體驗，詳細的執行過程（Plan、SQL、中間結果、診斷資訊）沉澱在用戶端中，可隨時回溯。

• 擴充分析：OpenClaw 得到的分析結論，可以繼續在用戶端的 Studio 模式下深入分析和匯出。

# 安裝 MaxCompute 外掛程式
openclaw plugins install @maxcompute/openclaw-maxquery --pin

# 啟用外掛程式並配置串連地址
openclaw plugins enable maxquery
openclaw config set plugins.entries.maxquery.enabled true
openclaw config set plugins.entries.maxquery.config.baseUrl http://127.0.0.1:8899

編輯器設定

AI 配置

AI 進階配置

主題切換

用戶端支援深色和淺色兩種主題，可在設定中切換。

版本更新

用戶端支援自動檢查更新。當有新版本可用時，會在應用內提示您下載安裝。

MacOS 安裝時提示“應用已損壞”或“無法驗證開發人員”

這是 macOS Gatekeeper 安全機制導致的，不影響應用安全性。開啟終端執行以下命令後重新啟動應用：

sudo xattr -rd com.apple.quarantine "/Applications/MaxCompute.app"

串連問題

• 串連測試失敗

  請依次排查以下事項：

  1. 確認 Endpoint 與 MaxCompute 專案所在 Region 匹配。如果不確定，可以在 MaxCompute 控制台查看專案詳情。

  2. 確認 AccessKey ID 和 Secret 填寫正確，且 AccessKey 未被禁用或到期。

  3. 確認當前網路可以訪問對應 Region 的 MaxCompute 公網 Endpoint。如果處於 VPN 或代理環境，確認網路原則允許出站串連。

  4. 確認 AccessKey 對應的帳號已被授權訪問目標 Project。

• 連線逾時

  通常由網路原因導致。如果使用的是跨境 Region（例如從中國內地訪問海外 Region），可能因網路延遲較高導致逾時。建議檢查網路連通性或聯絡網路系統管理員。

SQL 執行問題

• SQL 執行報語法錯誤

  MaxCompute SQL 與標準 SQL 存在部分差異。用戶端內建了 MaxCompute SQL 相容性規則，會在執行前自動進行部分文法轉寫（例如將 NOW() 轉為 GETDATE()），但不覆蓋所有情況。建議參閱 MaxCompute SQL 官方文檔確認文法。

• 查詢返回資料量過大

  用戶端預設對查詢結果進行行數限制以保證響應速度。如果需要擷取更多資料，建議在 SQL 中顯式使用 LIMIT 控制返回量，或通過資料匯出功能擷取完整結果。

AI 配置問題

• AI 助手無法使用

  請確認已在設定中正確配置 AI 服務的 API URL、API Key 和模型名稱。預設配置使用阿里雲百鍊（DashScope），您需要先在百鍊控制台建立 API Key。

• AI 響應速度慢

  AI 響應速度受模型服務負載和網路狀況影響。如果希望更快的響應，可以在 AI 進階配置中將推理檔位切換為 fast，或更換響應更快的模型。

匯入匯出問題

• Excel 檔案匯入後列類型不正確

  用戶端在解析 Excel 時會自動推斷列類型。如果推斷結果不符合預期，可以在建立表模式下手動修改 DDL 中的列類型定義，或使用 AI 產生 DDL 功能擷取更準確的類型推斷。

• Parquet 檔案匯出後無法開啟

  匯出的 Parquet 檔案遵循 Apache Parquet 標準格式，可使用 Python（pandas / pyarrow）、Spark 或其他支援 Parquet 的工具讀取。