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 或 wget
• jq 或 python3
• tar
• install
• 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

根據嚮導依次完成：

1. 選擇模型提供方。
2. 填入對應憑證。
3. 選擇默認模型。
4. 在最終確認頁檢查後再寫入配置。

不要把 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. 常用命令

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 作為腳本安裝版的必要流程；命令未識別安裝方式時，重新運行同一通道的安裝器。

通道安裝檢查：

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

1. Windows：關閉並重新打開 PowerShell。
2. macOS/Linux：確認 ~/.local/bin 已加入 PATH。
3. 重新運行 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 安裝失敗

優先檢查：

1. 是否使用 beta 渠道。
2. 是否已安裝 jq 或 python3。
3. OpenSSL 是否為 3+，並支持 pkeyutl -rawin。
4. 網絡是否可以訪問 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 文檔 · 概覽 · 可用方式