Koishi AI 插件:ChatLuna 三分钟接通大模型

结论先行:三步让 Koishi 接上 AI

老教程里搜 koishi chatgpt 出来的 davinci-003 插件已经跟不上现在的模型生态,当前 Koishi 社区接大模型的事实标准是 ChatLuna。它走 OpenAI 兼容接口,一个 kkaiapi 的 Key 就能调 DeepSeek、GLM、Kimi、Claude 全系模型,换模型只需要在下拉框重新选一个,其余配置一处不用动。 可用模型 ID:deepseek-v4-flash、deepseek-v4-pro、glm-5、kimi-k2.6、claude-sonnet-4-6、claude-opus-4-7、gpt-5.5、grok-4.5。

• 第一步:打开 Koishi 控制台的插件市场,搜索 chatluna,安装 chatluna 主插件和 chatluna-openai-like-adapter 适配器。
• 第二步:在适配器配置页填两个值,API Key 填 kkaiapi 的 sk- 密钥,请求地址填 https://api.kkaiapi.com/v1,保存并启用。
• 第三步:回到 chatluna 主插件,默认模型下拉选 deepseek-v4-flash,启用后在群里 @机器人 即可对话。

插件市场选型:为什么是 ChatLuna

插件市场搜 AI 相关关键词能出来一堆结果,真正值得装的很少。选型结论:直接装 ChatLuna,不用纠结。它把接口适配和对话逻辑拆开,以后换供应商只动适配器配置;房间机制让每个群、每个用户可以挂不同的模型和人设,这是其它 AI 插件都没有的能力。

API 配置:适配器填两个值就通

下面是 koishi.yml 的等价写法,不习惯改文件就直接在控制台界面上填,效果一样,字段名以你安装的 ChatLuna 版本界面为准。填完重载配置,在 chatluna 主插件的模型下拉框里能看到拉取的模型列表就说明通了。 模型怎么选:群聊闲聊高频场景选 deepseek-v4-flash,响应快成本低,人设服从性是社区公认的好;要更强的角色一致性上 deepseek-v4-pro 或 glm-5;群友爱发长文或希望机器人记住整段对话,kimi-k2.6 的长上下文最稳。Claude 系文笔最好,适合写作辅助等普通创作场景,注意 Anthropic 内容政策较严,不适合边界题材。grok-4.5 是 xAI 的旗舰通用模型,公开政策对成人向虚构文本相对宽松,是否启用请自行阅读其条款。

plugins:
  chatluna-openai-like-adapter:
    apiKeys:
      - - sk-你的kkaiapi密钥
        - https://api.kkaiapi.com/v1
  chatluna:
    defaultModel: deepseek-v4-flash

多平台适配:QQ、Discord、Telegram 一套逻辑

Koishi 的核心价值就在这:AI 逻辑写一次,平台无关。ChatLuna 不关心消息来自哪个适配器,同一套人设和记忆在 QQ 群、Discord 频道、Telegram 群里表现一致。三个适配器可以同时启用,一个 Koishi 实例带三个平台的机器人。 QQ 有两条路。adapter-qq 走官方开放平台,合规稳定但要申请资质,主动发言等能力受平台规则限制;adapter-onebot 配合 NapCat、Lagrange 这类协议端跑个人号,功能全,但属于协议模拟,账号本身存在风控风险,建议用小号并控制发言频率,这个风险来自协议端而不是 AI 插件。

plugins:
  adapter-onebot:
    protocol: ws
    selfId: '机器人QQ号'
    endpoint: ws://127.0.0.1:3001
  adapter-discord:
    token: 你的DiscordBotToken
  adapter-telegram:
    token: 你的TelegramBotToken

人设与记忆:preset 预设加长期记忆

ChatLuna 的人设用 preset 预设文件管理,放在 data/chatluna/presets 目录,yaml 格式,写好后在配置里设为默认预设,或按房间单独指定。写人设的要点:用第二人称写清角色身份、说话风格和行为边界,附两三句示例台词,比堆形容词有效得多。角色扮演类人设把功夫花在角色一致性和文风上,内容保持在平台与模型的政策范围内。 记忆分两层。短期记忆就是对话上下文,ChatLuna 按房间维护,聊太长可以清空房间重开;长期记忆需要另装 ChatLuna 的记忆增强插件,配向量库和 embedding 模型,机器人才能跨会话记住群友的名字和喜好。

keywords:
  - 小可
prompts:
  - role: system
    content: |
      你是小可,一个毒舌但心软的猫娘助手。
      说话简短,偶尔用"喵"收尾,拒绝无聊请求时先吐槽再帮忙。
      不讨论政治,不进行人身攻击,遇到不合适的请求就转移话题。

常见问题