GHL CRM 精通 — GoHighLevel API v2 技能

本技能的作用

赋予您的智能体对 GoHighLevel 的完整操作权限：读取、写入及实时会话管理。专为 CRM 自动化智能体设计（如预约设置、线索筛选、销售管道管理）。

联系人操作

• contacts list — 分页列出联系人
• contacts get — 根据 ID 获取完整联系人记录（姓名、邮箱、电话、公司、标签、自定义字段等）
• contacts search — 通过邮箱查找联系人
• contacts search-phone — 通过电话号码查找联系人
• contacts update — 更新任意联系人字段（公司、标签、自定义字段等）
• contacts add-tags — 为联系人添加标签
• contacts remove-tag — 从联系人中移除指定标签

会话操作（实时）

• conversations list — 列出最近的会话
• conversations get — 获取某联系人的完整会话历史（含最近 20 条消息，含方向、类型与时间戳）
• conversations send — 通过 GHL 发送短信、邮件或私信回复。这是智能体响应线索的主要方式。

备注操作

• notes add — 向联系人记录中添加调研笔记、通话摘要或交互日志
• notes list — 查看某联系人已有的备注

销售管道与商机

• opportunities list — 列出销售管道中的项目
• opportunities get — 获取商机的完整详情
• opportunities update — 将商机移至不同销售阶段

日历

• calendars list — 列出可用日历
• calendars events — 列出某日历下的所有事件

标签、表单与工作流

• tags list — 列出该 Location 下全部标签
• forms list — 列出全部表单
• forms submissions — 获取指定表单的全部提交记录
• workflows list — 列出工作流（仅读取）
• workflows trigger — 为某联系人触发工作流（严禁创建/编辑/删除）

系统

• health — 测试 GHL API 连接状态

实时会话模式

智能体使用本技能实现即时线索响应。典型流程如下：

首次触达（新线索，尚无前期调研）：

1. contacts search-phone 或 contacts search — 查找联系人
2. contacts get — 拉取完整联系人记录
3. notes list — 检查是否存在已有调研笔记
4. 若无调研笔记 → 执行身份核验（由独立技能/流程完成）
5. conversations get — 读取会话历史
6. 撰写个性化响应内容
7. conversations send — 通过 GHL 发送回复
8. notes add — 记录调研发现及已发送内容

后续跟进消息（联系人已完成前期调研）：

1. contacts get — 拉取联系人记录（其中已包含调研笔记）
2. conversations get — 读取最新消息
3. 撰写上下文相关的回复（目标响应时长：15–30 秒）
4. conversations send — 发送回复
5. notes add — 简要记录本次交互

核心原则：每位联系人的调研仅执行一次。此后，智能体仅需读取自身笔记与会话历史，即可快速响应。目标是实现类实时聊天体验——后续跟进响应控制在 30 秒以内。

前置条件

必需的环境变量（须在您的 .env 文件中设置）：

GHL_API_KEY=your-private-integration-token
GHL_LOCATION_ID=your-location-id

必需运行时：python3（macOS 自带；可通过 python3 --version 验证版本）。

获取您的 GHL 凭据

1. 登录 GoHighLevel → 设置 → 集成 → 私有集成 → 创建新集成
2. 为部署场景合理命名该集成
3. 启用全部必需权限范围：
   • contacts.readonly, contacts.write
   • conversations.readonly, conversations.write
   • conversations/message.readonly, conversations/message.write
   • opportunities.readonly, opportunities.write
   • calendars.readonly, calendars.write
   • calendars/events.readonly, calendars/events.write
   • locations/tags.readonly, locations/tags.write
   • locations/tasks.readonly, locations/tasks.write
   • forms.readonly, workflows.readonly
   • payments/transactions.readonly, locations.readonly
   • invoices.readonly, invoices.write, users.readonly
4. 复制私有集成 Token → 填入 .env 中的 GHL_API_KEY
5. 设置 → 企业信息 → 复制 Location ID → 填入 .env 中的 GHL_LOCATION_ID

使用方法

所有命令均通过内置 Python CLI 脚本执行，路径为 {baseDir}/scripts/ghl_api.py：

export GHL_API_KEY=$(grep GHL_API_KEY ~/.openclaw/.env | cut -d= -f2)
export GHL_LOCATION_ID=$(grep GHL_LOCATION_ID ~/.openclaw/.env | cut -d= -f2)

# 测试连接
python3 {baseDir}/scripts/ghl_api.py health

# 测试联系人查询
python3 {baseDir}/scripts/ghl_api.py contacts list --limit 1

# 测试会话读取
python3 {baseDir}/scripts/ghl_api.py conversations get --contact-id "YOUR_CONTACT_ID"

# 发送消息
python3 {baseDir}/scripts/ghl_api.py conversations send --contact-id "CONTACT_ID" --message "Hello" --type sms

# 添加备注
python3 {baseDir}/scripts/ghl_api.py notes add --contact-id "CONTACT_ID" --body "Research findings..."

安全防护机制（不可协商）

1. 禁止手动创建联系人 — GHL 在表单提交、收到短信或私信时自动创建联系人。手动创建易引发重复记录。若联系人不存在，请将其标记至对应渠道处理。
2. 禁止未经 Slack 明确人工确认即删除联系人
3. 禁止未经人工审批即批量发送短信
4. 禁止修改工作流 — 仅允许触发（trigger），严禁创建（create）、编辑（edit）或删除（delete）
5. 每次写入操作均须记录日志 — 所有 conversations send 与 notes add 操作均输出带时间戳的日志行
6. TCPA 合规性 — 不得在收件人本地时区晚 9 点至次日早 8 点之间发送短信（该限制由 TCPA 处理层强制执行，非本技能职责）

网络端点

本技能仅连接 GoHighLevel 官方 API：

• https://services.leadconnectorhq.com — GHL API v2（涵盖全部操作）

不访问任何其他外部端点。所有凭据仅从本地环境变量读取。

更新日志

v1.3.0（2026 年 3 月）

• 新增 metadata.openclaw 前置元数据声明（requires.env、requires.bins、primaryEnv），以满足 ClawHub 安全合规要求
• 新增 {baseDir} 引用，支持技能路径可移植性
• 补充明确的网络端点说明文档
• 更新 _meta.json，明确运行时与凭据依赖项
• 泛化智能体相关表述，提升跨部署场景兼容性

v1.2.0（2026 年 3 月）

• 新增 conversations send、notes list、contacts search-phone
• 新增实时会话模式说明文档

v1.0.0（2026 年 3 月）

• 初始发布：共 24 个接口，覆盖联系人、会话、备注、商机、日历、标签、表单与工作流模块