作者注：本文按 Alma 的官方文档和实机截图整理。Alma 不是只给程序员用的终端皮肤，它想做的事，是把 AI Agent 装进每个人的电脑：一个窗口接所有模型、记住你的偏好、替你操作电脑，也能把 herdr 里的 Claude Code、Codex 变成聊天窗口。我使用下来，他很有人的主观能动性，同一个模型能变聪明很多
先说结论：Alma 是一个本地优先的 AI Agent 应用，同时是 herdr 的图形客户端。官方把它定义成「把 Agent 能力交到每个人手里」：模型、记忆、技能、插件、频道、电脑操作都收在一个 App 里；对开发者最实用的一块，是把多个 coding agent 从终端搬进可读可回的聊天窗。
如果你每天同时开 2 到 4 个 agent，分不清谁在等权限、谁已跑完，或者离开电脑审批就卡住，这套组合值得试。它不适合只开一个 agent、也不需要电脑操作和手机端的人；iPhone 版目前还是 TestFlight 公测。本文事实以 Alma 和 herdr 官方文档为主，另有多张实机截图和一条 X 用户反馈，文中会分别标注。
图 1：Alma 桌面端与 iPhone 配合使用的示意图，根据官网首屏绘制，非官方截图。
多个 AI Agent 挤在终端里：乱的不是模型
假设你开了三个终端窗口：Claude Code 在重构，Codex 在补测试，另一个 Codex 在查 bug。模型都在正常工作，真正耗时的是你要轮流切窗口，再翻 scrollback（终端回滚记录），才能判断哪个会话停在权限确认上。agent 越多，这种巡检成本越高。
离开电脑时问题更明显。agent 可能只差一次命令审批，却在原地等了半小时，而你在手机上看不到它的进度。所以多 agent 的瓶颈往往不在模型能力，而在状态可见性和回复路径。
下面这张表对比两种工作方式，其中右列是 Alma 和 herdr 配合后的官方功能描述：
| 日常动作 | 纯终端 | Alma + herdr |
|---|---|---|
| 找出谁在等你 | 逐个切窗口查看 | 侧栏按状态分组，等待中的 agent 优先显示 |
| 读运行过程 | 翻 scrollback | 步骤折叠、代码格式化，子 Agent 可单独打开 |
| 回复 agent | 回到对应窗口输入 | 用输入框或按钮回复，也可排队下一条消息 |
| 离开电脑后审批 | 回到电脑才能处理 | 手机收推送，点按钮或输入回复 |
| 查看原始输出 | 一直可见 | 随时切回真实终端 |
需要说明的是，herdr 自己的侧栏和标签也能显示 agent 状态。也就是说，「知道谁需要你」这部分价值，只装 herdr 就能得到一部分。Alma 额外提供的是对话式阅读、按钮回复、手机端和模型接入。
用 Alma 改造「看和答」这一层，herdr 继续跑 Agent
理解这套组合，只要分清三层。herdr 负责组织和运行 agent；herdr-core 是跑在本机的小型服务，agent 实际由它托管；Alma 负责连接这个服务，把每个 pane（面板，也就是 agent 所在的终端区域）变成聊天界面。Alma 本身不运行这些 agent。
这样分层带来两个直接结果。第一，你不用改变现有习惯，照常在 herdr 里启动 agent 就行，Alma 会自己找到本机服务。第二，退出 Alma 或 herdr 应用后，agent 仍在 herdr-core 里继续跑。但机器重启或 herdr-core 停止时，程序也会停止；pane 会以同一目录下的 shell 恢复，herdr 不会重启 agent，也不会恢复进行中的工作。
图 2：herdr 与 Alma 的分工示意图，非官方架构图。
还要分清两条模型线。Alma 的聊天窗口使用你在 Providers 里配置的模型，herdr 里的 Claude Code、Codex 继续使用它们自己的登录与配置。后面接入 API易 时，影响的只是 Alma 这一侧。
Alma 不止是 agent 面板：5 个值得先开的功能
官网把 Alma 定义成本地优先、记忆优先的 AI Agent 应用，herdr 客户端只是其中一个身份。打开设置页，左侧这一列就能看出它的功能密度。
图 4：Alma 设置页的功能侧栏（长截图分两列拼接），Providers、Channels、Computer Use、Remote Access 都在这一列里。
一个窗口接完所有模型
Providers 里预置了 OpenAI、Anthropic、Google Gemini、xAI Grok、DeepSeek、Moonshot、Z.AI、Kimi、AiHubMix、OpenCode Go 等入口，也能加任意 OpenAI 兼容服务。Key 存在本机，同一个对话里随时换模型。
图 5：Providers 列表里预置的服务商，xAI Grok、Kimi、Z.AI 等都在其中。
记忆和活动记录：它可能比你先想起今天干了什么
Memory 把重要信息存成语义向量，可以查看、编辑、删除；Activity Recorder 会定期在本地截屏并 OCR，分析你在做什么项目，记录只留在本机。有 X 用户被 Alma 主动说出「你下午在 GitLab 上合并 MR、发 release」吓了一跳，专门发帖 @yetone。这种像人的表达，来自它真的翻了自己的小本子，而不是复述日志。
图 6：X 用户 @rubickeho 被 Alma 说出下午的操作后发帖，截图里的回答由 Alma 生成。
这是单个用户的使用反馈，不是官方功能承诺；Activity Recorder 的范围以软件内说明为准。
让它替你操作 Mac
Computer Use 能在后台驱动原生 Mac 应用，不抢当前窗口的焦点。它需要签名 helper，以及辅助功能和屏幕录制权限；建议先打开严格逐应用审批，只放行需要的应用，动作日志只留在本机。
图 7：Computer Use 的权限、逐应用审批和画中画监看开关。
微信、飞书、Telegram 都能接
Channels 里有 Telegram、Discord、飞书、Lark、WeChat、Email 六个入口。开一个 Telegram Bot，就能在手机上接着聊，不必守在电脑前。
图 8：Channels 里的六个入口，Telegram 可开 Bot。
还有一堆可以慢慢装的零件
Image Generation 生图、Token Savings 省 token、Prompts、Skills、MCP Servers、Plugins、Hooks、Speech 与 Text-to-Speech、People、Web Search、Chrome Relay、Remote Access（Beta）。不用一次全开，按需打开就行。
5 步装好 Alma 和 herdr，把终端变聊天窗口
动手前先核对平台支持。下表合并了 Alma 和 herdr 的官方信息，其中有两处需要特别留意：
| 平台 | Alma | herdr | 注意事项 |
|---|---|---|---|
| macOS | Apple Silicon 和 Intel 的 .dmg；文档要求 macOS 26 或更高，最低 4GB 内存，建议 8GB | 官网写 Apple silicon | Intel Mac 用户要先确认 herdr 能否运行，官网系统列表未写 Intel |
| Windows | x64 .exe，支持 Windows 10/11 | x86_64 | 两边都有安装包 |
| Linux | 下载页列出 x64 的 AppImage、.deb、.rpm | x86_64 和 arm64 | 文档写「即将支持」，与下载页不一致 |
| iPhone | TestFlight 公测，需与电脑配对 | 不在手机上运行 | 不是 App Store 正式版 |
| Android | 提供 APK 测试包 | 不在手机上运行 | 本文参考的官方文档没写功能范围 |
第 1 步：安装 herdr 并启动 agent
- 在哪点：Mac 用户从
herdr.dev下载 .dmg 并拖进 Applications。macOS 和 Linux 也可以在终端执行 herdr 安装命令curl -fsSL https://releases.herdr.dev/app/install.sh | sh。Windows 用 PowerShell 执行powershell -c "irm https://releases.herdr.dev/app/install.ps1 | iex"。 - 会看到什么：打开 Herdr 后，点标签栏的
+，可以启动 Claude Code、Codex 或其他程序。按官方说明，安装时会在缺少 herdr-core 的情况下一并配置。 - 不通过怎么办：先确认 agent 本身能在普通终端运行，再回到 Herdr 启动。herdr 不替你解决 agent 的登录问题。
验证标准：Herdr 窗口里至少有一个 agent 正在运行。建议保留它，下一步要用来测试连接。
第 2 步：安装并打开 Alma 客户端
- 在哪点：从
alma.now下载对应系统的安装包。macOS 把 Alma 拖进 Applications，Windows 运行 .exe。Linux 的 AppImage 要先执行chmod +x赋予执行权限，.deb 用apt install，.rpm 用dnf或zypper。 - 会看到什么：Alma 主窗口正常启动。macOS 首次打开可能弹出安全警告，这时右键或按住 Control 点击 Alma，再选 Open。
- 不通过怎么办：如果 macOS 提示「Alma is damaged and can’t be opened」，在终端执行
xattr -cr /Applications/Alma.app，用来清除这个应用的扩展属性。启动就崩溃时，官方给的办法是删除~/Library/Application Support/alma后重装，但这会重置 Alma 的本地数据，操作前要想清楚。
第 3 步：把 Alma 切到 Agent 侧栏
- 在哪点：用 Alma 顶部的切换按钮把侧边栏切到 Agent，Mac 快捷键是
⌘⇧A。 - 会看到什么：侧栏出现第 1 步启动的 agent。点击一个 pane，主区域显示对话，而不是终端画面。
- 不通过怎么办：这一步按文档不需要手动配置 socket（本机进程通信入口）。如果提示「herdr 没有运行」，先回到 Herdr 确认服务已启动，再看下文的报错对照表。
验证标准：侧栏出现 agent，点 pane 后出现对话。在输入框里发一句话，内容会进入对应 pane，效果等同于你在那里直接输入。
第 4 步：用 TestFlight 配对 iPhone
- 在哪点：先在 App Store 安装 TestFlight，再在 iPhone 上打开 Alma 的公测邀请并安装。然后回到电脑，打开 Alma 的 设置 › 远程访问（英文界面为 Remote Access），调出配对码，用 iPhone 扫码。
- 会看到什么：手机上出现与电脑相同的 agent 列表和聊天记录。官方说明连接方式是同一 Wi-Fi 下直连，或经 Alma 中继进行端到端加密传输。
- 不通过怎么办：先确认电脑上的 Alma 已打开、配对码仍显示在屏幕上，再重新扫码。如需使用远程屏幕，还要在 Mac 上给 Alma 开启屏幕录制和辅助功能权限，这个功能只支持 Mac。
验证标准：手机上出现同一列表，并能打开其中一个 agent 的对话。
第 5 步：把 Alma 的模型接到 API易
这一步是可选项，只影响 Alma 自己的聊天窗口和后台模型。API易 apiyi.com 是 OpenAI 兼容的模型聚合平台，用一个 Key 可以调用 Claude、GPT、Gemini、DeepSeek 等模型，新用户有免费测试额度。
以下步骤按 Alma Custom Provider 文档和 API易 文档整理；接好后的效果见图 9。
- 在 API易 控制台创建 Key。
- 打开 Alma 设置（
Cmd+,或Ctrl+,），进入 Providers，点 Add Provider，类型选 Custom。 - 按下表填写字段后点 Save。
- 在 Provider 设置里点 Add Model，手动填入准确的模型 ID。
- 点 Test，确认 Alma 能完成一次简单请求。
- 进入 设置 → General → Tool Model，选一个快而便宜的模型，再点 Test。
| 配置项 | 填写内容 | 说明 |
|---|---|---|
| Provider type | Custom | Alma 用它接入 OpenAI 兼容接口 |
| Name | API易 | 只是显示名，可以自定义 |
| Base URL | https://api.apiyi.com/v1 |
API 端点地址，要带协议，结尾不要加斜杠 |
| API Key | 在 https://api.apiyi.com/token 创建 |
不要提交到代码仓库或截图外传 |
| 聊天模型 ID | claude-sonnet-5-5、gpt-6-luna |
通过 Add Model 手动添加 |
| Tool Model | gemini-3.8-flash 或 deepseek-v4.1-flash |
负责工具选择、记忆、标题生成等后台操作 |
| 记忆 embedding（可选） | text-embedding-3-small |
用于把记忆存成语义向量 |
图 3：Alma Custom Provider 配置流程示意图，以 API易 apiyi.com 的接口为例，非软件实际截图。
验证标准：Provider 的 Test 通过，模型选择器里能看到刚添加的模型，并能在 Alma 普通聊天窗口收到回复。如果失败，优先检查 Base URL 结尾、模型 ID 和 Key。官方建议 Tool Model 不要用推理模型或又慢又贵的大模型。
图 9：接好 APIYI 后，Alma 首页的模型选择器里会显示 deepseek-flash · APIYI。
配置建议：先只添加一个聊天模型和一个 Tool Model，Test 通过后再逐步扩展。模型型号与价格以平台型号列表为准：docs.apiyi.com/models。
用好 Alma 的 4 个日常场景：从谁在等我到多台电脑
用 Alma 侧栏判断谁在等我
每天打开 Alma，先看侧栏，不用再逐个巡检终端。三种状态的含义和建议动作如下：
| 侧栏状态 | 官方含义 | 建议动作 |
|---|---|---|
| 需要输入 | Agent 提了问题，正在等待 | 优先处理，确认权限或回答问题 |
| 工作中 | Agent 正在进行一轮操作 | 不必打断，可以去处理其他任务 |
| 已完成 | Agent 做完了，未读轮次会标出 | 检查结果，再决定下一步 |
Agent 需要你或完成任务时，Alma 会发送桌面通知。某个工作区或标签页不想被打扰时，可以在菜单里静音。Workspace（工作区）适合按代码仓库划分，标签页适合按任务划分，这也是 herdr 官网给出的组织方式。
在 Alma 对话里读懂子 Agent 和改动
Alma 直接读取 Claude Code、Codex 和 pi 的会话记录，工具调用、子 Agent 和文件改动会按顺序排好。需要回复时，你可以选多选项、批准命令、排队下一条消息，或者发送文件和照片。发出的内容会进入对应 pane，所以回复前要确认选中的是正确的 agent。
随时切回 herdr 真终端
聊天视图适合快速阅读，但查看完整输出或处理交互式程序时，切到屏幕视图更直接。手机上的终端会按屏幕宽度换行，并提供 esc、^C 和方向键。其他能在 herdr 里运行的程序也会显示为实时终端，只是没有 Claude Code、Codex、pi 那样的完整对话记录。
用 Alma 管理多台电脑上的 Agent
一个 Alma 可以操控多台电脑上的 agent。先在另一台电脑打开 设置 › 远程访问，复制配对链接，再回到当前 Alma 的「添加电脑…」里粘贴。能直连时 Alma 走局域网，否则通过端到端加密的 Alma 中继连接。iPhone 也可以配对多台 Mac，并一键切换。
排查 Alma 和 herdr 的常见报错与坑
排错时先判断问题属于哪一层。「herdr 没运行」「会话不对」「版本过旧」看上去都是连不上，处理方法却不同：
| 现象 | 可能原因 | 处理方法 |
|---|---|---|
| 提示「herdr 没有运行」 | 目标电脑上的 herdr 未启动 | 在那台电脑启动 herdr，再点击重新连接 |
| herdr 已启动，但 Alma 仍连不上 | 使用了命名会话或自定义 socket，HERDR_SESSION 或 HERDR_SOCKET_PATH 不对 |
在登录 Shell 中设置正确的值，再点击重新连接 |
| 提示「请更新那台电脑上的 Alma」 | 对方电脑上的 Alma 比当前电脑旧 | 到提示中的那台电脑更新 Alma |
| agent 列表里看不到 agent | agent 版本未报告状态、在 tmux 内运行，或由 Herdr TUI 启动 | 更新 agent，避免套 tmux，并确认它在哪个 herdr 程序里启动 |
| Provider 报 Authentication Failed 或 Model Not Found | Key 格式不对，或模型 ID 不准确 | 重新复制 Key，并按型号列表核对模型 ID |
HERDR_SESSION 这一类最容易被误判。Alma 从程序坞或开始菜单打开时，也会读取登录 Shell 的环境变量，但你只在当前终端临时设置的变量，未必进入登录 Shell。默认会话的 socket 位于 <config>/herdr/herdr.sock，命名会话位于 <config>/herdr/sessions/<名称>/herdr.sock。
另外有三个容易踩的坑：
- Herdr 应用和 Herdr TUI 不共享 agent：TUI 是另一个带独立服务的程序，在一边启动的 agent 不会出现在另一边。
- 状态依赖 OSC 7501 协议：这是 agent 向 herdr 上报状态的开放协议。不支持它的程序仍能运行，只是没有状态显示。
- 关闭标签页会退出 agent：会话记录仍保留在电脑上，但进程已经结束。想让 agent 继续跑，不要把关闭标签页当成隐藏窗口。
Alma 的版本更新很频繁，遇到具体 agent 的问题时，先升级再排查。例如 v0.4.428 修复了 Codex 使用共享 app-server daemon 时，面板聊天找不到线程的问题，也修复了 iOS 解锁或切换网络时短暂出现重连提示的问题。
常见问题 FAQ
Q1：Alma 和 herdr 是什么关系？
herdr 负责运行和组织 agent，Alma 是它的图形客户端。Alma 连接本机 herdr 服务，把 pane 显示成可读可回的界面。Alma 本身还是一款支持多模型、记忆、Skills 和 MCP 的桌面 AI 应用。
Q2：Alma 和 herdr 都免费吗？
两者要分开看。herdr 官网写明应用、herdr-core 和 Herdr TUI 都免费，并以 Apache 2.0 开源。Alma 官网的下载按钮写着 Free download，但没有价格页，官方也没有写明长期是否无限制；Alma 应用本体不开源。
Q3：关掉 Alma 后，Claude Code 和 Codex 会停吗？
关闭 Alma 或 herdr 应用窗口，agent 仍在 herdr-core 里运行。机器重启或 herdr-core 停止时，agent 才会停止。恢复后的 pane 只有同目录 shell，进行中的工作需要你重新启动。
Q4：接入 API易 后，Claude Code 和 Codex 也会走这个接口吗？
不会。通过 API易 apiyi.com 配置的 Provider 只服务 Alma 的聊天窗口、Tool Model 等功能。herdr 里的 Claude Code、Codex 继续使用各自的登录与配置，本文也不涉及替代订阅或绕过登录。
Q5：除了 Claude Code、Codex 和 pi，其他 agent 能用吗？
能在 herdr 里运行的程序都会显示为实时终端，但只有 Claude Code、Codex 和 pi 有完整对话记录。是否显示工作中、已完成等状态，还取决于程序是否支持 OSC 7501。
Q6：Alma 的 Tool Model 应该怎么选？
优先选响应快、成本低的小模型，不要选推理模型。可以在 API易 apiyi.com 的型号列表里确认 `gemini-3.8-flash` 或 `deepseek-v4.1-flash` 当前是否可用，再到 Alma 里添加并点 Test。
Alma 和 herdr 核心要点 Key Takeaways
- 分工清楚：herdr 运行 agent，Alma 负责阅读和回复。
- 状态优先：侧栏按需要输入、工作中、已完成分组。
- 连接简单：默认不用配置 socket，连不上先查 herdr。
- 手机公测：iPhone 通过 TestFlight 安装，并与电脑配对。
- 运行边界：关窗口不停，重启或 herdr-core 停止后不恢复工作。
- 模型分线：接入 API易 只影响 Alma，不影响 agent 自身配置。
- 功能面很宽：Providers、Memory、Computer Use、Channels 都在同一个 App 里。
总结与行动建议
我也是用了 Alma 很久了，其实 Alma 早在 OpenClaw 火之前就有了，由独立开发者 yetone 大佬开发，而迭代到如今已经非常趁手好用了，我在里面使用 DeepSeek V4.1 Flash 让我感觉到我是在使用 Opus 5.5，Alma 这个 Harness 让模型的主观能动性和人味特别强，不论是做任务（由于主动性做的特别好），还是写作（基本没有人机味）。还有他的 Computer Use 功能，我体感上比 Codex 要强，超级快超级丝滑！！
至于模型接入，可以等 agent 工作流稳定后再配置。通过 API易 apiyi.com 创建 Key，先用一个聊天模型和一个 Tool Model 跑通 Test，再根据实际用量调整。可以通过 Magpie 可视化接入哦，很方便，延伸阅读里面有教程
📚 参考资料
- Alma 官网：产品功能、下载入口和官方 FAQ
- 链接：
alma.now -
说明： 用于核对平台支持和 iPhone 公测信息
-
Alma herdr 图形客户端文档：连接方式、侧栏状态和常见问题
- 链接：
alma.now/docs/zh/features/herdr -
说明： 用于排查 socket、会话和版本提示
-
Alma Custom Providers 文档：OpenAI 兼容接口配置
- 链接：
alma.now/docs/providers/custom -
说明： 用于配置 Base URL、Key 和模型 ID
-
herdr 官网：herdr-core、OSC 7501 和系统支持
- 链接：
herdr.dev -
说明： 用于了解 agent 运行方式和 Herdr FAQ
-
Alma 版本记录：安装包发布记录
- 链接：
github.com/yetone/alma-releases -
说明： 用于核对 v0.4.428 的发布时间和修复内容
-
API易模型列表：可用模型与价格说明
- 链接：
docs.apiyi.com/models - 说明： 配置模型 ID 前先在这里核对
作者：API易 技术团队
技术交流：欢迎在 API易 网站首页联系我们，更多资料可访问 docs.apiyi.com 文档中心
