EvoX CLI
通过官方通道安装器安装 EvoX CLI，再用
evox --help查看命令入口。
从终端使用 EvoX 的安装与入门指南。
本页介绍 EvoMap/evox 仓库产出的 EvoX CLI，也就是终端中的 evox 命令。它不是通过 npm 安装的 @evomap/evolver，后者属于独立的 Evolver CLI；两者的安装方式、配置目录和命令名都不同。
1. EvoX CLI 是什么
EvoX CLI 是运行在终端中的 AI 编码助手。它可以读取项目文件、执行命令、修改代码，并支持交互式 TUI、一次性任务、会话续接、Gateway 和扩展等能力。
2. 五分钟跑通
第一步：安装
macOS
在 Terminal 中运行：
curl -fsSL https://evomap.ai/evox/install.sh | EVOX_CHANNEL=beta sh
Linux
安装前需要具备：
curl或wgetjq或python3tarinstall- OpenSSL 3+，并支持
pkeyutl -rawin
然后运行：
curl -fsSL https://evomap.ai/evox/install.sh | EVOX_CHANNEL=beta sh
线上安装脚本会自动识别 Linux，并切换到 Linux 专用发布源。
Windows
打开 PowerShell，运行：
$env:EVOX_CHANNEL = 'beta'
irm https://evomap.ai/evox/install.ps1 | iex
安装脚本会把 EvoX CLI 安装到：
%LOCALAPPDATA%\EvoX\bin\evox.exe
脚本会把该目录加入当前用户的 PATH。安装完成后请关闭并重新打开 PowerShell，再继续下一步。
第二步：确认命令可用
evox --version
evox --help
成功时，evox --version 会返回类似下面的版本信息：
evox v1.1.0-beta.26 (...)
具体版本会随发布更新，不要求和示例完全一致。
如果 macOS 或 Linux 提示 evox: command not found，先在当前终端运行：
export PATH="$HOME/.local/bin:$PATH"
随后把同一行加入 ~/.zshrc、~/.bashrc 或团队使用的 Shell 配置文件，避免下次打开终端后再次丢失。
第三步：配置模型
首次使用推荐只配置模型，不进入 Gateway 和自进化的高级设置：
evox configure quick
根据向导依次完成：
- 选择模型提供方。
- 填入对应凭证。
- 选择默认模型。
- 在最终确认页检查后再写入配置。
不要把 API Key、Token 或其他凭证发到聊天、Issue、截图或日志附件中。也不建议把密钥直接写在 --api-key 命令参数里，以免进入 Shell 历史记录。
查看当前实际配置文件位置：
evox config path
查看配置摘要，敏感项会被遮蔽：
evox config list
第四步：运行健康检查
evox doctor
ok 表示检查通过，出现 skip 时阅读附带原因，并检查该能力是否属于任务要求。出现 warn 时应阅读提示，但不代表所有情况下都无法继续使用。
只查看告警和失败项：
evox doctor --quiet
第五步：在项目中完成第一次只读任务
先进入要处理的项目目录：
cd /path/to/your/project
Windows PowerShell 也可以使用：
Set-Location 'C:\path\to\your\project'
建议第一次先使用只读工具完成验证：
evox --tools read,grep,find,ls -p "Read this repository and return: 1) the main language and framework; 2) the entry point; 3) how to run tests. Do not modify files."
如果 EvoX 能返回当前项目的结构和测试方式，说明安装、模型配置、网络和项目读取链路已经跑通。
如果出现 PermissionDenied、prompt WAL 或无法写入 agent 目录的错误，先不要反复重试；运行 evox config path，检查该目录及其父目录是否对当前用户可写，再把脱敏后的错误信息交给项目联系人。
3. 日常使用
交互式终端界面
evox tui
进入 TUI 后可以持续对话，并使用模型选择器和会话历史。需要 EvoX 修改文件或执行命令时，应先确认当前目录就是目标项目。
执行一次性任务
evox -p "Summarize this repository and identify the safest next implementation step."
任务完成后 CLI 会退出，适合脚本、CI 前置分析或简单检查。
附带文件提问
evox -p @README.md "Summarize the setup steps and list anything missing."
继续上一段会话
evox --continue -p "Continue from the previous result and propose tests."
指定模型
evox --model <provider>/<model> -p "Review this change."
<provider>/<model> 应替换成团队允许使用、且已配置凭证的真实模型标识。
4. 常用命令
| 目的 | 命令 |
|---|---|
| 查看版本 | evox --version |
| 查看完整帮助 | evox --help |
| 快速配置模型 | evox configure quick |
| 完整配置模型、Channels 和 Gene | evox configure full |
| 只修改模型 | evox configure model |
| 查看配置路径 | evox config path |
| 查看脱敏后的配置摘要 | evox config list |
| 环境健康检查 | evox doctor |
| 交互式使用 | evox tui |
| 一次性任务 | evox -p "<prompt>" |
| 查看错误日志 | evox logs --errors -n 100 |
| 查看当天最近日志 | evox logs -n 100 |
5. 可选：启动本地 Gateway
Gateway 提供入站连接能力和本地浏览器管理/聊天界面。只需要终端编码助手时，可以跳过本节。
先配置 Channels 和 Gateway：
evox configure channels
启动并检查状态：
evox gateway start
evox gateway status
默认本地地址：
http://127.0.0.1:9700/
停止 Gateway：
evox gateway stop
默认绑定为本机回环地址。不要在没有完成认证和网络边界确认的情况下，把 Gateway 暴露到公网。
6. 命令入口与错误处理
处理 evox start 的后台服务错误
运行 evox start 提示没有可启动的后台会话服务时，改用交互入口或单次任务入口。
使用以下入口：
evox tui
或：
evox -p "<prompt>"
evox gateway start 是另一套独立入口，不等同于 evox start。
包管理与本地扩展
evox package 提示包管理不可用时，不要把它写入 Partner 的必要接入步骤。本地扩展开发使用独立的 evox ext ... 工作流。
7. 更新和渠道切换
通过上述安装脚本安装后，最稳妥的更新方式是重新运行同一条安装命令。安装器会重新读取渠道清单、下载当前构建并校验 SHA-256。
Beta 更新：
curl -fsSL https://evomap.ai/evox/install.sh | EVOX_CHANNEL=beta sh
Windows：
$env:EVOX_CHANNEL = 'beta'
irm https://evomap.ai/evox/install.ps1 | iex
不要把 evox self-update 作为脚本安装版的必要流程；命令未识别安装方式时，重新运行同一通道的安装器。
通道安装检查：
| 平台 | Beta | Stable |
|---|---|---|
| macOS | 使用 Beta 安装器 | 使用 Stable 安装器 |
| Windows | 使用 Beta 安装器 | 使用 Stable 安装器 |
| Linux | 首次安装使用 Beta 安装器 | 安装前核对 Linux Stable 清单与对应架构资产；404 时停止安装 |
Linux 首次安装按上文 Beta 流程操作，先确认 Beta 清单包含当前架构的资产。切换到 Stable 前，先确认 Linux Stable 清单及目标文件可用；清单或下载返回 404 时停止，不把其他平台的文件当作替代。已有安装保留原有二进制与通道，不先卸载；首次安装没有可保留的版本，应使用已核对资产的 Beta 通道或等待所需通道发布。不得关闭摘要或签名校验绕过下载问题。
8. 卸载
当前 CLI 帮助中没有独立的 uninstall 子命令。
- macOS/Linux 的可执行文件默认位于
~/.local/bin/evox。 - Windows 的可执行文件默认位于
%LOCALAPPDATA%\EvoX\bin\evox.exe。 - 通过
evox config path定位配置目录，再定位会话与日志目录。
仅移除可执行文件不会自动清除用户数据。除非已经备份并明确需要彻底清除，否则不要删除整个 EvoX 数据目录。
9. 常见问题
安装后找不到 evox
- Windows：关闭并重新打开 PowerShell。
- macOS/Linux：确认
~/.local/bin已加入PATH。 - 重新运行
evox --version。
提示没有模型凭证
重新运行：
evox configure quick
确认选择的模型提供方与凭证匹配。不要在公开消息中粘贴凭证原文。
能启动但任务失败
依次收集：
evox --version
evox doctor --quiet
evox logs --list
evox logs --errors -n 100
如果 evox logs --errors 提示没有对应日志文件，先提供 evox logs --list 的结果即可。检查所有输出中是否包含密钥、Token、私有仓库地址、用户名或本地敏感路径，脱敏后再发送给项目联系人。
Linux 安装失败
优先检查：
- 是否使用
beta渠道。 - 是否已安装
jq或python3。 - OpenSSL 是否为 3+，并支持
pkeyutl -rawin。 - 网络是否可以访问
evomap.ai和res.evomap.ai。
10. 向项目组反馈问题时请提供
- 操作系统和 CPU 架构。
evox --version输出。- 使用的渠道：
beta或stable。 - 执行的命令和完整错误文本。
- 脱敏后的
evox doctor --quiet输出。 - 必要时附上脱敏后的
evox logs --errors -n 100输出。 - 说明问题发生在安装、配置、TUI、一次性任务还是 Gateway。
不要提供 API Key、Token、密码、授权码或未脱敏的配置文件。
EvoX 文档 · 概览 · 可用方式