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。

Claude Code、Codex、OpenCode 和 Qoder 都可以用 npm 全局安装；Cursor 用官方安装脚本安装；WorkBuddy 只需要安装它的桌面应用。Windows 用户建议使用 PowerShell 或 Windows Terminal。

选择一个 Agent

新手只需要先选一个 Agent，不需要全部安装。

Cursor、Qoder、WorkBuddy 三种 Agent 类型自 RunLogos 1.0.3 起支持。

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。

安装 Cursor CLI

Cursor 的命令行 Agent 叫 Cursor CLI，命令名是 cursor-agent。它和 Cursor 编辑器是两个东西：只装了 Cursor 编辑器，并不等于装好了 Cursor CLI。

macOS 上使用官方安装脚本：

curl https://cursor.com/install -fsS | bash

Windows 用户请按 Cursor 官方文档中的 Windows 安装说明安装 Cursor CLI。

验证命令是否可用：

cursor-agent --version

进入项目根目录后启动：

cd /path/to/your-project
cursor-agent

首次使用时，按终端提示登录 Cursor 账号。

安装 Qoder CLI

Qoder 的命令行 Agent 叫 Qoder CLI，命令名是 qodercli。注意不要和 qoder 混淆：qoder 是 Qoder IDE 的启动入口，不是命令行 Agent。

使用 npm 全局安装：

npm install -g @qoder-ai/qodercli

验证命令是否可用：

qodercli --version

进入项目根目录后启动：

cd /path/to/your-project
qodercli

首次在某个目录启动时，Qoder 会询问「Do you trust the files in this folder?」，需要你本人选择 1. Trust folder，详见下文「首次启动的信任门」。Qoder 目前在 macOS 上支持，Windows 暂未纳入。

安装 WorkBuddy

WorkBuddy 是腾讯的 AI 编程桌面应用，它内置命令行 Agent codebuddy。你只需要安装 WorkBuddy 桌面应用，不需要另外安装 Node.js 或 npm 包：

1. 从 WorkBuddy 官网下载并安装 WorkBuddy 桌面应用，确认它位于「应用程序」目录（/Applications/WorkBuddy.app）。
2. 打开一次 WorkBuddy 完成登录。
3. 在 RunLogos 中新建 WorkBuddy 类型的 Agent，RunLogos 会自动找到应用内置的 codebuddy 并用应用自带的运行时启动它。

如果你已经在 PATH 中安装了 codebuddy 命令，RunLogos 也会直接使用它。

首次在某个目录启动时，WorkBuddy 同样会询问是否信任该目录，需要你本人确认。WorkBuddy 目前只支持 macOS。

与 OpenLogos 配合安装

装好 Agent 只是第一步。要让 Agent 读到 OpenLogos 的规则、Skills 和命令，项目里还要生成对应 Agent 的配置文件。

1. 确认 OpenLogos CLI 版本

RunLogos 1.0.3 要求 OpenLogos CLI ≥ 0.15.16：

openlogos --version

低于该版本时升级：

npm install -g @miniidealab/openlogos@latest

2. 新项目：无需额外操作

用 RunLogos 新建项目或接入存量项目时，RunLogos 会为 OpenLogos 支持的全部 Agent 一次性生成配置，Cursor、Qoder、WorkBuddy 也包括在内。

3. 老项目：补上新 Agent 后同步

如果项目是在升级前初始化的，logos/logos.config.json 里的 aiTool 只记录了当时的 Agent 列表，例如：

"aiTool": ["claude-code", "opencode", "codex", "cursor"]

升级 CLI 并不会自动把新 Agent 加进去。请在数组里补上你要用的 Agent，然后在项目根目录运行同步：

"aiTool": ["claude-code", "opencode", "codex", "cursor", "qoder", "workbuddy"]

cd /path/to/your-project
openlogos sync

可用的取值有 claude-code、opencode、codex、cursor、qoder、workbuddy，也可以写 "all" 表示全部。

4. 同步后生成了什么

同步完成后，请新开一个 Agent 会话，新的插件和 hooks 才会生效。OpenLogos 只管理自己生成的文件，你自己写的 .qoder/settings.json、.workbuddy/settings.json 等配置会原样保留。

5. 首次启动的信任门

Qoder 和 WorkBuddy 首次在某个目录启动时，会显示「Do you trust the files in this folder?」之类的确认：

• 这是正常的中间状态，不是启动失败；
• 需要你本人在 Agent 终端里选择信任，RunLogos 不会替你回答——是否信任一个目录是安全决定；
• Qoder 的免确认模式（RunLogos 新建 Agent 时勾选 Auto-run）只在受信任的目录中生效，未信任前会回到默认的逐项确认。

在 RunLogos 项目中验证 Agent

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

操作

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

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

4. 启动你选择的 Agent，例如 claude、codex、opencode、cursor-agent 或 qodercli（WorkBuddy 直接在 RunLogos 中新建 WorkBuddy 类型的 Agent）。
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 / qodercli 提示 command not found

运行：

npm config get prefix

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

RunLogos 1.0.3 起会读取你的 shell 配置（例如 ~/.zshrc）中的 PATH 查找这些命令。如果终端里能运行、RunLogos 里却提示未安装，请完全退出并重新打开 RunLogos。

cursor-agent 提示 command not found

Cursor CLI 默认安装在 ~/.local/bin。确认该目录在 PATH 中，然后重新打开终端运行 cursor-agent --version。

RunLogos 找不到 WorkBuddy

确认 WorkBuddy 安装在 /Applications/WorkBuddy.app，而不是只放在「下载」目录里直接运行。WorkBuddy 目前只支持 macOS。

Qoder / WorkBuddy 启动后停在信任提示

这是首次进入目录时的正常确认，在 Agent 终端里选择信任即可。确认后再使用 Auto-run 或无人值守驱动。

新 Agent 看不到 OpenLogos 的 Skills 或命令

检查 logos/logos.config.json 的 aiTool 是否包含该 Agent，补上后运行 openlogos sync，再新开一个 Agent 会话。

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 后的步骤继续。