OpenClacky：开源轻量化AI智能体框架，多级缓存降本+多模型统一接入

一、OpenClacky是什么

OpenClacky是由clacky-ai团队开源发布、基于MIT开源协议授权的轻量化开源本地AI智能体（Agent）框架项目，项目托管于GitHub开源平台，主打本地私有化部署、多厂商大模型API统一调度、智能对话缓存优化与自定义技能扩展能力，是面向个人开发者、小型工作室、企业运维人员的一站式AI客户端解决方案。

项目脱离云端封闭管控，不强制绑定任意一家大模型厂商，使用者仅需填入各家大模型API密钥即可快速对接主流商用开源大模型，兼顾命令行终端运行与可视化GUI图形界面两种使用形态，核心研发初衷是解决市面AI客户端调用成本高、上下文冗余消耗token、模型切换繁琐、无法自定义专属业务插件四大痛点。项目代码完全开源可二次修改、私有化打包部署，无内置付费捆绑组件，个人商用均在MIT协议许可范围内自由使用。

二、功能特色

2.1 多模型全兼容接入

• 无缝对接云端API模型：Claude全系列、OpenAI/GPT系列、DeepSeek、Kimi、MiniMax、智谱AI、通义千问等国内外主流大模型接口；

• 兼容本地部署开源大模型：Ollama托管的Llama3、Qwen、Mistral等本地离线模型，支持IP+端口直连本地推理服务，实现完全断网离线对话。

2.2 智能Token缓存优化（项目核心王牌功能）

高命中率上下文缓存机制是OpenClacky差异化核心，框架内置多级内存+本地文件双层缓存池：

1. 重复提问、相似语义问题自动命中历史缓存结果，无需重复消耗API计费Token；

2. 长会话冗余上下文自动精简裁剪，过滤无效历史对话字段，大幅降低大模型入参token开销；

3. 缓存文件采用加密json格式落地本地磁盘，重启程序缓存不丢失，自定义缓存有效期与缓存容量上限。

2.3 双端运行架构：CLI命令行 + GUI可视化界面

# CLI启动最简命令
openclacky run --api-key=xxx --model=deepseek-chat

1. CLI终端模式：适配服务器无桌面环境部署，可嵌入Shell脚本、自动化运维流程，对接Linux/Windows/macOS终端，支持批量批量指令问答、批量文档解析；

2. GUI图形界面：轻量化前端内嵌程序，开箱即用无需额外部署前端服务，可视化配置API密钥、会话管理、缓存参数、自定义技能插件，小白零代码配置。

2.4 自定义Skill技能插件系统

使用者通过简易JSON/少量Python代码编写自定义业务技能，插件挂载至OpenClacky后AI可自动调用对应能力，内置技能市场目录，支持社区共享插件：

• 内置原生技能：文档PDF解析、代码片段提取、表格数据整理、网页内容抓取；

• 可拓展自定义：企业库存查询、服务器运维巡检、本地文件批量处理、自动化文案生成等私有化业务插件。

2.5 会话隔离与多配置文件管理

支持创建多套独立配置文件，不同配置绑定不同API密钥、不同模型、不同缓存规则，实现工作/私人/测试三套环境完全隔离，配置文件以.conf后缀存于本地目录，一键切换配置。

2.6 跨操作系统全平台适配

原生适配Windows10+/macOS12+/Linux（Ubuntu/Debian/CentOS）三大桌面与服务器系统，提供预编译二进制安装包与源码编译两种安装方式。

三、技术细节

3.1 项目技术栈组成

1. 后端核心开发语言：Python3.10+，主体业务逻辑、API转发、缓存调度、技能引擎全部基于Python实现，保证跨平台兼容性；

2. GUI前端技术：内置PySide6轻量化桌面框架，无Chromium大型内核依赖，程序安装包体积控制在百MB级别，启动速度快；

3. 缓存存储技术：一级缓存使用Python内存字典（RAM实时缓存），二级持久化缓存采用本地JSON+Sqlite轻量数据库，避免海量缓存文件碎片化；

4. API调度层：自研统一请求适配器，对各大模型API入参、出参做标准化封装，屏蔽不同厂商接口字段差异，新增模型仅需编写简短适配器配置即可接入。

3.2 项目目录结构

openclacky/
├── core/     # 核心调度引擎、缓存算法、会话管理源码
├── adapters/   # 各大厂商大模型API适配器配置目录
├── gui/      # PySide6图形界面源码
├── cli/      # 命令行交互逻辑代码
├── skills/    # 原生内置技能+自定义插件存放目录
├── configs/    # 用户配置文件默认存储路径
├── cache/     # 本地持久化缓存目录
└── docs/     # 项目官方说明文档

3.3 缓存算法技术原理

OpenClacky采用语义相似度+精准字符串双重匹配缓存策略：

1. 精准匹配：用户输入完全一致时，直接调取缓存应答，零API调用；

2. 模糊语义匹配：基于内置轻量词向量算法，相似度高于预设阈值（可用户自定义0~1区间数值），复用历史缓存结果；

3. 缓存淘汰规则：采用LRU最近最少使用淘汰算法，到达自定义磁盘容量上限后自动清理长期未访问缓存，避免磁盘爆满。

3.4 技能插件运行机制

插件遵循标准化接口规范，插件加载时框架自动扫描skills目录下合规文件，挂载AI函数调用标识，当用户提问命中插件业务场景，智能体自动中断原生对话逻辑、调用本地插件执行任务，结果回传给大模型整理输出，全程插件运行在本地，数据不出本机。

四、应用场景

1. 个人日常办公场景
   普通办公人员接入DeepSeek、Kimi API，依托缓存功能降低月度API开销，利用PDF解析插件批量解析合同、报表文档，GUI可视化管理日常AI问答会话。

2. 程序员运维开发场景
   服务器Linux环境部署CLI版本OpenClacky，嵌入自动化Shell脚本，实现服务器日志自动解析、报错排查、代码批量生成，无桌面服务器环境稳定后台常驻运行。

3. 中小企业私有化AI部署场景
   中小企业采购少量API额度，全公司共用一套OpenClacky部署程序，依靠多级缓存大幅缩减全公司token消耗，自定义对接企业ERP系统技能，实现内部业务数据智能查询，业务数据本地留存不上传第三方云端。

4. 自媒体文案创作场景
   创作者多模型自由切换（GPT做逻辑梳理、Claude做长文撰写、DeepSeek优化润色），重复选题文案自动命中缓存，批量生成多篇文案初稿，自定义文档导出插件一键导出Word/TXT文件。

5. 离线本地大模型搭配场景
   本地Ollama部署开源大模型，OpenClacky对接本地推理端口，断网环境实现完全离线AI对话，隐私敏感内容无需上传公网API。

五、使用方法

5.1 环境前置依赖

• 系统：Windows/macOS/Linux任意主流版本；

• 源码部署：预装Python3.10及以上版本、pip包管理器；

• 预编译包：无需额外依赖，直接下载对应系统安装包。

5.2 安装方式（两种可选）

方式1：pip快速安装（推荐新手）

pip install openclacky

安装完成后终端输入openclacky -v校验版本，输出版本号即安装成功。

方式2：GitHub源码编译安装

# 拉取源码
git clone https://github.com/clacky-ai/openclacky.git
cd openclacky
# 安装依赖
pip install -r requirements.txt
# 本地编译安装
python setup.py install

5.3 基础配置步骤

1. 启动GUI：终端输入openclacky gui，自动弹出可视化配置窗口；

2. 在模型配置栏填入对应厂商API Key、接口地址、选择默认调用模型；

3. 缓存设置页面：自定义缓存磁盘上限、语义匹配阈值、缓存过期天数；

4. 技能管理：开启内置插件或导入第三方自定义技能文件；

5. 保存配置后即可新建会话开始AI对话。

5.4 CLI无桌面使用示例

# 指定DeepSeek模型单次提问
openclacky chat --model deepseek-chat --prompt "整理本月项目工作汇总"
# 指定配置文件启动批量问答
openclacky batch --config ./configs/work.conf --doc ./list.txt

六、竞品对比

选取Chatbox、Open WebUI两款主流开源AI客户端做横向参数对比，表格如下：

补充说明：OpenClacky核心优势集中在低成本缓存+CLI运维适配+轻量化插件三个方向，是两款竞品缺失的核心功能。

七、常见问题解答

Q1：OpenClacky运行提示API Key报错，无法发起对话是什么原因？

A：该故障多分为三种诱因，第一是API密钥填写错误，大小写、首尾空格会导致鉴权失败；第二是对应模型厂商账户余额不足、API调用额度耗尽；第三是服务器网络无法连通模型厂商接口，国内部分境外API需要配置代理参数，可在配置页填入代理地址后重试。

Q2：开启缓存后，重复提问没有命中缓存，依旧消耗token怎么处理？

A：先在缓存设置界面查看语义匹配阈值，阈值设置过高会大幅降低命中率，建议日常使用阈值调整至0.7~0.8区间；其次检查缓存目录读写权限，Linux系统若权限不足无法写入本地缓存文件，切换至管理员权限重启程序即可。

Q3：如何导入第三方用户分享的Skill技能插件？

A：下载后缀为.skill格式的插件文件，将文件直接放入项目根目录skills/custom文件夹，重启OpenClacky程序，软件会自动识别加载，随后在GUI技能管理面板勾选启用即可。

Q4：Linux服务器后台常驻运行OpenClacky CLI版本的方法？

A：借助systemd或者screen工具托管进程，screen方式最简，终端执行screen -S clacky，再输入启动命令，断开终端后程序持续在后台运行。

Q5：可以完全离线不联网使用OpenClacky吗？

A：可以，本地通过Ollama部署Llama、Qwen等开源大模型，在OpenClacky配置中填写Ollama本地IP（默认127.0.0.1:11434），不填写任何云端API密钥，即可实现断网全离线对话。

Q6：程序缓存文件占用磁盘过大，如何一键清理缓存？

A：GUI界面缓存设置内自带一键清空缓存按钮；CLI环境执行openclacky cache clear命令即可一键删除全部本地持久化缓存，内存缓存重启程序自动清空。

八、相关链接

1. 项目GitHub开源源码地址：https://github.com/clacky-ai/openclacky

2. OpenClacky官方产品主页：https://openclacky.com

九、总结

OpenClacky依托MIT宽松开源协议打造出一款兼顾轻量化部署、多模型统一调度与智能缓存降本的AI智能体开源框架，区别于市面偏重单一网页或桌面交互的AI客户端产品，凭借CLI+GUI双运行架构打通个人办公、服务器运维、企业私有化部署等多元落地场景，自研的多级语义缓存机制有效解决商用大模型API调用成本居高不下的行业痛点，低代码Skill插件系统进一步拓展产品业务边界，全平台适配与开源免费的属性，让开发者和普通用户均可低成本落地私有化AI工具，是兼顾实用性与二次开发潜力的优质开源AI项目。