AI Agent 集成

cz-cli 的重要价值是让 AI Agent 拥有可控、可审计的 ClickZetta 操作入口。你可以在 Claude Code、Cursor、Kiro、Hermes 等工具中，让 Agent 通过命令行调用 cz-cli。

推荐给 Agent 的提示词

将下面这段话发给你的 AI Agent：

你可以使用 cz-cli 操作 ClickZetta Lakehouse。请先运行 cz-cli status 确认连接；涉及写操作、任务发布、补数、删除、下线等高风险动作时，必须先给出执行计划并等待我确认；查询和巡检可以直接执行，结果请用简明表格或要点总结。

常见自然语言请求

下面示例中的 <profile>、<task_name>、<job_id> 需要替换成你自己的连接配置、任务名和 Job ID。建议让 Agent 先执行 cz-cli -p <profile> status 确认连接可用。

请使用 <profile> 环境，先确认 cz-cli 连接状态，然后列出当前 workspace 中有哪些 schema，再列出 public schema 下的前 20 张表。 请使用测试环境 <profile>，帮我在 demo schema 下创建一张订单明细表，插入几行测试数据，然后验证能查到数据。执行写操作前请先给出计划并等待我确认。 请使用 <profile> 环境，检查任务 <task_name> 今天是否有失败运行。如果有，请查看运行详情和日志，并给出失败原因与修复建议。 请使用 <profile> 环境，分析 SQL job <job_id> 的执行情况，查看 job 状态、结果和执行 profile，判断是否存在性能瓶颈。

通过 cz-cli 自带 Agent 入口执行

如果当前环境已经配置好 cz-cli Agent 所需的大模型参数，也可以直接运行：

cz-cli -p <profile> agent run "帮我检查今天失败的调度任务，并按失败原因分类"

在企业机器人场景中使用

如果你使用 Hermes 等企业机器人承载 AI Agent，建议将 cz-cli 安装在机器人执行环境中，并采用以下策略：

• 只给机器人配置必要的 ClickZetta 权限，避免使用高权限管理员账号。
• 对写入、删除、发布、下线、补数等操作启用人工确认。
• 对可访问机器人的用户做白名单或审批控制。
• 将 profile、PAT、密码等凭据放在受控环境变量或本机配置中，不要写入公开文档、聊天记录或代码仓库。

配置 AI Agent 大模型（agent llm）

cz-cli agent run

~/.clickzetta/llm.json

~/.clickzetta/profiles.toml

方式一：使用

cz-cli login

cz-cli login

配置云器内置 LLM（推荐，由 AI Gateway 提供）

云器内置 LLM 通过 AI Gateway 统一提供，无需单独申请模型 API Key。使用

cz-cli login

cz-cli login prod

登录会在浏览器中完成。命令中的

prod

方式二：接入外部 LLM

支持任何 OpenAI 兼容接口。如果企业已有 AI Gateway，直接将其 Endpoint 填入即可：

使用 AI Gateway（企业自建或云器托管）

cz-cli agent llm add my-gateway \ --provider openai-compatible \ --base-url https://<your-instance>.clickzetta.com/gateway/v1 \ --api-key <AI-Gateway-API-Key>

直接接入 OpenAI / GPT

cz-cli agent llm add my-openai \ --provider openai \ --api-key $OPENAI_API_KEY

其他 OpenAI 兼容网关

cz-cli agent llm add my-relay \ --provider openai-compatible \ --base-url https://your-gateway.example.com/v1 \ --api-key <API_KEY>

验证和管理

查看当前激活的 LLM 及所有配置：

cz-cli agent llm show

列出所有已配置的 LLM：

cz-cli agent llm list

测试连通性：

cz-cli agent llm test my-openai

列出配置项可用的模型：

cz-cli agent llm models my-openai

设置默认模型时必须使用完整的

<配置名>/<模型ID>

cz-cli agent llm use my-openai/gpt-4o

删除某个 LLM 配置：

cz-cli agent llm remove my-openai

cz-cli login

cz-cli agent llm add

cz-cli agent run

相关文档

cz-cli 文档

• 安装配置指南 — 安装、Profile 配置、基本使用
• SQL 执行与数据探索 — sql、schema、table 命令参考
• Studio 任务开发与运维 — 任务管理、runs、补数

Lakehouse 相关文档

• 深入使用 Studio — Studio Web 界面完整操作指南
• 工作空间 — 用户管理、权限体系
• ClickZetta-CLI — cz-cli 概览与 Agent 价值说明