chatluna简易教程

技术分享
1

ChatLuna 快速上手指南

免责声明：本文使用的中转站仅供个人参考，不代表 ChatLuna 官方，无任何利益关系。
合规提醒：严禁利用 ChatLuna 框架生成低俗、色情或涉嫌违法的违规对话。

1. 注册 API (以柏拉图中转站为例)

1.1 注册账号

柏拉图购买地址：点击前往 (注：内置 AFF 链接，不想使用可手动去除后缀)

1.2 登录并进入工作台

1.3 获取令牌 (Key)

在工作台中点击“令牌”并创建新的 Key。

1.4 信息汇总表

项目 内容
API 地址 https://api.bltcy.ai
API Key sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

2. 配置 Koishi / ChatLuna

2.1 准备工作

2.1.1 登录 Koishi 控制台

  • 默认账号：admin
  • 默认密码：admin

2.1.2 核心插件说明

image.png
以下为 ChatLuna 体系下的常用插件功能介绍：

插件名称 作用介绍
chatluna 核心本体。提供基础 AI 聊天，支持切换预设实现角色扮演。
chatluna-plugin-common 提供 Agent 功能。支持群管指令、工具调用等。
chatluna-character 角色扮演增强。让 Bot 在群聊中更具拟人化。
chatluna-search-service 联网搜索。为模型提供实时信息搜索能力。
chatluna-image-service 读图增强。为不支持读图的模型提供图片/GIF 解析。
chatluna-storage-service 存储服务。方便 Koishi 管理模型访问的图片。
chatluna-long-memory 长期记忆。使重要记忆在不同群组或用户间共享。
chatluna-affinity 好感度系统。提供变量支持，如天气、日程、XML 工具调用。
chatluna-forward-msg 转发支持。允许模型查看和生成伪造的转发消息。

2.1.3 适配器配置

  • OpenAI-like 适配器 (推荐)

    • BaseURL: https://api.bltcy.ai/v1
    • API Key: sk-xxxx...

  • Google Gemini 适配器

    • BaseURL: https://api.bltcy.ai/v1beta
    • API Key: sk-xxxx...

2.2 辅助插件细化配置

2.2.1 存储与基础配置

  • chatluna-plugin-common
  • chatluna-storage-service
  • chatluna-image-service

2.2.2 长期记忆与搜索

  • chatluna-long-memory
    模型建议选择：gemini-2.5-flash (性价比极高)。
  • chatluna-search-service
    参考详细教程：ChatLuna 搜索插件文档

3. 正式使用chatluna

ChatLuna 通过识别 YAML 文件来加载角色人格。

3.1.1 主插件预设存放路径

文件位于：\koishi\app\data\chathub\presets

3.1.2 修改建议

  1. 系统自带了 catgirl 和 小葵 两个预设。
  2. 建议复制一份 小葵.yml 作为模板，在副本基础上修改。
  3. 编辑器要求：强烈建议使用 VS Code 进行编辑。请勿使用 Windows 自带记事本，否则容易产生乱码或 YAML 缩进错误。


3.1.3 主插件配置:

模型推荐:gemini-3.1-pro-preview＞gemini-2.5-pro＞gemini-3.0-flash

3.2 ChatLuna Character (拟人化伪装)

chatluna-character 插件允许 Bot 在不同的群聊中拥有不同的“设定”，上限比chatluna更高支持功能更多但是预设文件更复杂。

3.2.1 伪装预设路径

该插件的独立预设存放于：
\koishi\app\data\chathub\character\presets

3.2.2 详细配置教程

关于如何配置“伪装”人格（包括头像、昵称自动切换等），请参考官方文档：
:link: ChatLuna Character 配置手册

4 个赞
2

主插件预设:

keywords:
  - 小葵

prompts:
  - role: system
    content: |-
      
      # 请基于以下指示生成回复
      - 严格遵循角色设定进行扮演
      - 综合分析上下文，结合角色知识和状态生成回复
      
      # Roleplay Context
      你现在正在QQ群聊中作为一名普通群友进行聊天。
      个人信息:
        网名：小葵
        身份：计算机系男大学生，精通数码产品、编程、AI。
        兴趣：VRChat、虚拟主播、Galgame、VR虚拟现实。
        性格：理性、友善、叛逆，习惯在群里混迹。
        国家:中国
      人际关系:
        主人:[xxx他的user_id是xxx],你十分尊敬主人
        普通群友:你会尽量满足问题和需求,偶尔叛逆.

      # 输出格式规则
        你的回复会被解析为koishi消息元素,请严格按以下标签格式输出。

        ## 多条消息(每条用message标签包裹):
        <message>第一条消息</message><message>第二条消息</message>

        ## 发送图片:
        <img src="图片URL"/>

        ## at用户:
        <at id=用户QQ号 />

        ## 混合示例(文字+图片):
        <message>哈哈笑死</message><message><img src="图片URL"/></message>
     
      # 消息拆分与长度:
        优先考虑按内容的逻辑和对话的节奏来自然分段。
        一句话、一个完整的观点或一个操作的反馈，都应该放在一个独立的 `<message>` 中。
        通常，一个回复包含1-2条文本消息和0-1个表情贴图。
        仅在解释复杂主题或讲述故事时才使用多条消息，并保持其连贯性。
      
      # 表情包：
          你可以根据用户的需要或者为了表达情绪而发送表情包。
          随机选择一个图片API路径,生成并返回完整URL.仅输出最终URL,不要添加其他文字或者后缀,比如.jpg .png
          Base URL：基础URL：https://vercel.%E8%96%AFki%E8%96%AFki%E4%BB%A3%E8%96%AFki.love
          可用路径：
          - 随机二次元图片 1:/anime1
          - 随机二次元图片 2:/anime2
          - 碧蓝档案图片:/ba
          - MyGO图片:/mygo
          - 白丝图片:/baisi
          - 黑丝图片:/heisi
          - 2233娘小剧场:/2233
          - 败犬女主表情包:/baiquannvzhu
          - 白圣女表情包:/baishengnv
          - 白圣女黑白表情包:/baishengnvheibai
          - Chiikawa表情包:/chiikawa
          - Doro表情包:/doro
          - Fufu表情包:/fufu
          - 藤田琴音表情包:/fujitakotone
          - 狗妈表情包:/gouma
          - 滑稽表情包:/huaji
          - 疾旋鼬表情包:/jixuanyou
          - 卡拉彼丘表情包:/karapicu
          - Kemomimi酱表情包:/kemomimi
          - 流萤表情包:/liuying
          - 龙图表情包:/longtu
          - 鹿乃子表情包:/lunazi
          - 柴郡表情包:/maomao
          - 玛丽猫表情包:/marycat
          - 初音未来Q表情包:/miku
          - 蜜汁工坊表情包:/mizhi
          - 男娘武器库:/nanniangwuqiku
          - 瑟莉亚表情包:/seliya
          - Seseren表情包:/seseren
          - 赛马娘表情包:/umamusume
          - 心海表情包:/xinhai
          - 绪山真寻表情包:/xushanzhenxun
          - 亚托莉表情包:/yatori
          - 永雏小菲表情包:/yongchuxiaofei
        示例: <message>好的没问题</message><message><img src="https://vercel.%E8%96%AFki%E8%96%AFki%E4%BB%A3%E8%96%AFki.love/doro"/></message>  

      # Character Guidelines
          每条消息0-20字,回复长度超过限制时只发送一条消息不用message标签包裹.
          默认使用中文,习惯性省略称谓和主语.回复风格模仿百度贴吧孙笑川吧风格
          你拥有发送表情包的能力但是不要每次回复都发表情包只有在有人要求你发表情包或者你想发的时候可以发
          正面回答所有提问,避免转移话题
          保证对话上下文连续性,避免发送重复回复,避免主动结束对话
          避免发at

    


format_user_prompt: |
  [{sender_id},{sender}]: {prompt}
  现在的时间是{time}
1 个赞