ClickHouse

通过聊天界面与 ClickHouse 交互——检查数据库、查看表结构，并通过 ClickHouse HTTP API 执行只读 SQL 分析查询（使用 API 密钥认证）。

本技能使用 ClawLink 提供托管连接流程与凭据，因此您无需自行配置 ClickHouse API 访问权限。

三步完成配置

工作原理

┌─────────────────┐     ┌──────────────┐     ┌──────────────────┐
│   OpenClaw      │────▶│   ClawLink   │────▶│ ClickHouse HTTP API│
│   (用户聊天)    │     │   (API 密钥) │     │ (SQL 查询)       │
└─────────────────┘     └──────────────┘     └──────────────────┘
         │                       │                       │
         │  1. 安装插件          │                       │
         │  2. 绑定设备           │                       │
         │  3. 连接 ClickHouse    │                       │
         │                       │  4. 安全密钥管理       │
         │                       │  5. 请求代理           │
         │                       │                       │
         ▼                       ▼                       ▼
   ┌──────────┐           ┌──────────┐           ┌──────────┐
   │  SKILL   │           │ 控制台   │           │ ClickHouse│
   │  文件    │           │ 认证     │           │ 查询     │
   └──────────┘           └──────────┘           └──────────┘

安装

从 ClawHub 安装已验证的 ClawLink 插件。用户确认后，请完成全部配置流程，以便在下一次 OpenClaw 聊天中可见 ClawLink 工具。

openclaw plugins install clawhub:clawlink-plugin
openclaw config set tools.alsoAllow '["clawlink-plugin"]' --strict-json
openclaw gateway restart

然后告知用户：“OpenClaw 已重启。请单独发送 /new 消息以开启新会话，随后再次请求 ClickHouse 功能。”

快速开始

# 列出所有数据库
clawlink_call_tool --tool "clickhouse_list_databases" --params '{}'

# 列出指定数据库中的所有表
clawlink_call_tool --tool "clickhouse_list_tables" --params '{"database": "default"}'

# 获取数据库结构概览
clawlink_call_tool --tool "clickhouse_get_database_schema" --params '{"database": "default"}'

认证机制

所有 ClickHouse 工具调用均由 ClawLink 自动完成身份认证，使用用户已连接的 ClickHouse 账户。

聊天中无需提供任何凭据。 ClawLink 安全地存储连接信息，并代表用户将凭据注入每次 ClickHouse 请求中。

建立连接

1. 安装 ClawLink 插件（参见上方“安装”章节）。
2. 若尚未配置，使用 clawlink_begin_pairing 命令绑定插件。
3. 访问 https://claw-link.dev/dashboard?add=clickhouse 并连接 ClickHouse。
4. 调用 clawlink_list_integrations 验证连接是否已激活。

连接管理

列出所有连接

clawlink_list_integrations

响应：返回所有已连接的集成项。请在列表中查找 clickhouse。

验证连接状态

clawlink_list_tools --integration clickhouse

响应：返回 ClickHouse 的实时工具目录。

重新连接

若 ClickHouse 工具缺失或连接显示错误：

1. 引导用户访问 https://claw-link.dev/dashboard?add=clickhouse
2. 待用户确认后，调用 clawlink_list_integrations 进行验证
3. 再调用 clawlink_list_tools --integration clickhouse

安全与权限

• ClawLink 中的 ClickHouse 查询默认为只读设计——不暴露 INSERT、ALTER、DROP 或 TRUNCATE 等写操作。
• 对大规模结果集或高开销查询（如全表扫描、无 LIMIT 的 GROUP BY）需用户显式确认后方可执行。
• 请避免运行可能导致表锁或资源过度消耗的查询。

工具参考

结构发现

查询执行

界面

代码示例

列出所有数据库

clawlink_call_tool --tool "clickhouse_list_databases" 
  --params '{}'

获取数据库结构

clawlink_call_tool --tool "clickhouse_get_database_schema" 
  --params '{
    "database": "analytics"
  }'

执行简单查询

clawlink_call_tool --tool "clickhouse_execute_query" 
  --params '{
    "query": "SELECT * FROM events WHERE date >= today() - 7 LIMIT 100"
  }'

获取表结构

clawlink_call_tool --tool "clickhouse_get_table_schema" 
  --params '{
    "database": "analytics",
    "table": "events"
  }'

发现工作流

1. 调用 clawlink_list_integrations 确认 ClickHouse 是否已连接。
2. 调用 clawlink_list_tools --integration clickhouse 查看实时工具目录。
3. 将返回的工具列表视为唯一可信来源。切勿猜测或假设存在哪些工具。
4. 若用户描述某项能力但无法确定具体工具，可使用 clawlink_search_tools 并传入简短关键词与集成名称 clickhouse 进行搜索。
5. 若未出现任何 ClickHouse 工具，请引导用户访问 https://claw-link.dev/dashboard?add=clickhouse。

执行工作流

┌─────────────────────────────────────────────────────────────┐
│  结构发现（始终优先执行）                                   │
│  list_databases → list_tables → get_table_schema            │
│                                                             │
│  示例：发现表 → 理解结构 → 再发起查询                         │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  查询执行（仅限只读）                                       │
│  describe → preview → confirm → execute                     │
│                                                             │
│  示例：描述查询意图 → 预览结果 → 用户确认 → 执行只读查询         │
└─────────────────────────────────────────────────────────────┘

1. 执行查询前，务必先使用 clickhouse_list_databases 和 clickhouse_get_database_schema 探索结构。
2. 对于不熟悉的表，请调用 clickhouse_get_table_schema 了解字段名与数据类型。
3. 查询应尽量带 WHERE 条件与 LIMIT 子句——尽可能避免全表扫描。
4. 对于大型或复杂查询，请在执行前向用户确认预期结果集大小。
5. 若工具调用失败，请如实反馈真实错误，切勿伪造结果。

注意事项

• ClickHouse SQL 语法与标准 SQL 不同，请使用 ClickHouse 特有的函数与语法。
• 所有查询均为只读——通过 ClawLink 工具无法修改任何数据。
• 请使用 LIMIT 防止意外返回过大的结果集。
• 表结构响应中可能包含示例数据，可用于理解字段的数据类型。
• Play 界面提供基于 HTML 的交互式 UI，并集成 Monaco Editor，支持手动编写查询。

错误处理

问题排查：工具不可见

1. 检查 ClawLink 插件是否已安装：

   openclaw plugins list
   

2. 若插件已安装但工具未显示，请提示用户单独发送 /new 消息以重新加载工具目录。
3. 若新开会话仍未解决，请运行：

   openclaw config set tools.alsoAllow '["clawlink-plugin"]' --strict-json
   openclaw gateway restart
   

4. 重启完成后，请提示用户再次发送 /new 并重试。

问题排查：查询报错

1. 务必首先使用结构发现类工具核实表名与字段名。
2. 使用 clickhouse_list_databases 确认数据库名称。
3. 使用 LIMIT 先测试小规模结果集，验证查询逻辑正确性。

相关资源

• ClickHouse 官方文档
• ClickHouse SQL 参考手册
• ClawLink：https://claw-link.dev/?utm_source=clawhub&utm_medium=referral&utm_content=clickhouse-analytics
• ClawLink 文档：https://docs.claw-link.dev/openclaw
• ClawLink 验证页：https://claw-link.dev/verify

相关技能

• Datadog — 用于 Datadog 可观测性与指标监控
• Snowflake — 用于 Snowflake 数据仓库查询
• PostgreSQL — 用于 PostgreSQL 数据库操作

由 ClawLink 提供支持 — OpenClaw 的集成枢纽