Codex + HAP

OpenAI 的编程 Agent，在终端里读写代码、运行命令，也可以在 IDE 插件里使用。连接 HAP 之后，你可以在 Codex 里用自然语言搭建应用、修改应用、查询数据，权限仍由 HAP 决定。

快速开始

四步完成连接。

安装 Codex

npm install -g @openai/codex

添加 HAP MCP

按下方「MCP 配置」完成，约 1 分钟。

安装 HAP Skills

npx skills add mingdaocom/hap-skills

打开 Codex，说出需求

codex

对 Agent 说

查一下「订单」表上个月各产品的销售额前 5，用表格给我

MCP 配置

把 HAP 的远程 MCP 服务接入 Codex。服务地址：https://api.mingdao.com/mcp，用个人访问令牌鉴权。

终端

export HAP_PAT="你的个人访问令牌"
codex mcp add hap --url https://api.mingdao.com/mcp --bearer-token-env-var HAP_PAT

或写入 ~/.codex/config.toml

[mcp_servers.hap]
url = "https://api.mingdao.com/mcp"
bearer_token_env_var = "HAP_PAT"

把 HAP_PAT 换成你的个人访问令牌（工作台「连接 AI」→ 个人）。令牌只放在本机，不要提交到代码仓库。

验证：codex mcp list

hap 命令行

能执行终端命令的 Agent，可以直接调用 hap 精确地改应用、查数据。每条命令都支持 --json，方便 Agent 解析。

安装与登录

pip install hap-cli
hap auth login
hap auth whoami

常用命令

hap auth list-my-orgs
hap app list
hap app select APP_ID
hap worksheet list
hap --json worksheet record list WORKSHEET_ID --page-size 10

HAP Skills

一组面向 HAP 的 Agent 技能，覆盖 CLI、MCP 与 API 三种方式。可以整组安装，也可以只装需要的那一个。

安装全部

npx skills add mingdaocom/hap-skills

只装一个

npx skills add mingdaocom/hap-skills --skill hap-mcp-app-builder

对 Agent 说

帮我安装这个skills: https://github.com/mingdaocom/hap-skills

hap-cli

装好并登录 hap，用 hap guide 获取当前版本的命令地图

hap-cli-app-editor

对已有应用做精确的局部修改

hap-cli-data-query

多条件筛选、分组与透视统计

hap-cli-environments

多环境 / 多账号的操作守则

hap-mcp-app-builder

方案设计 → 确认 → 全自动搭建应用

hap-apiv3-data

V3 接口鉴权、筛选与记录增删改

hap-api-website

用 HAP 当后端搭建网站

hap-view-plugin

开发 HAP 自定义视图插件

示例提示词

复制到 Codex 里试试。

对 Agent 说

查一下「订单」表上个月各产品的销售额前 5，用表格给我

对 Agent 说

列出当前 HAP MCP 可用的工具，并简要说明用途。先不要修改任何数据。

对 Agent 说

帮我搭建一个客户管理应用，先给我方案，确认后再动手

对 Agent 说

查询「客户管理」应用的工作表结构，只返回工作表名称和主要字段，不修改数据。

对 Agent 说

帮我查一下待办和未读消息，并总结要点

对 Agent 说

在「订单」表里加一个「交付日期」字段

对 Agent 说

查一下「销售」表上个月各产品的销售额前 5

对 Agent 说

给「采购申请」加一个工作流：金额超过 5 万需要总经理审批

常见工作流

MCP + hap-mcp-app-builder

从零搭建一个应用

说出业务诉求，例如「帮我搭建一个客户管理应用」
Agent 先给出方案（工作表、字段、关系、视图、流程）
你确认后，Agent 通过 MCP 自动完成搭建
中断了也可以一键续建

CLI + hap-cli-app-editor

修改已有应用

说清要改哪个应用的哪个元素
Agent 先读取应用的实时结构
加字段、改视图、调权限、加自定义动作
删除等破坏性操作前，会先向你确认

CLI + hap-cli-data-query

查数与统计

用自然语言描述想要的数据
Agent 写出筛选条件与透视统计
结果以表格或摘要返回
需要时再导出或写回工作表

API + hap-api-website

用 HAP 当后端做网站

在 HAP 里建好内容或订单工作表
Agent 生成前端项目并接好 HAP V3 接口
本地预览、调整界面
交给 HAP Compute 一条命令上线

CLI + hap-cli-environments

多个环境安全操作

用 hap auth login 授权多个环境或账号
说明要在哪个环境执行
环境不明确时，破坏性操作会先停下来确认

使用建议

第一次连接时，先用只读的提示词验证，例如「列出当前 HAP MCP 可用的工具」。
让 Agent 先给方案、再动手；删除、发布、改权限等操作要求它先向你确认。
授权了多个环境时，在提示词里说清要操作哪个环境。
令牌只放在本机的环境变量或配置文件里，分享配置前先脱敏。

常见问题

连接 Agent 之后，AI 的权限会变大吗？

不会。连接 MCP 或 CLI 不会扩大任何权限：Agent 只能做你这个账号（或这把应用密钥）本来就能做的事，所有操作照样受 HAP 的角色权限约束、留有日志。

MCP、CLI 和 Skills 有什么区别？该用哪个？

MCP 是远程服务，不用装任何东西，适合支持远程 MCP 的 Agent 对话式搭建应用；CLI（hap 命令行）在终端里运行，适合能执行命令的编程 Agent 精确地改应用、查数据；Skills 是写给 Agent 的操作指南，叠加在 MCP、CLI 或 API 之上，让 Agent 知道该怎么做。三者可以同时用。

个人访问令牌和应用密钥怎么选？

个人访问令牌（PAT）以你本人的身份操作，范围是你有权限的全部内容，通过 Authorization 请求头传入；应用密钥（HAP-Appkey / HAP-Sign）只作用于选定的一个应用，写在 MCP 地址的参数里，适合不支持自定义请求头的客户端。两者都在工作台「连接 AI」里生成。

私有部署可以用吗？

可以。MCP 请使用你所在环境生成的完整地址（保留路径前缀）；CLI 用 hap auth login https://你的域名登录即可。

我没有编程背景，也能用吗？

可以。WorkBuddy 这类桌面 Agent 只需要添加连接器；在任何 Agent 里，你都可以直接用中文描述需求，由 Agent 调用 HAP 完成。

排查问题

MCP 连接失败或返回未授权

确认组织已开启 API 访问策略，令牌没有过期，并且 Authorization 的值是“Bearer”加一个空格再加令牌。

hap 命令提示没有权限

运行 hap auth list-my-orgs，如果显示 CLI:off，需要组织管理员在组织管理后台 → 安全 → 数据与访问 → CLI 访问策略中开启。

浏览器登录回调失败

中断命令，把登录页上显示的令牌粘贴回终端；无界面的服务器可以用 hap auth login 你的环境 --token 你的令牌。

客户端不支持自定义请求头

改用应用授权：在应用的「API 文档 → 应用授权 → MCP」复制带 HAP-Appkey 与 HAP-Sign 的完整地址，直接填入 URL。

用 Codex 开始在 HAP 上构建

免费注册，生成令牌，几分钟就能让 Agent 开始干活。

免费开始开发者文档

Codex + HAP

快速开始

安装 Codex

添加 HAP MCP

安装 HAP Skills

打开 Codex，说出需求

MCP 配置

hap 命令行

HAP Skills

示例提示词

常见工作流

从零搭建一个应用

修改已有应用

查数与统计

用 HAP 当后端做网站

多个环境安全操作

使用建议

常见问题

排查问题

MCP 连接失败或返回未授权

hap 命令提示没有权限

浏览器登录回调失败

客户端不支持自定义请求头

其他 Agent

Cursor

GitHub Copilot

OpenCode

用 Codex 开始在 HAP 上构建