接入 Alma

Alma 适合偏好图形界面的用户：你可以在窗口里切换模型、拖入文件、管理多轮上下文，再把请求统一走到 小蓝中转站 网关。

如果你更习惯终端工作流，优先看 Claude Code。如果你想先用桌面界面把地址、Key 和模型跑通，再逐步过渡到 CLI，Alma 会更顺手。

下载与安装

官方入口：

• 官网：https://alma.now/
• 下载页：https://alma.now/download
• 官方文档：https://alma.now/docs/getting-started/getting-started.html
• GitHub 仓库：https://github.com/yetone/alma

优先使用官网和下载页。官方文档目前对 macOS 的说明更完整，Apple Silicon 设备的支持也更成熟；如果你使用的是其他平台，先看下载页和仓库发布说明，确认当前版本是否已经提供对应安装包。

下载页当前列出的常见安装包类型是：

• macOS：Apple Silicon .dmg、Intel .dmg
• Windows：x64 .exe
• Linux：x64 .AppImage、x64 .deb

如果你只是想先把桌面链路跑通，优先直接下官网安装包，不用为了这一页再折腾 Homebrew、源码或 GitHub Actions 产物。

接入前先准备

先准备三样东西：

1. 一把给桌面客户端单独使用的 Key，建议命名为 Desktop-Alma
2. 一个准备先测试的轻量模型名
3. Base URL 使用 OpenAI 兼容地址 https://xiaolan.ainb.plus/v1

这里要带 /v1，因为 Alma 的自定义 Provider 走的是 OpenAI 兼容接口。如果只填根域名，客户端能保存配置，但真正发请求时通常会命中网页入口而不是模型接口。

模型名不要手打，直接去模型广场复制。这样可以避免版本后缀、日期后缀或大小写不一致导致的 model not found。

配置步骤

1. 添加自定义 Provider

按 Alma 官方文档里的入口，打开 Settings / Providers / Add Provider。
如果当前版本的菜单里区分了内置 Provider 和 Custom APIs，这里优先选择 Custom APIs。

建议填写：

Provider Name: 小蓝中转站
Base URL: https://xiaolan.ainb.plus/v1
API Key: sk-你在控制台创建的 Desktop-Alma 专属 Key

Provider Name 只是本地显示名称，你可以改成 小蓝中转站、小蓝中转站-Alma 或团队内部更容易识别的名字。

之所以建议直接走自定义接口，而不是先套别的平台名称，是因为 Alma 之后显示的连接、模型列表和会话记录都会沿用这条 Provider 名称。
第一次就把名字写清楚，后面切模型和排查日志时会省很多事。

2. 导入模型

保存 Provider 后，先看 Alma 当前版本是否提供“获取模型”“刷新模型列表”之类的按钮：

• 有自动拉取：优先直接拉取，列表会和这把 Key 的权限范围保持一致
• 没有自动拉取：回到模型广场，复制模型名后手动添加

第一次建议先添加一个轻量模型。轻量模型更快，也更适合拿来确认地址、鉴权和网络链路是不是都正常。

如果 Alma 当前版本已经支持在会话里直接切模型，也建议先把“主力模型”和“轻量模型”都加进去。
这样同一个线程里你就能很快感受到：轻量模型适合先验证链路，主力模型更适合正式写代码、改文档或长对话。

3. 新建会话测试

新建一个会话，选中刚才配置的 Provider 和模型，先发送一句：

你好，请用一句话确认你已经连接成功。

能正常返回，说明地址、Key 和模型名已经打通。确认这一步成功后，再开始拖目录、贴代码或切换更强模型。

发送成功后，再顺手看一下输入框附近或线程设置里的模型下拉框。
如果你刚才添加的模型已经能在这里被选中，说明 Alma 不只是“保存了 Provider”，而是真的把这条模型链路接进来了。

如果你准备长期用 Alma，第一次接通后就把“轻量模型”和“主力模型”都试一遍更稳。
这样你很快就能知道：哪一个适合快速问答，哪一个更适合长文、长代码或复杂分析，后面切模型时也不会只凭感觉。

4. 再把代码上下文加进来

Alma 这类桌面客户端很容易一次拖入太多内容。第一次接入时，不要直接把整个大型仓库都丢进去，先按问题范围放少量文件：

• 先放 README、入口文件、报错相关文件
• 需要做 Code Review 时，再逐步追加相关目录
• 复杂仓库先让模型读目录结构，再继续追问

这样做的好处是更快、更稳，也更容易判断问题到底出在客户端配置还是上下文本身太大。

5. 顺手把线程设置和显示项调顺

Alma 官方文档把很多常用项放在线程设置和应用设置里。第一次跑通后，建议顺手检查两类内容：

• 线程设置：当前线程实际使用的模型、温度、上下文相关选项
• 显示设置：是否显示 Token 使用量、成本信息或你常用的会话侧栏

这一步的意义不只是“好看”，而是为了让你之后排障时看得见自己到底切到了哪一个模型、这一轮大概消耗了多少。
如果界面里完全不显示模型和消耗，很多人会误以为“切模型没生效”，其实只是界面没有把关键状态露出来。

网络与代理

大多数情况下，Alma 直连 https://xiaolan.ainb.plus/v1 就够了，不需要额外再套一层代理。
只有在你的电脑本身已经挂了代理软件、公司网络有出站限制，或者你本来就通过代理访问外网时，才需要继续看这里。

Alma 官方设置页当前把网络相关项单独放在 Network 或相近菜单里，常见会看到：

• 代理配置
• 连接超时
• 重试次数
• Proxy 测试

如果你电脑本来就在用 Clash、Surge 或其他本地代理，再决定要不要把代理也交给 Alma 之前，先想清楚一件事：
你要解决的是“Alma 本身连不出去”，还是“系统网络已经可以访问，只有这一个应用没走到正确出口”。

排查时可以按这个顺序来：

1. 先不填 Alma 代理，直接测试 https://xiaolan.ainb.plus/v1
2. 如果系统网络能通、Alma 不通，再回到 Network 设置检查代理项
3. 如果启用了本地代理，确认地址、端口和协议没有填错
4. 改完后先用 Alma 自带的代理测试，再发一条最短消息

这样做的好处是，你能把“客户端代理问题”和“网关地址问题”分开，不会一出错就误以为是 小蓝中转站 配错了。

使用建议

图形界面和终端怎么选

• 想拖文件、看多轮聊天、手动切模型：用 Alma
• 想在项目目录里直接读写文件、看 diff、跑命令：用 Claude Code

很多用户会把 Alma 当成“先跑通配置的第一站”，等 Key、模型和网关都验证成功后，再继续接入 Claude Code、Codex 或 OpenCode。

Key 分开更好管理

建议给 Alma 单独建一把 Key。这样你在控制台日志里能一眼看出桌面聊天和 CLI 编程分别消耗了多少，也方便单独停用某个设备的配置。

先用轻量模型确认，再换主力模型

图形客户端最容易出现的一种误判是：第一次就选了很重的模型，结果等待时间长，于是以为地址没通。

更稳的节奏通常是：

1. 先用轻量模型发一条最短消息
2. 确认 Provider、模型、返回内容都正常
3. 再切到主力模型处理长代码、长文档和复杂问题

这样做并不是为了省这一条费用，而是为了先证明链路是通的。

更新失败时，先回下载页看安装包

Alma 官方文档当前提到，并不是所有平台都一定能稳定走内置更新。
如果你已经发现版本异常、更新按钮没反应，或者更新后启动异常，优先回官方下载页重新下载安装包，通常比反复重试自动更新更直接。

常见问题

保存成功，但发消息时报连接错误

优先检查两项：

• Base URL 是不是写成了 https://xiaolan.ainb.plus/v1
• API Key 前后有没有多出空格

如果地址漏了 /v1，这是最常见的问题之一。

模型列表为空，或者选了模型后提示不存在

先到模型广场重新复制模型名，再回到 Alma 覆盖原值。

如果还是不行，再去控制台确认：

• 这把 Key 是否被禁用
• Key 所在分组是否允许当前模型
• 余额是否正常

有些桌面客户端会把“接口可达”和“模型可用”显示成同一类报错，所以这里不要只盯着网络。
地址、Key、分组、模型名四层里，只要有一层不匹配，表面上都可能看起来像“连接失败”。

发得出去，但明显没有走到你想要的模型

这类问题通常要回到线程层去看，而不是继续重建 Provider。

优先确认：

• 当前线程模型下拉框里，选中的到底是不是你刚添加的那一项
• 你是不是只保存了 Provider，但没有把模型切过去
• 这个线程是不是沿用了之前旧会话的模型设置

图形客户端和 CLI 最大的区别之一，就是“保存 Provider 成功”不等于“当前线程已经切到那个模型”。

拖入项目后明显变慢

这通常不是网关地址问题，而是上下文太大。把整仓拖进去后，模型需要先消化大量无关文件，响应自然会变慢。

优先保留和当前问题直接相关的文件，效果通常会明显好很多。