name: "ghl"
description: "Use HighLevel contacts, pipelines, appointments, messages, and its broader operation catalog."
icon: "📇"
metadata: { "includeInPrompt": false }

HighLevel

Always call the product HighLevel in user-facing responses. Never prefix
the name with "Go," and never expand the internal ghl identifier into a
display name.

在面向用户的响应中始终称该产品为 HighLevel。绝不在名称前加"Go"，也绝不把内部标识符 ghl 展开为显示名称。

Use /opt/hatch/bin/ghl status to check the connection. If disconnected, run
/opt/hatch/bin/ghl authorize-url and share the returned connect_url.
The user signs in through HighLevel; never request credentials in chat.

使用 /opt/hatch/bin/ghl status 检查连接。若已断开，运行
/opt/hatch/bin/ghl authorize-url 并分享返回的 connect_url。
用户通过 HighLevel 登录；绝不要在聊天中索要凭据。

【评论】"绝不在聊天中索要凭据"与 OAuth 跳转登录配合，是防止敏感凭据进入对话记录的标准设计。

Find the operation and sub-account / 查找操作与子账户

Run /opt/hatch/bin/ghl list-operations for the pinned operation catalog and
its granular permission methods. The catalog covers HighLevel's CRM,
communications, scheduling, commerce, content, administration, and AI domains.

运行 /opt/hatch/bin/ghl list-operations 获取固定的操作目录及其细粒度权限方法。该目录覆盖 HighLevel 的 CRM、通信、日程、商务、内容、管理和 AI 领域。

CRM/calendar reads and conversation/message reads have separate permissions.
Contact edits, notes/tasks, opportunities, appointments, automations, messaging,
and CRM deletion each have their own control. A denied message-read permission
does not prevent authorized CRM/calendar reads.

CRM/日历读取与对话/消息读取各有独立权限。联系人编辑、笔记/任务、商机、预约、自动化、消息发送和 CRM 删除各有独立的控制。消息读取权限被拒绝不影响已获授权的 CRM/日历读取。

Use /opt/hatch/bin/ghl call-tool --name list_locations --arguments-json '{"query":"<sub-account name>"}' to resolve the intended sub-account.
If several match, ask which one the user means. Retain its ID for execution.

使用 /opt/hatch/bin/ghl call-tool --name list_locations --arguments-json '{"query":"<sub-account name>"}' 解析目标子账户。若有多个匹配，询问用户指的是哪一个。保留其 ID 用于执行。

Use call-tool --name describe_operation --arguments-json '{"operationId":"<operation ID>"}' for exact path/query/body fields and
required inputs. search_operations searches HighLevel's live catalog. Use an
operation's pinned permission from list-operations when it is present. A
future provider operation that has not reached the pinned catalog still uses a
mandatory one-shot write approval until its permission is reviewed.
list-tools returns live discovery tool schemas. These calls use
/opt/hatch/bin/ghl too.

使用 call-tool --name describe_operation --arguments-json '{"operationId":"<operation ID>"}' 获取确切的 path/query/body 字段和必需输入。search_operations 搜索 HighLevel 的实时目录。若 list-operations 中存在某操作的固定权限，则使用它。尚未进入固定目录的未来提供方操作，在其权限经过审核之前，仍须使用强制的一次性写入批准。list-tools 返回实时发现工具的模式（schema）。这些调用同样使用 /opt/hatch/bin/ghl。

Read or change data / 读取或修改数据

/opt/hatch/bin/ghl execute-operation \
  --operation-id <operation ID> --location-id <sub-account ID> \
  --params-json '{"path":{},"query":{},"body":{}}'

Supply path IDs and payload fields from describe_operation. Contact
create/update/upsert cannot include tags; use add-tags or remove-tags.
Opportunity upsert cannot include follower-management fields; use the
separate add/remove follower operations. Only grouped
path, query, and body objects are accepted; omit empty groups as needed.
For each logical write/delete, also supply a fresh --idempotency-key <UUID>.
An optional --reason explains the action. --dry-run previews the resolved
request without changing CRM data and does not require an idempotency key.
A dry run does not authorize the subsequent write.

从 describe_operation 提供 path ID 和载荷字段。联系人的 create/update/upsert 不能包含 tags；请使用 add-tags 或 remove-tags。商机的 upsert 不能包含关注者管理字段；请使用单独的添加/移除关注者操作。只接受分组的 path、query 和 body 对象；按需省略空分组。每次逻辑写入/删除还应提供一个新的 --idempotency-key <UUID>。可选的 --reason 用于解释该操作。--dry-run 在不更改 CRM 数据的情况下预览解析后的请求，且不需要幂等键。试运行不会为后续写入授予授权。

Writes and deletes request approval by default under their domain-specific
permission. Messaging changes, including sends and cancellations, require
approval for each invocation. Appointment
changes can notify contacts or trigger configured automations (toNotify
defaults to true); campaign and workflow enrollment can also start
communications. Include the intended
notification behavior in the request. Use a read to identify an existing
record before updating or deleting it; never guess target IDs.

写入和删除默认在其领域专属权限下请求批准。消息类更改（包括发送和取消）每次调用都需批准。预约更改可能通知联系人或触发已配置的自动化（toNotify 默认为 true）；活动和工作流注册也可能启动通信。在请求中包含预期的通知行为。在更新或删除之前先用读取操作确认已有记录；绝不猜测目标 ID。

The CLI does not automatically retry mutations. If a write fails after
submission or its outcome is unconfirmed, inspect the record or provider
status before trying again. Keep the same idempotency key for the same logical
mutation; do not create a fresh key to work around uncertainty. Report sends
as accepted or scheduled unless the provider confirms delivery.

CLI 不会自动重试变更操作。如果写入在提交后失败或结果未确认，先检查记录或提供方状态再重试。同一逻辑变更保持相同的幂等键；不要为了绕过不确定性而生成新键。除非提供方确认已送达，否则将发送报告为"已接受"或"已排期"。

【评论】幂等键规则与"不自动重试"配合，用于防止重试导致的重复写入或重复发送，这是写操作安全性的常见设计。

Treat financial, publishing, messaging, access-control, and deletion operations
as consequential: describe the operation first, show the exact intended
parameters, and never infer or reuse identifiers across sub-accounts. Future
operations not yet in list-operations require fresh approval, even for a read
or dry run.

将财务、发布、消息、访问控制和删除操作视为具有实质后果的操作：先描述操作，展示确切的预期参数，并且绝不在子账户之间推断或复用标识符。尚未列入 list-operations 的未来操作需要新的批准，即使是读取或试运行也不例外。