# EOS CLI：安装、配置与运行

EOS CLI 在终端中运行 AI 任务。使用自己的模型服务时，需要供应商的 API 地址、密钥与模型名称。

## 安装

从 [EOS CLI 产品页](https://eosaios.com/zh/products/cli/) 或 [官方仓库](https://github.com/eosaios/eos) 获取适合系统与架构的版本。

macOS / Linux 官方安装入口：

```bash
curl -fsSL https://cdn.jsdelivr.net/gh/eosaios/eos@main/scripts/install.sh | bash
```

Windows PowerShell：

```powershell
irm https://cdn.jsdelivr.net/gh/eosaios/eos@main/scripts/install.ps1 | iex
```

安装脚本会下载并执行程序，可以先下载查看脚本内容。安装后重新打开终端，运行 `eos version` 检查命令是否在 PATH 中。更新使用 `eos update`；版本与渠道以命令显示和官方发布页为准，不把示例版本号当作当前最新版本。

## 配置模型

首次运行 `eos` 可以按照引导设置。环境变量方式适合临时会话或 CI，下面是占位示例，需替换为自己的供应商信息：

```bash
export EOS_API_BASE='https://provider.example/v1'
export EOS_API_KEY='YOUR_API_KEY'
export EOS_MODEL='YOUR_MODEL_ID'
eos
```

Windows PowerShell 使用 `$env:EOS_API_BASE`、`$env:EOS_API_KEY` 和 `$env:EOS_MODEL` 设置对应变量。不要提交包含真实密钥的脚本或配置。持久配置使用用户目录的 `.eos.json`；日常通过交互界面管理模型，可避免手工编辑错字段。

## 交互任务

在目标目录运行 `eos`，输入问题或任务。在界面中使用 `/model` 切换模型，`/status` 查看状态，`/workspace` 检查工作目录，`/mcp` 管理 MCP 连接。输入 `?` 查看当前版本快捷键。

先让工具解释计划，再授权修改或执行。模型输出、工具审批与运行结果应分别检查；成功退出并不保证业务需求已经实现。

## 单次输出与自动化

```bash
eos --print '说明当前项目如何运行，不要修改文件' --output-format json
```

`--print` 执行单次任务，`--output-format` 可选 `text`、`json`、`stream-json`。需要限制工具时使用 `--allowed-tools` 与 `--disallowed-tools`（名称以当前版本帮助为准，多个名称用逗号分隔）。用 `eos --help` 核对命令，不使用过时或臆造的工具名。

继续最近会话可用 `eos --continue`，选择已有会话可用 `eos --resume <session-id>`。自动化前确认工作目录、模型额度、工具权限与退出状态；将真实密钥保存在 CI 的秘密变量中。

## 故障定位

- 找不到命令：重开终端，检查安装目录是否在 PATH。
- 鉴权失败：检查供应商 API 地址、密钥权限、余额与模型 ID。
- 工具无法运行：核对本机运行时、文件权限与允许的工具。
- 上报问题：附版本、系统、去除密钥后的报错和最小复现步骤；不要公开完整配置或会话中的私人文件。