夜雨聆风
这篇教程是给第一次接触 Mercury 的用户准备的。你可以把它理解成一个“从零开始”的完整上手指南：先装环境，再装 Mercury，然后完成首次配置，最后根据自己的需要决定是否开启 Telegram 和后台守护进程。
如果你以前几乎没有接触过命令行，也没关系。下面我会尽量把每一步都拆开写清楚，并告诉你Mercury与小龙虾跟hermes的区别。这是一篇枯燥的教程，文章很长可以先收藏！
一、先弄清楚 Mercury 是什么
Mercury 是一个运行在本机终端里的 AI Agent。你可以直接在终端和它聊天，也可以把它接到 Telegram，这样你在手机上也能和它对话。
Mercury 主要依赖下面几样东西：
你的电脑里要先安装 Node.js 你至少要有一个可用的大模型 API Key 如果你想用手机远程聊天，还需要一个 Telegram Bot Token
如果你只想先在电脑里跑起来，Telegram 这一步可以先跳过，后面再补。
Mercury、OpenClaw 和 Hermes 有什么区别
如果你在接触 Mercury 之前，已经听说过 OpenClaw 或 Hermes，那么最容易产生的问题通常是：
“它们是不是同一类东西？只是名字不同吗？”
严格来说，它们都可以归到“AI Agent / 本地代理 / 任务执行代理”这类工具里，但设计重点并不完全一样。
先用一句话理解三者
OpenClaw：更强调本地执行能力，重点是“真的能动手做事” Hermes：更强调持久记忆和自主性，重点是“长期积累和持续工作” Mercury：更强调权限控制、成本可控和后台稳定运行，重点是“适合日常长期使用”
1. Mercury 更偏“可控、可长期运行”的路线
Mercury 的核心定位比较明确：
它是命令行原生的 agent 可以在后台以守护进程方式运行 支持 Telegram 这类远程交互方式 比较强调权限边界、配置可读性和预算控制
对普通用户来说，这意味着 Mercury 更适合作为“长期挂着跑的个人代理”。
它不只是一次性对话工具，而是更接近“平时在你电脑后台待命，需要时可以调出来做事”的那种形态。
2. OpenClaw 更偏“本地执行能力很强”的路线
OpenClaw 的重要意义在于：
它证明了开发者确实需要本地 agent 它不是单纯网页聊天，而是真能执行命令、操作环境 它把“本地可执行代理”这件事推到了更多人面前
如果用新手能理解的话说，OpenClaw 更像是：
“让 AI 不只是说怎么做，而是真的开始替你在本机做事。”
当然，围绕这类强执行型代理，大家也会自然关注权限、扩展生态和安全边界问题：
OpenClaw 更偏执行能力和生态扩展 Mercury 更偏权限收紧和风险控制
这不是简单的“谁绝对更好”，而是产品设计取舍不同。
3. Hermes 更偏“记忆和自主成长”的路线
Hermes 的特色在于：
强调持久记忆 倾向于让代理具备更强的连续性 更重视自主生成和长期积累能力
如果你更在意的是：
代理能不能长期记住很多东西 能不能逐步形成自己的工作方式 能不能持续运行并带有更强的自主性
那 Hermes 这类路线会更有吸引力。
相对地，Mercury 在这部分更强调的是“可读、可改、可版本控制”。也就是把人格、偏好、风格等内容尽量放在显式的 Markdown 文件里，而不是更多依赖一个黑盒式记忆系统。
4. 三者最核心的差异，其实是设计重心不同
比较客观的总结是：
OpenClaw更像在回答：“AI 能不能真正获得本地执行能力？” Hermes更像在回答：“AI 能不能拥有持续记忆和更强自主性？” Mercury更像在回答：“AI 如果真的长期替人做事，怎样才能更安全、更省钱、更稳地运行？”
所以它们并不是完全互斥的关系，更像是三种不同侧重点的答案。
5. 对普通用户来说，应该怎么选
如果你最看重“本地执行能力”和工具操作感，通常会更关注 OpenClaw如果你最看重“持久记忆、自主演化、长期积累”，通常会更关注 Hermes如果你最看重“权限边界、预算控制、后台守护进程、日常稳定使用”，通常会更关注 Mercury
它们都在做 AI Agent，但 Mercury 更偏“稳、可控、可长期运行”，OpenClaw 更偏“强执行”，Hermes 更偏“强记忆和持续性”。
二、安装前准备
在正式安装之前，建议先准备好下面这些内容。
1. 一台电脑
支持的平台通常包括：
macOS Linux Windows
如果你是 macOS 或 Windows 用户，直接跟着本文做就可以。Linux 用户也能参考，大多数步骤是一样的。
2. 安装 Node.js 20 或更高版本
Mercury 要求 Node.js 20 或更高版本。
如果你已经装过 Node.js，可以先检查版本。
打开终端，输入：
node -v如果输出类似下面这样：
v20.18.0或者任何 v20、v21、v22 之类的版本，就说明 Node.js 版本够用了。
然后再检查 npm：
npm -v只要能正常输出版本号，一般就没问题。
3. 如果你还没有安装 Node.js
最适合小白的方法，是去 Node.js 官网下载安装包：
Node.js 官网
建议优先安装 LTS（长期支持版）。
安装步骤通常是：
打开官网 下载 LTS 版本安装包 双击安装包 一路点“继续 / Next” 安装完成后，重新打开终端 再次执行 node -v和npm -v检查是否成功
如果你执行 node -v 仍然提示“command not found”或“不是内部或外部命令”，通常是下面两种原因：
终端没有重新打开 Node.js 没安装成功
这时最简单的处理方式是：关闭终端，重新打开，再测一次；如果还不行，就重新安装一遍 Node.js。
4. 准备至少一个大模型提供商的 API Key
首次配置 Mercury 时，你至少要提供一个模型提供商的密钥。文档里提到支持这些提供商：
DeepSeek OpenAI Anthropic Grok Ollama Cloud Ollama Local
如果你是新手，建议优先考虑你已经在用、最熟悉的那一个。只要有一个可用就够开始使用了。
5. 可选：准备 Telegram Bot Token
如果你想通过 Telegram 在手机上使用 Mercury，就提前准备一个 Telegram 机器人令牌。
这个令牌需要通过 Telegram 里的 @BotFather 创建。
如果你暂时不需要 Telegram，可以先不准备，安装完成后只在终端里使用 Mercury。
三、安装 Mercury
Mercury 有两种常见启动方式。
方法 A：全局安装（推荐给新手）
在终端执行：
npm i -g @cosmicstack/mercury-agent这条命令的意思是：把 Mercury 安装到你的电脑里，之后你就可以直接输入 mercury 来启动它。
安装完成后，可以检查是否成功：
mercury --help如果能看到帮助信息，说明安装成功了。
方法 B：不安装，直接临时运行
如果你只是想先试试看，也可以用：
npx @cosmicstack/mercury-agent这种方式的特点是：
不一定要提前全局安装 适合临时体验 但长期使用通常还是全局安装更方便
对于小白用户，我更建议直接用“方法 A：全局安装”。
四、首次启动和初始配置
安装完成后，第一次运行 Mercury：
mercury或者：
mercury start --foreground第一次运行时，Mercury 一般会进入首次设置向导。你会被依次要求填写一些信息。
首次配置时会让你填写什么
1. 你的名字
这个名字主要是给 Mercury 在对话里称呼你用的。
你可以填写：
真实姓名 英文名 昵称
比如：
Alice2. Agent 名称
默认一般是 Mercury，你也可以改成自己喜欢的名字，比如：
Mercury Xiao助手 MyAgent
如果你不知道填什么，直接回车保留默认值就可以。
3. 选择大模型提供商
这里会让你选择你要接入哪个模型服务。
对新手来说，最重要的原则很简单：
你有哪个 API Key，就选哪个 不确定时先只选一个，后面再补
4. 选择模型
输入有效的 API Key 之后，Mercury 会尝试读取可用模型，并让你选择默认模型。
如果这里能正常列出模型，通常说明你的 API Key 没问题。
如果列不出来，通常是：
API Key 填错了 提供商网络不可用 账户权限不够
这时重新检查密钥最重要。
5. Telegram Bot Token（可选）
如果你已经准备好了 Telegram 机器人令牌，可以在这里直接填。
如果你暂时不想启用 Telegram，一般可以先跳过，或者后面再通过 mercury doctor 重新配置。
6. API Key
这里至少要填一个可用的大模型密钥，否则 Mercury 没法真正工作。
Mercury 会先做格式验证，然后尝试获取模型列表做进一步验证。
这对新手很友好，因为它能帮你提前发现“密钥看起来像对的，但其实不能用”的问题。
五、配置会保存到哪里
Mercury 的运行数据默认保存在：
~/.mercury/这里的 ~ 代表当前用户的家目录。
也就是说：
macOS / Linux 一般在你的用户目录下 Windows 对应的是你的用户目录
Mercury 不会把这些配置写进你的项目文件夹里，这一点对新手非常友好，不容易把项目目录弄乱。
常见文件包括：
~/.mercury/mercury.yaml：主配置文件 ~/.mercury/daemon.pid：后台进程 PID ~/.mercury/daemon.log：后台运行日志 ~/.mercury/skills/：已安装技能 ~/.mercury/memory/：记忆数据
六、最适合新手的启动方式
如果你刚装好，建议先用前台模式测试是否正常。
方式 1：前台运行
mercury start --foreground简写：
mercury start -f前台模式的优点是：
你能直接看到输出 出错时更容易排查 最适合第一次测试
如果你看到交互界面，并且可以开始输入内容和 Mercury 对话，就说明基本安装成功了。
退出前台模式时，一般按：
Ctrl + C方式 2：一键启动推荐方式
如果你已经确认它能正常运行，推荐使用：
mercury up这条命令是官方更推荐的“省心模式”。
它通常会帮你做这些事：
如果系统服务还没装，会尝试安装 启动 Mercury 后台守护进程 检查 Mercury 是否已经在运行 如果已经在运行，会显示对应的进程 ID
对于不想折腾细节的小白用户，mercury up 基本可以理解成“帮我把 Mercury 稳定跑起来”。
七、后台运行和守护进程模式
很多新手第一次用终端程序时，会遇到一个问题：
“我一关终端，程序是不是就没了？”
如果你用的是普通前台模式，答案通常是“会停止”。
而 Mercury 的守护进程模式，就是为了解决这个问题。
启动后台守护进程
mercury start默认情况下，这条命令会以后台模式运行 Mercury。
后台模式的意思是：
Mercury 会在后台持续运行 你关闭当前终端窗口后，它也可以继续工作 如果你启用了 Telegram，你可以继续在手机上和它聊天
停止后台进程
mercury stop如果你想彻底停掉后台运行的 Mercury，用这条命令就行。
重启后台进程
mercury restart如果你刚改了配置，或者觉得 Mercury 状态不对，最简单的方式通常就是重启一次。
查看状态
mercury status这条命令一般会告诉你：
Mercury 是否正在运行 当前后台进程 PID 日志文件路径
查看日志
mercury logs一般会显示最后一部分后台日志，方便你排查问题。
如果你启用了后台运行，但发现 Telegram 没回复、任务没执行、模型没响应，第一时间先看日志，往往最有帮助。
八、如何开启更详细的调试日志
如果启动时有问题，可以加上 --verbose：
mercury start --verbose这会输出更详细的调试信息。
新手可以这样理解：
正常使用时，不一定需要 --verbose出问题时，优先加这个参数看报错
九、升级 Mercury
如果以后 Mercury 发布了新版本，建议优先使用：
mercury upgrade这比你手动重新执行 npm i -g 更稳妥。
它通常会：
检查 npm 上是否有新版本 如果 Mercury 正在运行，会先停止后台进程 删除旧版本相关包，避免安装冲突 再安装新版本 显示升级前后的版本变化
如果你遇到 ENOTEMPTY 错误
有些用户在手动执行下面命令时会遇到问题：
npm i -g @cosmicstack/mercury-agent错误可能类似：
ENOTEMPTY: directory not empty, rename ...这种情况下，不建议继续硬装，直接改用：
mercury upgrade通常更容易解决。
十、重新配置：mercury doctor
如果你后面想修改配置，比如：
更换 API Key 更换模型提供商 增加 Telegram 关闭 Telegram 修改预算
可以执行：
mercury doctor这条命令会重新打开配置向导，并自动带出当前已有的值。
小白最需要知道的几点
在某个字段直接按回车，通常表示“保留当前值” 已有 API Key 往往会以打码形式显示 如果你想替换，就直接粘贴新的 如果想关闭 Telegram，通常可以按提示输入 none
例如，旧密钥可能显示成类似：
sk-x••••4f2a这表示系统认识到你已经有一个密钥，但不会完整展示出来。
十一、Telegram 配置详细教程
如果你想在手机里通过 Telegram 使用 Mercury，可以照下面来。
第一步：创建机器人
在 Telegram 中打开：
BotFather
然后：
发送 /start发送 /newbot按提示输入机器人名称 按提示输入机器人用户名 BotFather 会返回一串 Bot Token
这串 Token 看起来通常像这样：
1234567890:AAExampleTokenHere把它复制保存好。
第二步：在 Mercury 里填入 Bot Token
如果你还没完成首次配置，就在首次配置时填入。
如果你已经装好了，再执行：
mercury doctor然后把这个 Telegram Bot Token 填进去。
第三步：完成首次配对
如果你是第一次给这个 Mercury 实例接 Telegram，通常还需要做一次配对。
流程一般是：
在 Telegram 中找到你刚创建的机器人 给它发送 /startTelegram 会返回一个配对码 回到终端 把这个配对码粘贴到 Mercury 的 CLI 里 完成绑定
这样做的目的，是确保只有真正拥有本机终端访问权限的人，才能拿到这个 Mercury 实例的管理员权限。
首位用户和后续用户的区别
第一个完成配对的人，一般会成为管理员。
管理员可以：
批准新用户 拒绝新用户 提升或降级成员权限 重置整个 Telegram 访问列表
后面其他用户如果也给机器人发送 /start`，通常会变成待审核状态，需要管理员批准。
常用 Telegram 管理命令
mercury telegram listmercury telegram approve <code|userId>mercury telegram reject <userId>mercury telegram remove <userId>mercury telegram promote <userId>mercury telegram demote <userId>mercury telegram reset如果你是新手，一开始最常用的通常只有两个：
mercury telegram listmercury telegram approve <code|userId>
十二、系统服务与开机自启
如果你希望 Mercury 在开机或登录后自动运行，可以安装系统服务。
命令是：
mercury service install这条命令的意思可以简单理解为：
“把 Mercury 注册成系统级的自动运行服务。”
安装完成后，Mercury 往往会在系统登录后自动启动，并在崩溃时自动尝试恢复。
检查服务状态
mercury service status卸载服务
mercury service uninstall不同平台的大致方式
macOS
通常使用 LaunchAgent，配置文件类似：
~/Library/LaunchAgents/com.cosmicstack.mercury.plist特点：
通常不需要 sudo 登录时自动启动 崩溃后可自动拉起
Linux
通常使用 systemd 用户服务，配置文件类似：
~/.config/systemd/user/mercury.service特点：
一般不需要 sudo 可通过 systemctl --user管理某些场景下可额外配置 linger 实现无登录启动
Windows
通常使用任务计划程序。
特点：
登录后自动触发 一般不需要管理员权限 日志通常保存在用户目录下的 .mercury文件夹
十三、最推荐的新手安装路线
如果你完全不想看太多原理，只想“最快跑起来”，我建议直接按下面做。
路线 A：只在电脑终端里使用
安装 Node.js LTS 执行 npm i -g @cosmicstack/mercury-agent执行 mercury start -f按提示填好名字、模型提供商、API Key 成功进入交互界面后，先测试几句对话 没问题后，用 mercury up或mercury start改成长期运行
路线 B：终端 + Telegram 一起用
安装 Node.js LTS 创建 Telegram 机器人并拿到 Bot Token 执行 npm i -g @cosmicstack/mercury-agent执行 mercury start -f在首次配置里填入 API Key 和 Telegram Bot Token 去 Telegram 给机器人发送 /start把配对码粘贴回终端完成绑定 最后执行 mercury up，让它稳定后台运行
十四、常见问题排查
1. 输入 node -v 没反应，或者提示找不到命令
原因通常是 Node.js 没装好，或者终端还没刷新。
处理方法：
关闭终端重新打开 再次执行 node -v如果还是不行，重新安装 Node.js LTS
2. 输入 mercury 提示找不到命令
常见原因：
Mercury 没安装成功 全局 npm 路径没有生效
可以先重新执行：
npm i -g @cosmicstack/mercury-agent然后再试：
mercury --help如果还是不行，可以先临时用：
npx @cosmicstack/mercury-agent3. API Key 明明填了，但模型拉不出来
常见原因：
密钥填错 复制时多了空格 提供商账户本身没有可用模型权限 网络环境无法访问对应提供商接口
优先建议：
重新复制粘贴 API Key 确认账户余额或权限 执行 mercury doctor重新配置
4. Telegram 机器人没反应
先检查下面几件事：
Bot Token 是否填对 是否已经在 Telegram 里对机器人发送过 /start是否已经完成配对码确认 Mercury 是否真的在后台运行
你可以先执行：
mercury status再执行：
mercury logs一般就能看出大概问题。
5. 关闭终端后 Mercury 不工作了
说明你大概率是在前台模式运行。
解决方法：
mercury up或者：
mercury start如果你还想登录后自动启动，再执行：
mercury service install十五、常用命令速查表
安装与启动
npm i -g @cosmicstack/mercury-agentmercurymercury startmercury start -fmercury up停止与状态
mercury stopmercury restartmercury statusmercury logs重新配置与升级
mercury doctormercury upgrade系统服务
mercury service installmercury service statusmercury service uninstallTelegram 管理
mercury telegram listmercury telegram approve <code|userId>mercury telegram reject <userId>mercury telegram reset十六、给新手的最后建议
如果你是第一次安装 Mercury，不要一上来就追求“后台运行 + Telegram + 自动启动”一步到位。最稳妥的顺序是：
先确认 Node.js 装好 再确认 Mercury 能启动 再确认 API Key 可用 然后测试前台交互 最后再加 Telegram 和后台守护进程
这样出问题时更容易知道到底是哪一步出了错。
如果只记一句话，那就是：
先用 mercury start -f 跑通，再用 mercury up 做长期运行。
