EvoX CLI Quickstart

从终端使用 EvoX 的安装与入门指南。

本页介绍 EvoMap/evox 仓库产出的 EvoX CLI，也就是终端中的 evox 命令。它不是通过 npm 安装的 @evomap/evolver，后者属于独立的 Evolver CLI；两者的安装方式、配置目录和命令名都不同。

1. EvoX CLI 是什么

EvoX CLI 是运行在终端中的 AI 编码助手。它可以读取项目文件、执行命令、修改代码，并支持交互式 TUI、一次性任务、会话续接、Gateway 和扩展等能力。

2. 五分钟跑通

第一步：安装

macOS

在 Terminal 中运行：

bash

curl -fsSL https://evomap.ai/evox/install.sh | EVOX_CHANNEL=beta sh

Linux

安装前需要具备：

curl 或 wget
jq 或 python3
tar
install
OpenSSL 3+，并支持 pkeyutl -rawin

然后运行：

bash

curl -fsSL https://evomap.ai/evox/install.sh | EVOX_CHANNEL=beta sh

线上安装脚本会自动识别 Linux，并切换到 Linux 专用发布源。

Windows

打开 PowerShell，运行：

powershell

$env:EVOX_CHANNEL = 'beta'
irm https://evomap.ai/evox/install.ps1 | iex

安装脚本会把 EvoX CLI 安装到：

text

%LOCALAPPDATA%\EvoX\bin\evox.exe

脚本会把该目录加入当前用户的 PATH。安装完成后请关闭并重新打开 PowerShell，再继续下一步。

第二步：确认命令可用

bash

evox --version
evox --help

成功时，evox --version 会返回类似下面的版本信息：

text

evox v1.1.0-beta.26 (...)

具体版本会随发布更新，不要求和示例完全一致。

如果 macOS 或 Linux 提示 evox: command not found，先在当前终端运行：

bash

export PATH="$HOME/.local/bin:$PATH"

随后把同一行加入 ~/.zshrc、~/.bashrc 或团队使用的 Shell 配置文件，避免下次打开终端后再次丢失。

第三步：配置模型

首次使用推荐只配置模型，不进入 Gateway 和自进化的高级设置：

bash

evox configure quick

根据向导依次完成：

选择模型提供方。
填入对应凭证。
选择默认模型。
在最终确认页检查后再写入配置。

不要把 API Key、Token 或其他凭证发到聊天、Issue、截图或日志附件中。也不建议把密钥直接写在 --api-key 命令参数里，以免进入 Shell 历史记录。

查看当前实际配置文件位置：

bash

evox config path

查看配置摘要，敏感项会被遮蔽：

bash

evox config list

第四步：运行健康检查

bash

evox doctor

ok 表示检查通过，skip 通常表示该可选能力未启用。出现 warn 时应阅读提示，但不代表所有情况下都无法继续使用。

只查看告警和失败项：

bash

evox doctor --quiet

第五步：在项目中完成第一次只读任务

先进入要处理的项目目录：

bash

cd /path/to/your/project

Windows PowerShell 也可以使用：

powershell

Set-Location 'C:\path\to\your\project'

建议第一次先使用只读工具完成验证：

bash

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. 日常使用

交互式终端界面

bash

evox tui

进入 TUI 后可以持续对话，并使用模型选择器和会话历史。需要 EvoX 修改文件或执行命令时，应先确认当前目录就是目标项目。

执行一次性任务

bash

evox -p "Summarize this repository and identify the safest next implementation step."

任务完成后 CLI 会退出，适合脚本、CI 前置分析或简单检查。

附带文件提问

bash

evox -p @README.md "Summarize the setup steps and list anything missing."

继续上一段会话

bash

evox --continue -p "Continue from the previous result and propose tests."

指定模型

bash

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：

bash

evox configure channels

启动并检查状态：

bash

evox gateway start
evox gateway status

默认本地地址：

text

http://127.0.0.1:9700/

停止 Gateway：

bash

evox gateway stop

默认绑定为本机回环地址。不要在没有完成认证和网络边界确认的情况下，把 Gateway 暴露到公网。

6. 当前版本需要注意的限制

`evox start` 不是当前主流程

在已核验的 Beta 构建中，后台 daemon bridge 尚未接通。运行 evox start 会提示没有可启动的后台会话服务。

当前应使用：

bash

evox tui

或：

bash

evox -p "<prompt>"

evox gateway start 是另一套独立入口，不等同于 evox start。

远程 package 管理尚未开放

当前构建中的 evox package 仍显示为不可用。不要把它写入 Partner 的必要接入步骤。需要本地扩展开发时，可另行使用 evox ext ... 工作流。

7. 更新和渠道切换

通过上述安装脚本安装后，最稳妥的更新方式是重新运行同一条安装命令。安装器会重新读取渠道清单、下载当前构建并校验 SHA-256。

Beta 更新：

bash

curl -fsSL https://evomap.ai/evox/install.sh | EVOX_CHANNEL=beta sh

Windows：

powershell

$env:EVOX_CHANNEL = 'beta'
irm https://evomap.ai/evox/install.ps1 | iex

不要把 evox self-update 作为脚本安装版的必要流程；当前构建可能无法识别这种安装方式，并提示重新使用对应安装渠道。

渠道状态（核验于 2026-09-24）：

平台	Beta	Stable
macOS	可用	可用
Windows	可用	可用
Linux	可用	当前发布源返回 404，暂不要切换

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。

提示没有模型凭证

重新运行：

bash

evox configure quick

确认选择的模型提供方与凭证匹配。不要在公开消息中粘贴凭证原文。

能启动但任务失败

依次收集：

bash

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 文档 · 概览 · 可用方式

EvoX CLI Quickstart

从终端使用 EvoX 的安装与入门指南。

1. EvoX CLI 是什么

EvoX CLI 是运行在终端中的 AI 编码助手。它可以读取项目文件、执行命令、修改代码，并支持交互式 TUI、一次性任务、会话续接、Gateway 和扩展等能力。

2. 五分钟跑通

第一步：安装

macOS

在 Terminal 中运行：

bash

curl -fsSL https://evomap.ai/evox/install.sh | EVOX_CHANNEL=beta sh

Linux

安装前需要具备：

curl 或 wget
jq 或 python3
tar
install
OpenSSL 3+，并支持 pkeyutl -rawin

然后运行：

bash

curl -fsSL https://evomap.ai/evox/install.sh | EVOX_CHANNEL=beta sh

线上安装脚本会自动识别 Linux，并切换到 Linux 专用发布源。

Windows

打开 PowerShell，运行：

powershell

$env:EVOX_CHANNEL = 'beta'
irm https://evomap.ai/evox/install.ps1 | iex

安装脚本会把 EvoX CLI 安装到：

text

%LOCALAPPDATA%\EvoX\bin\evox.exe

脚本会把该目录加入当前用户的 PATH。安装完成后请关闭并重新打开 PowerShell，再继续下一步。

第二步：确认命令可用

bash

evox --version
evox --help

成功时，evox --version 会返回类似下面的版本信息：

text

evox v1.1.0-beta.26 (...)

具体版本会随发布更新，不要求和示例完全一致。

如果 macOS 或 Linux 提示 evox: command not found，先在当前终端运行：

bash

export PATH="$HOME/.local/bin:$PATH"

随后把同一行加入 ~/.zshrc、~/.bashrc 或团队使用的 Shell 配置文件，避免下次打开终端后再次丢失。

第三步：配置模型

首次使用推荐只配置模型，不进入 Gateway 和自进化的高级设置：

bash

evox configure quick

根据向导依次完成：

选择模型提供方。
填入对应凭证。
选择默认模型。
在最终确认页检查后再写入配置。

不要把 API Key、Token 或其他凭证发到聊天、Issue、截图或日志附件中。也不建议把密钥直接写在 --api-key 命令参数里，以免进入 Shell 历史记录。

查看当前实际配置文件位置：

bash

evox config path

查看配置摘要，敏感项会被遮蔽：

bash

evox config list

第四步：运行健康检查

bash

evox doctor

ok 表示检查通过，skip 通常表示该可选能力未启用。出现 warn 时应阅读提示，但不代表所有情况下都无法继续使用。

只查看告警和失败项：

bash

evox doctor --quiet

第五步：在项目中完成第一次只读任务

先进入要处理的项目目录：

bash

cd /path/to/your/project

Windows PowerShell 也可以使用：

powershell

Set-Location 'C:\path\to\your\project'

建议第一次先使用只读工具完成验证：

bash

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 能返回当前项目的结构和测试方式，说明安装、模型配置、网络和项目读取链路已经跑通。

3. 日常使用

交互式终端界面

bash

evox tui

进入 TUI 后可以持续对话，并使用模型选择器和会话历史。需要 EvoX 修改文件或执行命令时，应先确认当前目录就是目标项目。

执行一次性任务

bash

evox -p "Summarize this repository and identify the safest next implementation step."

任务完成后 CLI 会退出，适合脚本、CI 前置分析或简单检查。

附带文件提问

bash

evox -p @README.md "Summarize the setup steps and list anything missing."

继续上一段会话

bash

evox --continue -p "Continue from the previous result and propose tests."

指定模型

bash

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：

bash

evox configure channels

启动并检查状态：

bash

evox gateway start
evox gateway status

默认本地地址：

text

http://127.0.0.1:9700/

停止 Gateway：

bash

evox gateway stop

默认绑定为本机回环地址。不要在没有完成认证和网络边界确认的情况下，把 Gateway 暴露到公网。

6. 当前版本需要注意的限制

`evox start` 不是当前主流程

在已核验的 Beta 构建中，后台 daemon bridge 尚未接通。运行 evox start 会提示没有可启动的后台会话服务。

当前应使用：

bash

evox tui

或：

bash

evox -p "<prompt>"

evox gateway start 是另一套独立入口，不等同于 evox start。

远程 package 管理尚未开放

当前构建中的 evox package 仍显示为不可用。不要把它写入 Partner 的必要接入步骤。需要本地扩展开发时，可另行使用 evox ext ... 工作流。

7. 更新和渠道切换

通过上述安装脚本安装后，最稳妥的更新方式是重新运行同一条安装命令。安装器会重新读取渠道清单、下载当前构建并校验 SHA-256。

Beta 更新：

bash

curl -fsSL https://evomap.ai/evox/install.sh | EVOX_CHANNEL=beta sh

Windows：

powershell

$env:EVOX_CHANNEL = 'beta'
irm https://evomap.ai/evox/install.ps1 | iex

不要把 evox self-update 作为脚本安装版的必要流程；当前构建可能无法识别这种安装方式，并提示重新使用对应安装渠道。

渠道状态（核验于 2026-09-24）：

平台	Beta	Stable
macOS	可用	可用
Windows	可用	可用
Linux	可用	当前发布源返回 404，暂不要切换

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。

提示没有模型凭证

重新运行：

bash

evox configure quick

确认选择的模型提供方与凭证匹配。不要在公开消息中粘贴凭证原文。

能启动但任务失败

依次收集：

bash

evox --version
evox doctor --quiet
evox logs --list
evox logs --errors -n 100

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 文档 · 概览 · 可用方式

EvoX CLI Quickstart

1. EvoX CLI 是什么

2. 五分钟跑通

第一步：安装

macOS

Linux

Windows

第二步：确认命令可用

第三步：配置模型

第四步：运行健康检查

第五步：在项目中完成第一次只读任务

3. 日常使用

交互式终端界面

执行一次性任务

附带文件提问

继续上一段会话

指定模型

4. 常用命令

5. 可选：启动本地 Gateway

6. 当前版本需要注意的限制

evox start 不是当前主流程

远程 package 管理尚未开放

7. 更新和渠道切换

8. 卸载

9. 常见问题

安装后找不到 evox

提示没有模型凭证

能启动但任务失败

Linux 安装失败

10. 向项目组反馈问题时请提供

EvoX CLI Quickstart

1. EvoX CLI 是什么

2. 五分钟跑通

第一步：安装

macOS

Linux

Windows

第二步：确认命令可用

第三步：配置模型

第四步：运行健康检查

第五步：在项目中完成第一次只读任务

3. 日常使用

交互式终端界面

执行一次性任务

附带文件提问

继续上一段会话

指定模型

4. 常用命令

5. 可选：启动本地 Gateway

6. 当前版本需要注意的限制

evox start 不是当前主流程

远程 package 管理尚未开放

7. 更新和渠道切换

8. 卸载

9. 常见问题

安装后找不到 evox

提示没有模型凭证

能启动但任务失败

Linux 安装失败

10. 向项目组反馈问题时请提供

`evox start` 不是当前主流程

安装后找不到 `evox`

`evox start` 不是当前主流程

安装后找不到 `evox`