Agent 安装指南

这篇文档解决一个很常见的问题：RunLogos 已经安装好了，但不知道 Agent 怎么装、怎么启动、怎么和 RunLogos 配合。

本文只使用纯文本说明，不需要截图。你只需要先安装一个可用的 Agent，然后让它在 RunLogos 项目的项目根目录里工作。

先把三个角色分清楚：

• RunLogos 是桌面端工作台，负责打开项目、展示规格链、预览 Markdown 文档和 HTML 原型、查看验收结果。
• OpenLogos CLI 是命令工具，负责初始化项目、创建变更、合并规格、执行 openlogos verify 验收。
• Agent 是 AI 编程助手，负责读取项目规则、询问信息、写规格文档、写测试、写代码和执行命令。

Agent 不是 RunLogos 本体。RunLogos 负责让项目和规格链看得见；Agent 负责按照 AGENTS.md 和 logos/logos-project.yaml 去完成生成、修改和排查工作。它们读写的是同一个本地项目目录。

开始前准备

先确认你的电脑已经安装 Node.js LTS 和 npm。在终端运行：

node --version
npm --version

如果提示 node 或 npm 不存在，请先回到 安装 文档安装 Node.js。

macOS、Linux 和 Windows 都可以使用 npm 全局安装 Agent。Windows 用户建议使用 PowerShell 或 Windows Terminal。

选择一个 Agent

新手只需要先选一个 Agent，不需要三个都安装。

RunLogos 不强绑定某个 Agent。只要这个 Agent 能在项目根目录读取文件、理解 AGENTS.md、执行必要命令，就可以配合 RunLogos 使用。

安装 Claude Code

使用 npm 全局安装：

npm install -g @anthropic-ai/claude-code

验证命令是否可用：

claude --version

进入项目根目录后启动：

cd /path/to/your-project
claude

首次使用时，按 Claude Code 终端提示完成登录、授权或 API Key 配置。

安装 Codex

使用 npm 全局安装：

npm install -g @openai/codex

验证命令是否可用：

codex --version

进入项目根目录后启动：

cd /path/to/your-project
codex

首次使用时，按 Codex 终端提示完成登录、授权或 API Key 配置。

安装 OpenCode

使用 npm 全局安装：

npm install -g opencode-ai

验证命令是否可用：

opencode --version

进入项目根目录后启动：

cd /path/to/your-project
opencode

首次使用时，按 OpenCode 终端提示选择模型 Provider，并配置对应的登录或 API Key。

在 RunLogos 项目中验证 Agent

安装完成后，不要急着让 Agent 写代码。先确认它打开的是正确项目目录。

操作

1. 用 RunLogos 打开已经初始化的项目目录。
2. 在终端进入同一个项目根目录。
3. 确认项目根目录中能看到这些文件：

ls AGENTS.md logos/logos.config.json logos/logos-project.yaml

4. 启动你选择的 Agent，例如 claude、codex 或 opencode。
5. 向 Agent 发送这段验证提示词：

请读取 AGENTS.md 和 logos/logos-project.yaml，告诉我当前项目下一步应该做什么。

预期结果

Agent 应该能说出当前项目阶段、下一步建议，以及需要读取的 Skill。它不应该一上来就直接写代码。

如果 Agent 说找不到 AGENTS.md，几乎一定是目录打开错了。请回到包含 AGENTS.md、logos/logos.config.json 和 logos/logos-project.yaml 的项目根目录后重新启动 Agent。

推荐给小白的最短路径

如果你不确定该怎么选，按下面的顺序走：

1. 安装 RunLogos。
2. 安装 OpenLogos CLI。
3. 安装一个 Agent，例如：

npm install -g @openai/codex

4. 在项目目录运行 openlogos init。
5. 用 RunLogos 打开项目目录。
6. 在终端进入同一个项目根目录并启动 Agent。
7. 发送验证提示词。
8. 回到 快速上手 继续执行。

常见问题排查

npm install -g 失败

先检查网络和 npm 源。如果是权限问题，优先修复 npm 全局目录权限，不建议一上来使用 sudo。

claude / codex / opencode 提示 command not found

运行：

npm config get prefix

确认 npm 全局 bin 目录已经加入 PATH。修改 shell 配置后，重新打开终端再运行 claude --version、codex --version 或 opencode --version。

Windows 安装后找不到命令

确认 %APPDATA%\npm 已加入系统 PATH，然后重新打开 PowerShell 或 Windows Terminal。

Agent 说找不到 AGENTS.md

说明你没有在项目根目录启动 Agent。请先进入包含 AGENTS.md 的目录：

cd /path/to/your-project

不要只打开 src/、src-tauri/ 或 logos/ 子目录。

Agent 只看到 src/，看不到 logos/

说明打开了子目录。请打开仓库根目录，也就是同时包含业务代码、AGENTS.md 和 logos/ 的目录。

Agent 不知道 RunLogos / OpenLogos

先发送验证提示词，让它读取 AGENTS.md 和 logos/logos-project.yaml。Agent 不需要控制 RunLogos 桌面端，它只需要理解项目文件和 OpenLogos 规则。

Agent 直接开始写代码

要求它停止，并按当前 Phase 读取对应 Skill。设计文档完成前，不应该直接进入代码实现。

可以这样说：

请先读取 AGENTS.md，判断当前 Phase，并按对应 Skill 的步骤执行。不要直接写代码。

Agent 提示没有模型权限或 API Key

进入对应 Agent 的登录、订阅或 API Key 配置流程。RunLogos 不托管第三方 Agent 的账号权限，也不会替你自动开通模型权限。

RunLogos 里看不到 Agent 刚生成的文档

确认 RunLogos 和 Agent 打开的是同一个本地项目目录，然后刷新 RunLogos 项目树。

下一步

安装并验证 Agent 后，返回 快速上手，从连接 Agent 后的步骤继续。