☕ KOPI Agent 文档

新加坡咖啡 × AI — 一行命令，装好你的AI助手

简介

KOPI Agent 是基于 Hermes Agent 深度定制的 AI 代理平台，专为新加坡及东南亚用户打造。像在咖啡摊点咖啡一样简单 — 选你的口味，一行命令装好。

产品线

安装

KOPI O（经典版）

curl -fsSL https://kopiaiagent.com/install.sh | bash

KOPI Siew Dai（少糖版）

curl -fsSL https://kopiaiagent.com/install-siew-dai.sh | bash

手动提供 API Key

curl -fsSL https://kopiaiagent.com/install.sh | KOPI_API_KEY=kp-xxx bash

系统要求

• 操作系统：Ubuntu 20.04+, Debian 11+, CentOS 8+, Fedora, Arch, macOS 12+
• 架构：x86_64 / arm64（支持 Apple Silicon）
• Python：3.11+（脚本自动安装）
• 内存：1GB+ 推荐
• 磁盘：2GB+ 可用空间
• 网络：需要访问 kopiaiagent.com

macOS 安装

Mac 完整支持 — 不需要 sudo，不需要 systemd。

curl -fsSL https://kopiaiagent.com/install-siew-dai.sh -o install-siew-dai.sh
bash install-siew-dai.sh

快速开始

交互式聊天

kopi

直接在终端里和 AI 对话。支持工具调用、代码执行、文件操作等。

单次提问

kopi "帮我写一个 Python 脚本，批量重命名文件"

切换模型

/model kopi-gau       # 切换到浓厚推理版
/model kopi-o-flash   # 切换到快速版
/model kopi-o         # 切回经典版

CLI 命令

所有命令在终端运行，格式为 kopi <命令>。使用 kopi --help 查看完整选项。

🚀 核心

🔧 诊断 & 配置

🌐 网关 & 平台

🧩 技能 & 工具

🧠 会话 & 记忆

🔐 认证 & 模型

📊 其他

聊天中命令

对话中可用的斜杠命令（输入 /help 查看完整列表）：

💬 会话管理

⚙️ 配置

🧰 工具 & 技能

📋 控制 & 信息

Gateway（消息网关）

KOPI Agent 可以通过 Telegram 和 WeChat 与你交互，像聊天一样使用 AI。

Telegram 配置

1. 在 Telegram 搜索 @BotFather
2. 发送 /newbot 创建 Bot
3. 复制获得的 Token
4. 运行 kopi gateway setup 并输入 Token

systemd 服务

systemctl start kopi-gateway     # 启动
systemctl stop kopi-gateway      # 停止
systemctl status kopi-gateway    # 状态
journalctl -u kopi-gateway -f    # 日志

模型

所有模型通过 KOPI Proxy 代理，无需自备 API Key。在聊天中用 /model <名称> 切换。

技能

安装时自动预装 100+ 技能，涵盖：

🔌 什么是 MCP？

MCP = Model Context Protocol（模型上下文协议）

你可以把 MCP 理解成：AI 世界里的 USB 接口。

以前，每个 AI 要连接外部工具，都要单独开发适配。有了 MCP 之后，只要工具提供 MCP Server，AI 就可以像插 USB 一样接进去使用。

▲ MCP 连接示意图

MCP 可以让 AI 做什么？

MCP 的作用，就是让 AI 不只是"聊天"，而是可以真正连接外部系统、读取数据、执行操作：

Native MCP — KOPI Agent 内置支持

KOPI Agent 内置了 MCP 客户端能力。不需要重新开发插件系统，只要在配置文件里写好要连接哪些 MCP Server，启动后自动加载：

# ~/.kopi/config.yaml
mcp_servers:
  time:
    command: "uvx"
    args: ["mcp-server-time"]
  filesystem:
    command: "uvx"
    args: ["mcp-server-filesystem", "/path/to/folder"]

配置完成后，你问 "现在新加坡几点？"，Agent 就会自动调用 MCP 时间工具获取准确时间，而不是靠模型猜测。

工作原理

你问："现在新加坡几点？"
  ↓
KOPI Agent 识别到需要实时数据
  ↓
调用 MCP Server（时间工具）
  ↓
从时间服务器获取准确答案
  ↓
回答："现在是下午 3:45（SGT, UTC+8）"

一句话总结

📋 应用案例

案例一：客服自动化

一家零售公司通过 WhatsApp 使用 KOPI Agent 处理客户咨询。Agent 通过 MCP 连接订单数据库，当客户问"我的订单 #1234 到哪了？"时，直接查询数据库返回真实物流信息 — 无需人工介入。

案例二：开发者效率提升

一个开发团队通过 MCP 将 KOPI Agent 连接到 GitHub。开发者在 Telegram 里直接问"有哪些待处理的 PR？"或"总结最新的 Issues"，Agent 实时读取 GitHub 并给出摘要。

案例三：商业智能

一位中小企业老板通过 MCP 连接销售数据库。每天早上问 KOPI Agent"昨天销售额多少？"，立即获得报表 — 不需要登录后台或写 SQL。

案例四：文档管理

一家律师事务所通过 MCP 连接文档文件夹。律师可以问"找出所有提到 X 公司的合同"，Agent 立即搜索文件并返回相关文档和摘要。

案例五：多平台监控

一家媒体公司通过 MCP 连接 Telegram、WhatsApp 和邮件。KOPI Agent 监控所有渠道，可以自动回复、转发消息，或在紧急事项出现时通知团队。

案例六：YouTube 字幕档案馆 已上线

一位内容创作者基于 KOPI Agent + MCP 搭建了字幕档案馆。系统通过 MCP SSE Bridge 提取 YouTube 视频字幕，AI 自动生成内容摘要，并以精美的卡片式网页呈现。支持一键提取字幕、自动主题标签、可视化内容卡片 — 全部由 KOPI Agent 后台调度完成。

🔗 查看在线演示 →

案例七：量化策略排名系统 专业版

量化团队使用 KOPI Agent 自动化回测与策略排名。Agent 在 15 分钟级别上对 16 个标的、8 种策略执行 320+ 组回测，自动生成交互式排名看板（Chart.js 可视化）。评分维度涵盖总收益率、夏普比率、最大回撤、胜率等 — 全部由 KOPI Agent 自动计算并发布，无需人工介入。

🔗 查看实时排名 →

案例八：AI 知识漫画生成 创意

KOPI Agent 只需一个主题提示，即可生成完整的漫画风格知识漫画。通过 baoyu-comic 技能，自动创作剧情、AI 绘制插画、排版多格漫画 — 将新加坡鸟类保护危机等复杂话题转化为生动的视觉叙事。一条命令，一本漫画。

🔗 阅读漫画 →

案例九：智能量化交易看板 专业版

AMT Capital 使用 KOPI Agent 驱动实时量化交易看板。通过接入 Alpaca Markets API，系统追踪投资组合价值、盈亏、购买力及持仓详情 — 每 30 秒自动刷新。功能包括交易大师策略库、Vanderbilt AI 投资组合分析、交互式权益曲线图表、一键生成投资报告。KOPI Agent 在后台编排市场数据获取、风险计算与策略执行。

🔗 查看实时看板 →

开始使用 MCP

运行 kopi mcp 管理 MCP 服务器，或查看配置章节了解详细设置。

配置文件

配置文件位于 ~/.kopi/config.yaml：

# 大模型配置
model:
  default: kopi-o              # 默认模型
  provider: custom
  base_url: https://kopiaiagent.com/kp/v1
  api_key: kp-xxxxxxxx         # 安装时自动获取
  context_length: 256000

# 代理配置
agent:
  max_turns: 90

# 终端配置
terminal:
  timeout: 180

# 显示配置
display:
  skin: default
  show_cost: true

# 内存配置
memory:
  memory_enabled: true
  user_profile_enabled: true

故障排除

安装失败

API 相关

Gateway 相关

计费与财务

KOPI 内置计费引擎，追踪 token 用量、计算成本、生成发票、管理付款。所有财务数据与代理数据库分开存储。

架构

request_logs (原始 API 调用，只读)
    ↓ 每日聚合 (凌晨 4:00)
daily_usage (按 客户×模型×天 聚合)
    ↓ 月度发票生成
invoices (草稿 → 已确认，不可变)
    ↓ 付款记录
payment_ledger (银行级审计流水)

定价

财务仪表盘

管理后台地址：https://readinghero.xyz/finance/。功能：

• 实时收入、成本、利润率追踪
• 14 天日用量图表
• 按客户、按模型细分
• 发票生成与管理
• 付款记录与审计追踪
• 公司损益表 (P&L)

对账

计费引擎内置对账系统，验证 request_logs 与 daily_usage 聚合是否一致：

python3 /opt/kopi-finance/billing_engine.py reconcile 2026-05-15
# → {"status": "PASS", "discrepancies": 0}

充值系统

当客户接近或超过每日 token 限额时，系统可生成付款链接进行即时充值。付款后，客户限额自动提升。

充值套餐

流程

客户达到限额 (100% 使用率)
    ↓
系统生成付款链接
    ↓
客户付款 (Stripe / 手动)
    ↓
限额自动提升 (原限额 + 新 tokens)
    ↓
客户继续使用

API 接口

客户账单

KOPI 生成银行级客户账单，完整审计追踪。每笔财务交易都记录变动前后的余额状态。

账单内容

• 账户摘要 — 总费用、已收付款、应付余额
• 按模型用量 — 每个 AI 模型的 token 明细
• 每日明细 — 按天、按模型的用量与成本
• 发票历史 — 所有发票及付款状态
• 付款流水 — 每笔付款的 balance_before → balance_after

流水完整性

每条付款流水记录包含：

• entry_type — charge（计费）、payment（收款）、refund（退款）、credit（信用）、adjustment（调整）
• balance_before — 本条记录前的账户余额
• balance_after — 本条记录后的账户余额
• source — stripe、manual、system
• reference — Stripe 付款 ID 或手动参考号

计费（charge）不影响账户余额 — 只有实际收付款/退款才会变动余额。

发票生命周期

草稿 (draft) → 已确认 (finalized) → 已发送 (sent) → 已付 (paid)
                                  ↘ 作废 (void)

发票一旦确认（finalized），不可编辑。调整通过新增流水记录实现。

API 接口

账单 UI 预览

三种账单界面风格供选择：

• 📄 经典发票 — 传统纸质发票风格，可打印
• 📊 现代仪表盘 — 图表、卡片、数据丰富
• 📱 极简移动端 — 卡片式布局，手机优先