快速上手
从 Koishi 插件市场安装到第一次对话
完成这篇教程后，你会得到一份正在运行的默认 profile：它带着预设模型、人格、引擎与频道认领规则，可以在 Koishi 中接收消息、调用工具并回复。
开始前
请准备：
- 一个 Koishi 4.18.11 或更高的 4.x 应用，控制台可以正常打开。
- 正式接入时需要一个已经连接真实账号的聊天平台适配器。下面以 OneBot 适配器为例；只验证插件、profile 与回复链路时，可以使用 Koishi 自带沙箱频道。
- 一个模型接口及其 API Key。默认
native工具调用引擎需要模型支持原生工具调用。
Ishiki 已经发布在 Koishi 插件市场。安装过程不需要下载源码、安装 Bun 或手动编译。
安装并启用插件
从插件市场安装
在 Koishi 控制台左侧打开「插件市场」，搜索 ishiki，选择 koishi-plugin-ishiki，依次点击「添加」和「安装」。
插件市场负责下载并安装发布包，控制台页面已经包含在发布包中。
确认预设已经释放
首次使用空数据目录启动时，插件会自动释放一套预设，并把日志写到控制台：
Default preset created under .../data/ishiki.预设包含：
models.yaml：DeepSeek 兼容接口与deepseek:deepseek-flash模型声明。profiles/default/profile.yaml：channel模式、三组引擎、codemode 与频道认领规则。profiles/default/PERSONA.md：可以直接开始对话的中文人格。
默认数据目录是 Koishi 应用下的 data/ishiki，可以在插件配置的 dataPath 中修改。预设只在目录不存在或为空时释放，已有文件不会被覆盖。
获取 Bot 的账号与频道标识
profile 使用 <platform>:<selfId> 识别 Bot 账号。platform 来自平台适配器，selfId 是平台上的 Bot 账号；两者合起来才是完整的 sid。
OneBot 适配器的 platform 是 onebot。QQ 号码可以作为 OneBot 的 selfId，不能单独作为 sid。
取得这些值不一定要发送 inspect。inspect 是推荐方法，已经知道适配器配置或能从控制台日志核对时，也可以使用那些来源。
启用 inspect 插件（推荐）
Koishi 已经预置 inspect 插件，但需要手动启用。打开「插件配置」，找到 inspect，点击「启用插件」，然后启动或重载 Koishi。
发送 inspect
使用一个真实聊天账号，在 Bot 所在的群聊或私聊中向 Bot 发送：
inspect也可以先在 Koishi 自带的沙箱频道发送同样的指令，确认插件已经正常加载。沙箱返回的是沙箱适配器的数据，配置真实平台时不能混用。
记录三个值
inspect 会返回平台名、消息 ID、频道 ID、群组 ID、用户 ID 与 Bot 自身 ID。无论使用 inspect、适配器配置还是日志，部署都需要确认以下值：
| 值 | 用途 |
|---|---|
platform | 平台适配器名称；OneBot 填写 onebot |
selfId | Bot 在该平台上的账号 |
channelId | 当前群聊或私聊的频道标识 |
由前两个值组成 sid。例如平台为 onebot、Bot 账号为 123456789 时：
onebot:123456789如果只希望响应当前群聊，把该群聊返回的 channelId 原样填入频道名单；如果希望响应这个 Bot 账号下的全部频道，填写 *。
已经知道适配器实际使用的平台名与 Bot 账号时，可以直接填写这些值，再用一条真实消息核对结果。缺少 channelId 或无法确认账号时，优先启用 inspect。
填写模型 API Key
打开 Koishi 控制台左侧的 Ishiki，进入「模型目录」。页面标题为「模型配置」，可以可视化编辑供应商、模型与模型组。
- 找到预设供应商
deepseek。 - 打开供应商编辑器，把
YOUR_API_KEY替换成实际 API Key。 - 保存模型配置。
- 如果运行中的实例仍报鉴权错误，在「人格配置」中点击「重新加载」，或者重载插件。
模型声明的引用是 <供应商>:<模型>。预设 profile 已经引用 deepseek:deepseek-flash，替换 API Key 后可以直接使用。
凭据保存位置
API Key 以明文保存在 <dataPath>/models.yaml。请限制数据目录的访问权限，不要把它提交到版本库，也不要发到公开 issue 中。
配置频道并应用 profile
进入 Ishiki 的「人格配置」，打开预设 default。点击「编辑」后，在频道认领区域完成两项修改：
- 把账号
onebot:BOT_ID替换成上一步得到的真实sid。 - 把频道名单设为
*，或者换成当前群聊的channelId。
保存后，配置只会写入磁盘。点击「应用」后，新的 profile 配置才会启动并接管频道。
平台名称必须匹配
OneBot 适配器使用 onebot，不要写成 qq。其他平台请使用适配器实际配置的 platform，或者使用 inspect 返回的原值。
频道匹配规则、channel 与 cross 两种运行模式的差别，见编写 profile。第一次上手保留预设的 channel 模式即可，每个群聊会拥有独立的会话与资源。
在频道中发送第一条消息
回到已经认领的群聊，@ Bot 或引用 Bot 的消息，然后发送一条简单消息。预设唤醒引擎会处理这次输入。
查看 Koishi 控制台日志，正常启动时应该出现：
profile "default" activated: mode=channel, accounts=1第一次收到该频道的消息时，还会出现：
[default] runtime created: default/onebot:123456789/CHANNEL_ID第一条消息会创建 runtime，模型调用成功后通过 send_message 发回平台。之后可以继续在「人格配置」中调整模型、引擎与频道，也可以直接编辑 PERSONA.md 定制人格。
先用沙箱验证
Koishi 自带沙箱频道。让 profile 认领沙箱会话的 platform:selfId 与 channelId 后，可以在沙箱中检查插件加载、profile 激活与模型回复。正式接入时仍需在真实适配器会话中发送一条消息。
网页控制台已经可用
安装发布包后即可使用控制台，不需要执行 console:build。只有修改 client/ 源码的开发者才需要重新构建控制台资源。
遇到问题
按现象查找常见问题与排查，其中覆盖插件安装、启动失败、收不到消息、收到消息没有回复、不同群聊表现不一致与图片问题。
需要更详细的运行期日志时，开启 logLevel: 3；需要查看模型请求时，开启 dumpRequests。完整用法见调试与排障。
如果按文档检查后仍未解决，可以在 GitHub Issues 附上 Koishi 版本、插件版本、报错日志与已经执行的检查。QQ交流群：857518324。