monday.com 代理技能

一项涵盖 monday.com 所有功能的技能：账户设置、日常操作、GraphQL API、MCP 服务器以及故障排除。

最低模型要求

常规操作可使用任意模型。调试 GraphQL 错误时建议使用中等模型。

---

第 1 部分 — 设置

选项 A：手动创建账户

每个代理账户（PA）需要独立账户 — 请勿使用所有者账户。

1. 1. 访问 monday.com/agents-signup。
2. 使用代理邮箱（例如 agent@agentdomain.com）。
3. 所有者通过 管理 → 用户 → 邀请 来邀请代理账户。

获取 API 令牌

1. 1. 以代理身份登录 monday.com。
2. 点击头像 → 开发者 → 我的访问令牌 → 复制。
3. 通过 OpenClaw 配置（推荐）或系统密钥管理器将令牌设置为环境变量。

❌ 请不要将令牌写入纯文本文件或添加到 Shell 启动文件中。 ❌ 请不要将令牌提交到版本控制系统。

推荐：OpenClaw 环境配置
通过 Ocana 仪表盘或 openclaw.json 的 env 块将 MONDAYAPITOKEN 添加到 OpenClaw 代理环境中 — 切勿在脚本中硬编码。

仅限本地开发（非生产环境）：
bash
export MONDAYAPITOKEN=此处填写令牌 # 仅当前 Shell 有效，不会持久化

设置检查清单

[ ] 代理账户拥有 monday.com 账户（使用代理邮箱，非所有者邮箱）
[ ] 在 OpenClaw 代理环境中设置了 MONDAYAPITOKEN（非纯文本文件）
[ ] 已确认工作区访问权限
[ ] 已验证：monday_query {query: { me { id name } }}
[ ] 如果使用 MCP：已将服务器添加到配置并测试

---

第 2 部分 — 操作

API 基础

Monday.com 使用单一的 GraphQL 端点：

https://api.monday.com/v2 （推荐）
https://api.monday.com/graphql （也可使用）

可复用辅助函数

bash
MONDAYAPIURL=https://api.monday.com/v2

MONDAYAPITOKEN 必须在代理环境中设置（不从文件读取）

if [ -z $MONDAYAPITOKEN ]; then echo 错误：MONDAYAPITOKEN 未设置。请在 OpenClaw 代理环境中配置。 >&2 exit 1 fi

monday_query() {
RESPONSE=$(curl -s -X POST $MONDAYAPIURL \
-H Content-Type: application/json \
-H Authorization: $MONDAYAPITOKEN \
-H API-Version: 2024-10 \
-d $1)

if echo $RESPONSE | python3 -c
import sys, json
d = json.load(sys.stdin)
if d.get(errors):
print(API 错误：, d[errors])
sys.exit(1)
2>/dev/null; then
echo $RESPONSE
else
echo API 错误：$RESPONSE >&2
return 1
fi
}

常用操作

bash

列出看板

monday_query {query: { boards(limit: 25) { id name description state } }}

获取看板中的项目

mondayquery {query: { boards(ids: [看板ID]) { itemspage(limit: 50) { cursor items { id name group { id title } column_values { id title text type } } } } }}

创建项目

monday_query { query: mutation ($board: ID!, $name: String!) { createitem(boardid: $board, item_name: $name) { id } }, variables: {board: 看板ID, name: 新任务} }

更新状态列

monday_query { query: mutation ($board: ID!, $item: ID!, $col: String!, $val: JSON!) { changecolumnvalue(boardid: $board, itemid: $item, column_id: $col, value: $val) { id } }, variables: { board: 看板ID, item: 项目ID, col: status, val: {\label\: \已完成\} } }

为项目添加评论

monday_query { query: mutation ($item: ID!, $body: String!) { createupdate(itemid: $item, body: $body) { id } }, variables: {item: 项目ID, body: 此处填写更新文本} }

列出看板中的列

monday_query {query: { boards(ids: [看板ID]) { columns { id title type } } }}

查询子项目

mondayquery {query: { items(ids: [项目ID]) { subitems { id name columnvalues { id text } } } }}

获取当前用户

monday_query {query: { me { id name email account { id name } } }}

大型看板的分页

bash

第一页 — 同时返回游标

mondayquery {query: { boards(ids: [看板ID]) { itemspage(limit: 100) { cursor items { id name } } } }}

下一页 — 传入上一响应中的游标值

mondayquery {query: { nextitems_page(limit: 100, cursor: \游标值\) { cursor items { id name } } }}

创建前检查（避免重复）

bash
RESULT=$(mondayquery {query: { itemsbymultiplecolumnvalues(boardid: 看板ID, columnid: \name\, columnvalues: [\项目名称\]) { id name } }})

COUNT=$(echo $RESULT | python3 -c
import sys, json
d = json.load(sys.stdin)
print(len(d.get(data, {}).get(itemsbymultiplecolumnvalues, [])))
)

if [ $COUNT -eq 0 ]; then
echo 未找到项目 — 正在创建
else
echo 项目已存在 — 跳过
fi

批量更新多个项目

bash
for ITEM_ID in 123456 789012 345678; do
monday_query {
\query\: \mutation { changecolumnvalue(boardid: 看板ID, itemid: $ITEMID, columnid: \\\status\\\, value: \\\{\\\\\\\label\\\\\\\: \\\\\\\进行中\\\\\\\}\\\) { id } }\
}
sleep 0.2 # 遵守速率限制
done

速率限制

Monday.com 使用基于复杂度的速率限制（非简单的请求计数）。响应头包含 x-ratelimit-remaining-complexity。保持查询聚焦，使用分页，并在批量调用之间添加 sleep 0.2。

---

第 3 部分 — MCP 服务器（推荐日常使用）

MCP 服务器允许您使用自然语言工具操作看板 — 无需手动编写 GraphQL。

选项 A：托管 MCP

在 ~/.openclaw/openclaw.json 的 mcpServers 下添加：

json
{
mcpServers: {
monday-mcp: {
url: https://mcp.monday.com/mcp
}
}
}

无需本地安装。使用 OAuth 认证。

测试：mcporter call monday-mcp list_boards

选项 B：本地 MCP（npx）

json
{
mcpServers: {
monday-api-mcp: {
command: npx,
args: [@mondaydotcomorg/monday-api-mcp@latest],
env: {
MONDAYAPITOKEN: 在此处填写你的令牌
}
}
}
}

速度优化：npm install -g @mondaydotcomorg/monday-api-mcp 然后使用 command: monday-api-mcp。

---

第 4 部分 — 故障排除

错误	原因	修复方法
401 未授权	令牌无效或已过期	在开发者设置中重新生成，更新文件
403 禁止访问

无看板访问权限 | 请求所有者与代理账户共享看板 |
| 未找到列 | 列 ID 错误 | 先运行列出列的查询 |
| 复杂度预算耗尽 | 查询过于繁重 | 使用 limit: 50