跳到主要内容

使用 OpenAPI Development Skill

alimail-openapi-development Skill 用于指导 Codex、Claude Code、OpenClaw 等开发型 Agent 设计、实现、评审和排查阿里邮箱 OpenAPI 集成。它包含应用鉴权、文档查询、安全边界和验证清单，不复制容易过期的完整接口文档。

适用场景​

  • 开发组织、域名、用户、部门、邮件组或公共联系人同步程序。
  • 开发邮件、附件、日历、隔离区或审计日志相关功能。
  • 使用应用 ID 和 Secret 获取 Token，并封装阿里邮箱 API 客户端。
  • 查询接口、Scope、请求字段、响应结构或错误码。
  • 排查 401、403、429、分页遗漏和 Server 选错等问题。

该 Skill 面向企业管理员在 API 开放平台创建的应用。使用个人 MCP token 操作单个邮箱时，应选择个人访问 Skill，不要混用两种凭证。

Skill 地址​

https://mailhelp.aliyun.com/docs/skills/alimail-openapi-development/SKILL.md

安装到 Codex​

mkdir -p ~/.codex/skills/alimail-openapi-development/agents
curl -fsSL https://mailhelp.aliyun.com/docs/skills/alimail-openapi-development/SKILL.md \
  -o ~/.codex/skills/alimail-openapi-development/SKILL.md
curl -fsSL https://mailhelp.aliyun.com/docs/skills/alimail-openapi-development/agents/openai.yaml \
  -o ~/.codex/skills/alimail-openapi-development/agents/openai.yaml

安装后新建任务或重启当前 Agent，使其重新发现 Skill。其他支持 Skill 的开发型 Agent 可以将同一目录复制到对应的用户级 Skill 目录。

在任务中调用​

Use $alimail-openapi-development to add a client that retrieves every department page to the
existing Java service. Search the official docs for the endpoint, scope, and pagination fields
first, then follow the project's existing OkHttp style and add unit tests. Do not call a live
environment or introduce another HTTP framework.

任务描述应明确目标资源、运行环境或地域、技术栈、读写动作，以及是否允许访问真实环境。

文档查询​

Skill 会先读取 Agent 入口：

https://mailhelp.aliyun.com/docs/llms.txt

再通过搜索接口按能力名、API 路径、Operation ID、字段名或错误码检索：

curl --get 'https://mailhelp.aliyun.com/docs/agent/search' \
  --data-urlencode 'q=list all departments' \
  --data-urlencode 'locale=zh-CN' \
  --data-urlencode 'kind=api' \
  --data-urlencode 'limit=10'

搜索结果中的 markdown_url 指向适合 Agent 阅读的接口页。Agent 应从具体页面确认 HTTP 方法、路径、Server、Scope、参数、响应、分页字段和错误码。

常用示例​

以下 Markdown 页面可以直接交给 Agent 阅读。地址会随当前站点解析到对应环境：

安全边界​

安装 Skill 不等于授权 Agent 调用生产接口。代码变更不会自动授权发送邮件、删除或移动邮件、批量修改资源、释放隔离邮件、创建或删除用户和域名等真实操作。

需要联调时，请明确目标环境、组织或邮箱、接口动作和资源范围。对于有外部影响或不可逆的操作，要求 Agent 在调用前列出动作与目标并再次确认。