适合：第一次在个人电脑安装智能体 CLI 的开发者、运营人员和小团队负责人
智能体 CLI 工具箱：安装、验证、切换与 Mayaai Top 接入
不要一次装完所有工具。先选择一个真实任务，从官方入口安装一种 CLI，再依次验证版本、登录和最小任务。需要多套 Provider 时再使用 CC Switch；最后单独核对 Mayaai Top 是发现了工具，还是已经具备执行适配。
先说结论
开始前先看这四个答案
| 问题 | 直接答案 |
|---|---|
| 应该一次安装全部工具吗？ | 不应该。先选择一个真实任务和一种 CLI，完成版本、登录与最小任务验证后，再增加第二种。 |
| CC Switch 会替我执行任务吗？ | 不会。它管理 Provider 配置和切换，具体任务仍由 Codex、Claude Code 等工具执行。 |
| QClaw 是 CLI 吗？ | 本教程中的腾讯 QClaw 是 macOS/Windows 桌面产品。GitHub 上存在同名社区 CLI，两者不是同一项目。 |
| 终端能运行，就能交给 Mayaai Top 吗？ | 不一定。还要检查 Mayaai Top 是否发现该工具，以及是否已经实现对应执行 Adapter。 |
完成后你会得到
- 根据真实任务选择一种适合首装的智能体 CLI。
- 完成官方安装、版本检查、登录和最小任务验证。
- 使用 CC Switch 管理官方 Provider，并完成切换与回滚检查。
- 准确判断工具在 Mayaai Top 中属于已安装、已发现还是可执行。
开始前准备
- 一台可以安装软件的 macOS 电脑；Windows 和 Linux 用户可按各步骤中的官方入口操作。
- 能够打开终端并复制一条命令，不要求具备编程经验。
- 准备至少一个工具的官方账号；不要把 API Key 粘贴到截图、聊天或代码仓库。
先看完整路径
完整路径只有四步：装、验、切、接
“装”确认工具来自官方来源；“验”检查版本、认证和最小任务；“切”只在确有多 Provider 需求时使用 CC Switch，并验证配置真的生效；“接”区分本机已安装、Mayaai Top 已发现和 Mayaai Top 可执行。前一步没有证据，就先不要进入下一步。
- 编码型：Codex、Claude Code、Kimi Code、Qoder。
- 常驻或自主型：OpenClaw、Hermes。
- 桌面一键环境：腾讯 QClaw，不按 CLI 讲解。
- 配置管理：CC Switch，不是任务执行器。
12 个操作步骤
现在跟着做
- 1
步骤 1 / 12
先选一种工具，再检查终端环境
如果主要修改代码，先在 Codex、Claude Code、Kimi Code、Qoder 中选一种。如果需要常驻自动化或消息入口，再考虑 OpenClaw；需要自主任务实验时再评估 Hermes。第一次安装不要同时改四套配置。
- `arm64` 通常表示 Apple Silicon，`x86_64` 通常表示 Intel Mac。
- 找不到 Homebrew 不影响所有安装脚本，但会影响后面的 CC Switch Cask 安装。
- 安装后要打开新终端，让 PATH 和 Shell 配置重新加载。
检查 Mac 芯片架构
uname -m检查当前 Shell
echo $SHELL检查 Homebrew
command -v brew你应该看到
你知道当前 Mac 的架构和 Shell，并已经选定本轮只安装的一种 CLI。
如果没看到
如果公司设备限制安装权限，先联系管理员。不要用未知来源的 `sudo` 命令绕过组织策略。
- 2
步骤 2 / 12
安装并验证 Codex CLI
Codex 适合在终端中理解代码库、修改文件和运行工程任务。下面使用 OpenAI 当前推荐的官方安装脚本。执行前先打开页面核对域名仍是 `chatgpt.com`。
macOS / Linux 官方安装
curl -fsSL https://chatgpt.com/codex/install.sh | sh打开新终端后检查版本
codex --version启动并完成官方登录
codex你应该看到
终端能输出 Codex 版本；首次启动出现 ChatGPT 登录或其他官方认证选项。
如果没看到
找不到 `codex` 时先打开新终端，再运行 `command -v codex`。不要在多个 Node、Homebrew 和脚本安装来源之间反复覆盖。
- 3
步骤 3 / 12
安装并验证 Claude Code
Claude Code 适合在明确的项目目录中阅读、修改和验证复杂代码库。Anthropic 当前推荐原生安装；Homebrew 也提供 Cask。安装后用 Doctor 检查环境，而不只看命令是否存在。
macOS / Linux / WSL 原生安装
curl -fsSL https://claude.ai/install.sh | bash检查版本
claude --version检查环境
claude doctor在测试目录启动并登录
claude你应该看到
版本命令返回结果，Doctor 没有阻断项，启动后可以进入官方登录流程。
如果没看到
如果旧 npm 版本与原生版本冲突，先用 `command -v claude` 确认当前执行路径，再按 Anthropic 官方迁移说明处理。
- 4
步骤 4 / 12
安装 OpenClaw，并检查 Gateway
OpenClaw 不只有一个终端命令。除了版本和 Doctor，还要检查 Gateway 是否运行。CLI 安装成功但 Gateway 停止时，常驻任务或消息入口仍不可用。
macOS / Linux 官方安装
curl -fsSL https://openclaw.ai/install.sh | bash检查 CLI
openclaw --version检查配置
openclaw doctor检查 Gateway
openclaw gateway status你应该看到
版本、Doctor 和 Gateway 分别给出状态；你能判断问题位于命令、配置还是后台服务。
如果没看到
Gateway 未运行时按官方初始化或启动说明处理。不要为了让状态变绿而开放不需要的消息渠道和系统权限。
- 5
步骤 5 / 12
安装 Hermes Agent，并先限制权限
Hermes 适合探索自主任务和多工具工作流。首次配置 Provider 时，只使用自己拥有授权的账号，并先限定工作目录、可用工具和费用范围。
macOS / Linux 官方安装
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash启动 Hermes
hermes你应该看到
Hermes 可以启动并进入首次配置；你已经明确 Provider、工作目录和权限边界。
如果没看到
安装失败时先查看官方仓库的系统要求。不要把真实 API Key 发到公开问题区、截图或聊天记录。
- 6
步骤 6 / 12
安装 Kimi Code，而不是沿用旧 Kimi CLI
Kimi Code CLI 是当前产品入口。旧 Kimi CLI 仓库已经提示产品演进，新的教程不应继续把旧安装方式作为默认路径。
macOS / Linux 官方安装
curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash启动 Kimi Code
kimi进入交互界面后登录
/login你应该看到
运行 `kimi` 后进入 Kimi Code CLI，并能通过 `/login` 完成官方认证。
如果没看到
如果电脑上已经存在旧 `kimi` 命令，先运行 `command -v kimi` 并对照官方迁移说明，不要直接覆盖未知配置目录。
- 7
步骤 7 / 12
安装 Qoder CLI，并注意真实命令名
产品名是 Qoder，但 CLI 命令是 `qodercli`。使用官方 Quick Start 安装后，先检查版本，再进入交互界面登录。
macOS / Linux 官方安装
curl -fsSL https://qoder.com/install | bash检查版本
qodercli --version启动 Qoder CLI
qodercli进入交互界面后登录
/login你应该看到
`qodercli --version` 返回版本，启动后可以进入官方登录流程。
如果没看到
如果误用 `qoder` 找不到命令，改用 `qodercli`。Windows 用户应使用官方 PowerShell 安装入口。
- 8
步骤 8 / 12
把腾讯 QClaw 当作桌面应用安装
腾讯 QClaw 官方页面提供 macOS 和 Windows 桌面下载，它不是本教程前几步那样的 CLI。GitHub 上存在同名 `qclaw` 社区项目，不要把两者的命令、维护者或安全说明混在一起。
- 只从 https://qclaw.services/ 打开腾讯 QClaw 官方下载页。
- 根据系统下载安装包，核对开发者和系统安全提示。
- 如果你寻找的是某个开源 `qclaw` CLI，先核对仓库组织、维护者和许可证。
你应该看到
你能明确说明安装的是腾讯 QClaw 桌面产品，而不是同名社区 CLI。
如果没看到
下载页、签名或开发者信息不一致时停止安装，返回官方页面重新核对。
- 9
步骤 9 / 12
安装 CC Switch，但先理解它不负责执行
CC Switch 用于管理 Claude Code、Codex 等工具的 Provider 配置。它不会替你购买模型、执行任务，也不会让尚未适配的 CLI 自动接入 Mayaai Top。官方仓库说明唯一官网是 `ccswitch.io`。
macOS Homebrew Cask
brew install --cask cc-switch从应用程序启动
open -a "CC Switch"你应该看到
CC Switch 可以启动，你能看到它当前官方说明覆盖的工具和 Provider 配置入口。
如果没看到
Homebrew 找不到 Cask 时先运行 `brew update` 并核对官方仓库。不要从搜索广告或第三方下载站获取安装包。
- 10
步骤 10 / 12
创建 Provider，完成切换和回滚
只为当前确实使用的工具创建 Provider。保存前记录原配置；切换后关闭旧终端，打开新终端再运行版本和登录检查。界面显示已切换，不代表旧进程已经读取新配置。
- 优先使用工具官方 Provider；第三方中转服务需要单独评估数据、费用和账号风险。
- 配置记录只保留工具、Provider、认证方式和回滚位置，不复制真实 API Key。
- 切换失败时先恢复原 Provider，再依次检查环境变量和配置文件。
检查是否有环境变量覆盖配置
env | grep -E 'OPENAI|ANTHROPIC|BASE_URL' | sed 's/=.*$/=<redacted>/'你应该看到
新终端中的目标 CLI 能正常启动；切回原 Provider 后也能恢复，不需要重新安装 CLI。
如果没看到
切换无效时不要继续新增配置。先检查旧终端、环境变量和工具自己的配置文件是否覆盖了 CC Switch。
- 11
步骤 11 / 12
核对 Mayaai Top 的三个支持层级
本机命令存在，只说明已经安装。运行设备报告命令，说明 Mayaai Top 已发现。只有实现执行 Adapter 并通过任务验证，才属于可执行。当前 Codex、Claude Code、OpenClaw 有执行路径；Hermes、Kimi 只有发现定义；Qoder、QClaw 当前未接入。
- 已安装：终端能够找到命令。
- 已发现：Mayaai Top 运行设备报告该 Provider。
- 可执行：可以创建任务，并产生真实执行记录和产出。
- 产品版本变化后，以运行设备页面和当前代码为准。
你应该看到
你能为每个已安装工具标记“已安装、已发现、可执行”，不会把三种状态混写。
如果没看到
工具没出现在运行设备页面时，先确认 Mayaai Top 本地助手与终端使用同一 PATH。出现但不能选为执行方案时，说明可能只有发现能力。
- 12
步骤 12 / 12
用一个无风险任务完成最终验收
只选择当前明确可执行的工具。测试任务使用单独目录，不读取真实客户资料，不外发，也不删除文件。任务完成后同时检查执行记录和产出文件。
- 测试任务示例：读取测试目录中的三个文件名，生成一份 Markdown 清单。
- 运行设备必须在线，执行助手必须绑定真实可用工具。
- 失败时保留原始错误，先判断是工具、认证、PATH 还是 Mayaai Top 适配问题。
- 安装可找、版本可读、任务可跑、配置可回滚、兼容状态准确，才算完成。
你应该看到
测试任务产生可查看的执行记录和 Markdown 产出文件；任何失败都能定位到具体层级。
如果没看到
不要用真实项目反复试错。先回到测试目录独立运行 CLI；独立运行成功后，再检查运行设备和执行 Adapter。
可直接复制
保存这张“装、验、切、接”检查卡
以后每增加一种智能体工具，都按同一顺序留下证据。前一步未通过，就停止进入下一步。
- 装：官方域名、正确系统、命令路径。
- 验：版本、认证、最小任务。
- 切：Provider、生效检查、可回滚。
- 接：本机已安装、Mayaai Top 已发现、Mayaai Top 可执行。
安装前再次核对
官方来源
CLI 安装入口会变化。执行命令前，先打开对应官方页面核对域名、系统要求和最新说明。
完成本教程
你已经得到一套可验证、可恢复的 CLI 工作环境。
以后增加新工具时继续使用“装、验、切、接”：从官方来源安装，验证版本和最小任务，切换配置并保留回滚，再核对 Mayaai Top 的真实支持层级。
常见问题
Codex 和 Claude Code 应该先装哪个？
按当前任务选择。两者都适合工程任务，但账号、模型体验和工作方式不同。第一次只装一种，用真实测试目录完成版本、登录和最小任务，再决定是否增加第二种。
必须使用 API Key 才能运行这些 CLI 吗？
不一定。不同工具支持账号登录、订阅或 API Key 等方式，具体以官方文档和账号资格为准。不要为了统一形式，把原本可用的官方登录强行改成第三方 Key。
CC Switch 可以管理 Kimi Code、Qoder 和 QClaw 吗？
只按 CC Switch 当前官方说明中明确列出的工具配置。没有明确支持时，不要仅因界面可以填写字段就认定兼容。
为什么切换 Provider 后旧终端没有变化？
旧进程可能已经读取了原来的环境变量和配置。关闭旧终端、打开新终端再验证；仍无变化时检查 Shell 环境变量是否覆盖 CC Switch。
Mayaai Top 发现 Hermes 或 Kimi 后为什么不能执行？
发现表示本地助手找到了命令，不代表对应任务 Adapter 已实现。当前教程明确标注产品边界，未适配工具可以继续独立使用。
安装脚本是否安全？
任何远程脚本都需要先核对官方域名、HTTPS、系统要求和最新文档。组织设备还应遵循管理员策略。不要从搜索广告、转载文章或陌生网盘复制安装命令。