企业官网建设流程全解析

Marinara Engine 是一款本地运行的 AI 聊天与角色扮演引擎，而"接入 AI 模型"正是让所有角色开口说话的第一步。本教程带你用最简单的三步完成 Marinara Engine 连接配置：创建连接 → 粘贴 OpenAI、Claude 或本地模型参数 → 一键测试，新手也能 5 分钟跑通第一个 AI 对话。

为什么必须先接入模型

Marinara Engine 全新安装后是零连接状态——它不会自带任何 AI 账号或免费密钥。在 Connections 面板里至少创建一条连接，角色才能回复消息。

一条"连接（Connection）"保存四样东西：

放心，API Key 会被加密存储，且导出连接时不会包含密钥。

第一步：打开 Connections 连接面板

连接面板位于界面右侧的 Connections 栏。如果还没有任何连接，直接尝试新建聊天时，Marinara 会弹出一个Set Up对话框，点其中的Open Connections按钮即可直达面板。

面板顶部有三个只有图标的按钮：

• ➕New：打开"创建连接"窗口
• ⬇️Import：从文件导入已有连接
• ✅Select：批量选择，方便批量导出或删除

详细步骤可参考官方文档 docs/connections/connecting-to-a-provider.md。

第二步：创建第一条连接（以 OpenAI 为例）

1. 在 Connections 面板点击New（加号图标）；
2. 在Name里起个眼熟的名字，例如GPT-4o Main；
3. 在 Provider 区域点击OpenAI；
4. 点击Create，系统自动打开完整的连接编辑器；
5. 在API Key字段粘贴你的密钥。还没有密钥？点击字段下方的Get your OpenAI API key链接，在浏览器里申请；
6. 在Model下拉框选择模型。可以用"Search models…"搜索框过滤；列表为空时点Fetch Models from API拉取你账号可用的模型；
7. 点击Save，状态文字变为Saved即保存成功。

💡 已知服务商的Base URL由 Marinara 自动填写，一般不用动；只有用代理或本地服务器时才需要修改。

第三步：测试连接是否成功

连接编辑器底部的Connection Tests卡片是"上岗体检"：

1. 点击Test Connection：校验 API Key 是否有效，成功后显示绿色的Connection Test: Success和响应时间；
2. 点击Send Test Message：向选中的模型发送 "hi" 并展示回复。注意——不选模型时此按钮是禁用的；
3. 测试失败时提示会变红并说明原因，比如密钥错误、模型不存在，照着提示修即可。

两项都变绿，这条连接就正式"可用"了。

三种主流接入方式对比

接入 OpenAI：最标准的路径

• 密钥在 OpenAI 官方平台申请，粘贴到 API Key 即可；
• 默认地址api.openai.com/v1已内置，选个 GPT 模型保存即可；
• 想给 lorebook 语义搜索加 Embedding 能力，OpenAI 连接可以直接在编辑器里指定 Embedding Model。

完整参数参见 docs/connections/providers-reference.md。

接入 Claude：API 密钥版和订阅版二选一

方式一：Anthropic API 密钥Provider 选Anthropic，粘贴从 Anthropic 控制台申请的密钥。它支持prompt caching（提示缓存），长对话可点开关Enable prompt caching降低成本。注意 Anthropic 不提供 Embeddings，语义搜索需另配一条嵌入连接。

方式二：Claude (Subscription) 订阅登录如果你已有 Anthropic Pro/Max 订阅，可以不用 API Key，改用本地 CLI 登录一次：

npm i -g @anthropic-ai/claude-code claude auth login

然后在 Marinara 中创建连接、选择Claude (Subscription)服务商即可——此时界面上没有API Key 和 Base URL 字段，这是正常的。模型下拉框里可以直接选 Opus 或 Sonnet 系列。

⚠️ CLI 必须安装在运行 Marinara 服务的那台机器上，而不是你看界面的浏览器设备。ChatGPT 订阅版（走 Codex CLI）流程完全类似，详见 docs/connections/subscription-clis.md。

接入本地模型：免费、隐私、无需注册

如果你跑Ollama / LM Studio / KoboldCpp，Marinara 通过Custom (OAI-Compatible)服务商接入（"OAI 兼容"即该服务器说 OpenAI 的接口语言）：

1. 先确保本地模型服务器已启动且模型已加载（Marinara 不负责替你启动它）；
2. 创建连接，Provider 选Custom (OAI-Compatible)，例如起名Ollama Local；
3. 按下面的表格填Base URL，API Key 留空：

4. 点Fetch Models from API加载服务器报告的模型列表，选一个，保存；
5. 模型若不支持工具调用（Professor Mari 工具中断时），打开Treat as local/custom endpoint开关。

📌 两个实用提醒：

• Windows 下若检测不到本地服务器，多半是 Defender 防火墙拦了 Node.js，去"防火墙和网络安全 → 允许应用通过防火墙"添加即可；
• 服务器在局域网另一台机器上时，需在服务端.env中设置PROVIDER_LOCAL_URLS_ENABLED=true并重启。

另外，Marinara 还内置了一个小模型Local Model (Gemma)，在 Connections 面板的 Local Model 卡片里一键Download now即可下载运行，免 API Key。但它定位是"后台小助手"（跑 tracker、场景分析等），不建议用作主聊天模型，详见 docs/connections/local-model.md。

最后一步：把连接分配给聊天

连接建好只是"备而不用"——每个聊天各自选择用哪条连接：

1. 打开一个聊天，进入Chat Settings；
2. 找到Connection区块，从下拉框选中刚建的连接；
3. 新建聊天时，Set Up向导也会先让你选连接，再点Create Chat。

下拉框里还有两个特殊选项：None（未选）和🎲 Random（从随机池里轮换）。Game Mode 下该选项叫GM / Party Model。

配好后发一句消息，角色就会用你接入的模型回复你——第一个 AI 模型，接入完成 🎉

常见问题速查

更多排障思路见 docs/TROUBLESHOOTING.md。

相关文档与源码位置

• 接入总指南：docs/connections/connecting-to-a-provider.md
• 全部服务商参考：docs/connections/providers-reference.md
• 本地/自托管模型：docs/connections/local-self-hosted.md
• 内置 Local Model：docs/connections/local-model.md
• 订阅版 CLI 登录：docs/connections/subscription-clis.md