Microsoft Excel：通过 API 实现电子表格自动化 - Openclaw Skills

什么是 Microsoft Excel API 集成？

Microsoft Excel 技能在 AI 代理与 Microsoft Graph API 之间提供了无缝桥梁，允许全面操作存储在 OneDrive 或 SharePoint 中的 Excel 文件。通过利用 Openclaw Skills，开发人员可以绕过复杂的 OAuth 实现，直接通过托管网关与工作簿、工作表和单元格区域进行交互。这种集成对于构建需要处理电子表格数据、生成报告或通过安全统一的界面同步企业数据集信息的代理至关重要。

下载入口:https://github.com/openclaw/skills/tree/main/skills/byungkyu/microsoft-excel

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

npx clawhub@latest install microsoft-excel

2. 手动安装

将技能文件夹复制到以下位置之一

全局模式 ~/.openclaw/skills/ 工作区 <project>/skills/

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

请帮我使用 Clawhub 安装 microsoft-excel。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。

Microsoft Excel API 集成 应用场景

• 将 AI 生成的洞察或外部数据源自动输入到 Excel 工作簿中。
• 提取特定区域或表格数据以供 LLM 提示词进行数据分析。
• 在现有的 OneDrive 电子表格中生成动态图表和可视化报告。
• 以编程方式管理复杂的财务模型、库存清单或项目追踪器。
• 使用持久会话进行批量电子表格更新处理，以确保数据完整性和性能。

Microsoft Excel API 集成 工作原理

1. 用户使用 Maton API 密钥进行身份验证，并通过控制门户建立托管 OAuth 连接。
2. API 请求被发送到 Openclaw Skills 网关，网关会自动注入必要的 OAuth 令牌。
3. 网关将请求代理到 Microsoft Graph API，通过文件 ID 或 OneDrive 路径定位特定工作簿。
4. 技能执行请求的操作，例如读取单元格值、更新区域或创建新工作表。
5. 对于复杂的工作流，该技能管理工作簿会话，将多个操作作为单个逻辑单元处理。

Microsoft Excel API 集成 配置指南

通过获取您的 Maton API 密钥并配置环境变量来设置技能：

export MATON_API_KEY="YOUR_API_KEY"

接下来，通过控制门户 https://ctrl.maton.ai 创建与 Microsoft Excel 的活动连接。您可以使用以下命令验证连接状态，以确保您的 Openclaw Skills 环境配置正确：

# 列出活动连接以验证设置
curl -H "Authorization: Bearer $MATON_API_KEY" "https://ctrl.maton.ai/connections?app=microsoft-excel&status=ACTIVE"

Microsoft Excel API 集成 数据架构与分类体系

该技能基于 Microsoft Graph 资源层级组织数据交互。Openclaw Skills 用户可以导航和操作以下数据结构：

层级	描述	关键属性
驱动器	OneDrive 或 SharePoint 中的根容器	drive_id, root_path
工作簿	主要的 .xlsx 文件资源	file_id, filename
工作表	工作簿中的单个表格页	id, name, visibility
区域	指定的单元格块	address, values, formulas, text
表格	带有标题的结构化数据对象	id, name, rows, columns
图表	视觉数据表示	type, sourceData, seriesBy

注意：所有区域操作均使用标准 A1 引用样式（例如 A1:C10）。仅支持 .xlsx 文件格式。

name: microsoft-excel
description: |
  Microsoft Excel API integration with managed OAuth. Read and write Excel workbooks, worksheets, ranges, tables, and charts stored in OneDrive.
  Use this skill when users want to read or modify Excel spreadsheets, manage worksheet data, work with tables, or access cell values.
  For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway).
compatibility: Requires network access and valid Maton API key
metadata:
  author: maton
  version: "1.0"
  clawdbot:
    emoji: ??
    requires:
      env:
        - MATON_API_KEY

Microsoft Excel

Access the Microsoft Excel API (via Microsoft Graph) with managed OAuth authentication. Read and write workbooks, worksheets, ranges, tables, and charts stored in OneDrive or SharePoint.

Quick Start

# List worksheets in a workbook
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/worksheets')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Base URL

https://gateway.maton.ai/microsoft-excel/{native-api-path}

Replace {native-api-path} with the actual Microsoft Graph API endpoint path. The gateway proxies requests to graph.microsoft.com and automatically injects your OAuth token.

Authentication

All requests require the Maton API key in the Authorization header:

Authorization: Bearer $MATON_API_KEY

Environment Variable: Set your API key as MATON_API_KEY:

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

1. Sign in or create an account at maton.ai
2. Go to maton.ai/settings
3. Copy your API key

Connection Management

Manage your Microsoft Excel OAuth connections at https://ctrl.maton.ai.

List Connections

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=microsoft-excel&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Create Connection

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'microsoft-excel'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Get Connection

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "connection": {
    "connection_id": "4751ac89-3970-47e1-872c-eacdf4291732",
    "status": "ACTIVE",
    "creation_time": "2026-02-07T00:43:18.565932Z",
    "last_updated_time": "2026-02-07T00:43:29.729782Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "microsoft-excel",
    "metadata": {}
  }
}

Open the returned url in a browser to complete OAuth authorization.

Delete Connection

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Specifying Connection

If you have multiple Microsoft Excel connections, specify which one to use with the Maton-Connection header:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/microsoft-excel/v1.0/me/drive')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '4751ac89-3970-47e1-872c-eacdf4291732')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

If omitted, the gateway uses the default (oldest) active connection.

Workbook Access Patterns

You can access workbooks using either ID-based or path-based patterns:

By File ID:

/microsoft-excel/v1.0/me/drive/items/{file-id}/workbook/...

By File Path:

/microsoft-excel/v1.0/me/drive/root:/{path-to-file}:/workbook/...

API Reference

Drive Operations

Get Drive Info

GET /microsoft-excel/v1.0/me/drive

List Root Files

GET /microsoft-excel/v1.0/me/drive/root/children

Search for Excel Files

GET /microsoft-excel/v1.0/me/drive/root/search(q='.xlsx')

Upload Excel File

PUT /microsoft-excel/v1.0/me/drive/root:/{filename}.xlsx:/content
Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

{binary xlsx content}

Session Management

Sessions improve performance for multiple operations. Recommended for batch operations.

Create Session

POST /microsoft-excel/v1.0/me/drive/root:/{path}:/workbook/createSession
Content-Type: application/json

{
  "persistChanges": true
}

Response:

{
  "persistChanges": true,
  "id": "cluster=PUS7&session=..."
}

Use the session ID in subsequent requests:

workbook-session-id: {session-id}

Close Session

POST /microsoft-excel/v1.0/me/drive/root:/{path}:/workbook/closeSession
workbook-session-id: {session-id}

Worksheet Operations

List Worksheets

GET /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/worksheets

Response:

{
  "value": [
    {
      "id": "{00000000-0001-0000-0000-000000000000}",
      "name": "Sheet1",
      "position": 0,
      "visibility": "Visible"
    }
  ]
}

Get Worksheet

GET /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/worksheets('Sheet1')

Create Worksheet

POST /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/worksheets
Content-Type: application/json

{
  "name": "NewSheet"
}

Update Worksheet

PATCH /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/worksheets('Sheet1')
Content-Type: application/json

{
  "name": "RenamedSheet",
  "position": 2
}

Delete Worksheet

DELETE /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/worksheets('{worksheet-id}')

Returns 204 No Content on success.

Range Operations

Get Range

GET /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/worksheets('Sheet1')/range(address='A1:B2')

Response:

{
  "address": "Sheet1!A1:B2",
  "values": [
    ["Hello", "World"],
    [1, 2]
  ],
  "formulas": [
    ["Hello", "World"],
    [1, 2]
  ],
  "text": [
    ["Hello", "World"],
    ["1", "2"]
  ],
  "numberFormat": [
    ["General", "General"],
    ["General", "General"]
  ],
  "rowCount": 2,
  "columnCount": 2
}

Get Used Range

GET /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/worksheets('Sheet1')/usedRange

Update Range

PATCH /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/worksheets('Sheet1')/range(address='A1:B2')
Content-Type: application/json

{
  "values": [
    ["Updated", "Values"],
    [100, 200]
  ]
}

Clear Range

POST /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/worksheets('Sheet1')/range(address='A1:B2')/clear
Content-Type: application/json

{
  "applyTo": "All"
}

Options: All, Formats, Contents

Table Operations

List Tables

GET /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/worksheets('Sheet1')/tables

Create Table from Range

POST /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/worksheets('Sheet1')/tables/add
Content-Type: application/json

{
  "address": "A1:C4",
  "hasHeaders": true
}

Response:

{
  "id": "{6D182180-5F5F-448B-9E9C-377A5251CFC5}",
  "name": "Table1",
  "showHeaders": true,
  "showTotals": false,
  "style": "TableStyleMedium2"
}

Get Table

GET /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/tables('Table1')

Update Table

PATCH /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/tables('Table1')
Content-Type: application/json

{
  "name": "PeopleTable",
  "showTotals": true
}

Get Table Rows

GET /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/tables('Table1')/rows

Response:

{
  "value": [
    {
      "index": 0,
      "values": [["Alice", 30, "NYC"]]
    },
    {
      "index": 1,
      "values": [["Bob", 25, "LA"]]
    }
  ]
}

Add Table Row

POST /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/tables('Table1')/rows
Content-Type: application/json

{
  "values": [["Carol", 35, "Chicago"]]
}

Delete Table Row

DELETE /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/tables('Table1')/rows/itemAt(index=0)

Returns 204 No Content on success.

Get Table Columns

GET /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/tables('Table1')/columns

Add Table Column

POST /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/tables('Table1')/columns
Content-Type: application/json

{
  "values": [["Email"], ["[email protected]"], ["[email protected]"]]
}

Named Items

List Named Items

GET /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/names

Charts

List Charts

GET /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/worksheets('Sheet1')/charts

Add Chart

POST /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/worksheets('Sheet1')/charts/add
Content-Type: application/json

{
  "type": "ColumnClustered",
  "sourceData": "A1:C4",
  "seriesBy": "Auto"
}

Code Examples

JavaScript

// Get range values
const response = await fetch(
  "https://gateway.maton.ai/microsoft-excel/v1.0/me/drive/root:/data.xlsx:/workbook/worksheets('Sheet1')/range(address='A1:B10')",
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);
const data = await response.json();
console.log(data.values);

Python

import os
import requests

# Update range values
response = requests.patch(
    "https://gateway.maton.ai/microsoft-excel/v1.0/me/drive/root:/data.xlsx:/workbook/worksheets('Sheet1')/range(address='A1:B2')",
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
    json={'values': [['Name', 'Age'], ['Alice', 30]]}
)
print(response.json())

Notes

• Only .xlsx files are supported (not legacy .xls)
• Worksheet names with special characters need URL encoding
• Table and worksheet IDs containing { and } must be URL-encoded (%7B and %7D)
• Sessions expire after ~5 minutes of inactivity (persistent) or ~7 minutes (non-persistent)
• Use null in value arrays to skip updating specific cells
• Blank cells should use "" (empty string)
• Range addresses use A1 notation (e.g., A1:C10, Sheet1!A1:B5)
• IMPORTANT: When using curl commands, use curl -g when URLs contain parentheses to disable glob parsing
• IMPORTANT: When piping curl output to jq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments

Error Handling

Common Error Codes

Troubleshooting: API Key Issues

1. Check that the MATON_API_KEY environment variable is set:

echo $MATON_API_KEY

2. Verify the API key is valid by listing connections:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Troubleshooting: Invalid App Name

1. Ensure your URL path starts with microsoft-excel. For example:

• Correct: https://gateway.maton.ai/microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/worksheets
• Incorrect: https://gateway.maton.ai/v1.0/me/drive/root:/workbook.xlsx:/workbook/worksheets

Resources

• Microsoft Graph Excel API Overview
• Working with Excel in Microsoft Graph
• Excel Workbook Resource
• Excel Worksheet Resource
• Excel Range Resource
• Excel Table Resource
• Maton Community
• Maton Support