最后核对

官方资料最后核对日期：2026-06-19。本文依据 RunNode changelog 整理，仅提供中文摘要和阅读索引；功能开放范围、账号计划、地区限制、模型可用性与版本号，请以官方原文为准。

本页用于快速了解 RunNode 近期变化，涵盖桌面 App、移动端、CLI、模型、插件、权限与远程控制等内容。为保持阅读清晰，本文自 2025 年起整理，并不逐项搬运官方 GitHub PR 清单。

手动配置

下一步：用 RunNode 完成第一个任务

这篇案例面向医护人员、研究生、规培医生和医学科研初学者，演示如何让 RunNode 帮你把一个医学研究问题整理成可复核的文献工作台。它不替你诊断患者，也不替你下治疗决策；它只帮助你做研究辅助、资料整理和写作准备。

适合什么场景

• 准备综述、开题报告或课题背景。
• 想把几篇论文整理成证据表。
• 想检查文献总结里有没有过度推断。
• 想把医学问题转成 PICO 或 PICOS 框架。
• 想给团队留下可追踪的文献阅读记录。

不适合的场景：

• 让 RunNode 直接给某个患者诊断或治疗方案。
• 让 RunNode 编造 PMID、DOI、指南或随机对照试验。
• 让 RunNode 处理未脱敏的真实病历。
• 把模型输出当成最终医学结论。

推荐目录结构

先在本地建一个小型资料夹，例如：

literature-review-demo/
├─ question.md
├─ papers/
│  ├─ paper-01.md
│  ├─ paper-02.md
│  └─ paper-03.md
├─ evidence-table.md
├─ gaps-and-risks.md
└─ summary-draft.md

每篇论文可以先放结构化笔记，不需要一开始就很完美：

# Paper 01

Title:
Year:
Study type:
Population:
Intervention or exposure:
Comparator:
Outcome:
Key result:
Limitations:
PMID or DOI:

第一步：把问题拆成 PICO

先在 question.md 写下研究问题：

# Research question

在成人 2 型糖尿病患者中，连续葡萄糖监测是否能改善血糖控制和低血糖风险？

然后让 RunNode 帮你拆解：

请只读取 question.md。

任务：
1. 把这个医学研究问题拆成 PICO。
2. 标出哪些信息还不明确。
3. 不要给临床建议。
4. 输出到 question.md 的 “PICO draft” 小节。

比较好的输出应该像这样：

| 元素 | 内容 | 需要补充 |
|

最后核对

官方资料最后核对日期：2026-06-13。下载地址与安装方式以 RunNode 产品页为准，不同地区和账号套餐下可用功能可能有所差异。

本教程里说的 RunNode 桌面应用，是电脑上的客户端，不是手机 App。它由 RunNode 官方发布，支持 macOS 和 Windows，安装后你可以在本地管理项目、发起任务、使用 Skills 和 Automations。

下载

打开 desktop.runnode.ai，页面中央会显示对应系统的下载按钮。

macOS：

点击「Download for macOS」下载 .dmg 安装包。

1. 打开下载好的 .dmg 文件
2. 把 RunNode 图标拖进「Applications（应用程序）」文件夹
3. 首次启动时，macOS 可能弹出「无法验证开发者」——无需担心，打开「系统设置 → 隐私与安全性」，点击「仍要打开」即可

Windows：

Windows 用户点击对应的下载按钮，下载完成后运行安装程序，按提示完成安装。

登录

安装完成后打开 App，使用 ChatGPT / RunNode 账号登录。

安装后验证

登录成功后，左侧栏会出现「Projects」和「Chats」两个入口，顶部显示当前账号信息。如果界面正常加载，说明安装成功。

下一步：订阅 RunNode Pro / Pro

最后核对

官方资料最后核对日期：2026-06-13。定价与套餐以 RunNode 定价页为准。

为什么需要订阅

免费版 ChatGPT 可以体验基础对话，但 RunNode 功能（包括桌面 App、Cloud 任务、多 agent 并行）需要付费套餐才能稳定使用。

| 套餐 | 月费（美元） | RunNode 可用情况 |
|

最后核对

官方资料最后核对日期：2026-06-13。本章参考 RunNode docs等官方资料。界面说明以当前 RunNode 桌面应用 实际版本为准，不同系统、地区、客户端版本和账号套餐下显示可能略有差异。

认识对话和项目

打开 RunNode，左侧栏就两个入口：Chat（对话） 和 Project（项目）。

Chat 对话

和 ChatGPT 网页版差不多，随手问问题。各对话互不相干，也不共享文件夹。

Project 项目

需要动本地文件时用它——写代码、改文档、做 PPT 都可以。项目里的所有对话共用同一个文件夹，方便一起管理。

在项目里下达指令后，RunNode 的修改会直接应用到你本地文件夹中的文件。

对话框功能说明

RunNode 的对话框和 ChatGPT 网页版类似，支持：

1. 添加上下文：可以附加文件、截图或其他参考内容
2. 切换模型：在不同模型之间切换
3. 控制权限：设定 RunNode 在当前任务中的操作权限

插件与技能

包括 RunNode 官方定制或推荐的插件与技能。

Skills 默认包含 Skills Creator、Skills Installer、RunNode Docs 等技能，用来创建、安装技能，或获取 RunNode 官方最新文档。在对话框中使用 $ 即可调用 Skills：

插件是 RunNode 定义的外部工具入口，也可能包含 Skills、MCP、脚本等能力。常见插件包括 Computer Use、Browser Use、PPT、Docs、Excel、Slack、GitHub 等。不同插件可能有额外配置。

设置面板

点击左下角头像或设置图标可以打开设置面板。

左侧是设置菜单。里面包含丰富的配置选项，详情如下：

设置说明

大部分情况下都是保持默认配置即可。配置很多时候都是按需开启。

个人

集成

编码

已归档

下一步：用手机端 RunNode 跟进桌面任务

最后核对

官方资料最后核对日期：2026-05-27。本章以开发一个简单网页为例，演示从创建工作目录到任务迭代的完整操作流程。

本章以"用 RunNode 桌面应用 开发一个关于 AI 发展历史的简单网页"为例，走完一次完整的任务闭环，帮助你快速上手 RunNode 桌面应用 的基本用法。

第一步：输入任务描述，开始执行

在对话框中输入你的需求，点击发送，RunNode 就会开始执行任务。

任务完成后，RunNode 会在对话中展示结果，同时将生成的文件写入工作目录。

如果生成的是网页文件，手动打开文件夹。

第五步：逐步迭代

对结果不满意时，直接在当前对话框中继续描述修改需求，RunNode 会在已有基础上进行调整。

随着对话轮次增加，上下文窗口会逐渐被填满。点击对话框右下角的小圆圈图标，可以查看当前上下文使用情况。

我们使用runnode开发obsidian新手教程网站作为示例：来说明任务的顺序执行管理和并行操作

1.顺序执行

点击创建新的对话。

我们向 runnode 发送任务，让他帮我们设计一个网站，这个时候他就会开始执行。

在这个任务没有执行的过程中，如果我们去给他下达新的命令，就只能等待。显示的是下面这种情况：

这种相当于当前他正在执行一个任务，我们给他的另外两个命令就需要排队，必须等前面的任务执行完成之后才能执行。

但是如果我们想修改一下要求，比如想让他明确这个网站的背景风格为“手绘风格”，如果等他设计完成之后再去修改就会比较麻烦。我希望他在正在设计的时候就知道我的风格要求。

这时候，我们可以点击引导选项。这样操作后，他就会执行一个“插队”的操作：

1. 原本的任务顺序：
   (a) 执行网站设计
   (b) 介绍技术选型
   (c) 执行手绘风格要求（原定第三个任务）

2. 插队后的效果：
   我们想让“手绘风格”在设计过程中就发挥作用，通过点击引导提示，这个任务就会直接插队到当前正在执行的任务当中。

这实际上就是通过这样一个过程，演示如何对顺序执行的任务进行管理以及相关的插队操作。

2.如何并行

实际上就是一个项目（Project）里面，我们同时去执行多个任务。

这个时候，我们只需要在左侧边栏点击“新建对话”就可以了。这样的话，它的几个任务就会并行执行，互不干扰。

这个宠物最大的价值在于状态的可视化：

1. 任务进度一目了然： 不用一直切换回 RunNode 的界面，就能看到当前任务的进度。
2. 实时状态反馈：
   • 它会在 RunNode 忙碌的时候显示忙碌的画面。
   • 在需要你确认的时候会发出提醒。
   • 任务完成之后，它也会让你知道可以去检查结果了。

对有编程经验的人来说，解决方法有很多——GitHub Pages、Vercel、Cloudflare Pages——但这些工具对普通用户并不友好：什么是分支？什么是部署？什么是域名解析？

本篇介绍一个对新手极其友好的工具：DKFile。

Draw.io 就是一个非常好的工具。它可以用来绘制：

1. 流程图
2. 架构图
3. 思维导图
4. 系统设计图
5. 业务流程图
6. 技术路线图

很多程序员、产品经理、架构师都会用它来表达复杂系统之间的关系。前段时间，Draw.io 官方发布了自己的 MCP。

GitHub 地址：https://github.com/jgraph/drawio-mcp

本章节介绍如何使用 RunNode 安装、使用 Draw.io 的 MCP 工具，去绘制信息图或架构图。

如果你的团队或个人经常使用飞书，那么接入飞书 CLI 之后，你就拥有了一种全新的使用方式——在 RunNode 里一句话处理飞书里的所有信息和数据。

本篇介绍如何把 RunNode 和飞书 CLI 结合，直接通过自然语言操作飞书中存储的数据和内容。

演示用的是一个购物车项目。

1. Remotion：使用 React 写视频
2. HyperFrames：使用 HTML、CSS 或 JS 做视频

如果你想做一些轻量化的视频，比如网页转视频、文档转视频等，那么使用 HyperFrames 就是一个非常不错的选择。

像 RunNode 这类编程类的 Agent，不仅能够编写和修改代码，还能够打开网页，像人一样检查页面是否跑通。

本章节使用命令行的方式，来学习 MCP 的安装和使用。

适用场景

• 你已经找到一个想用的社区 Skill。
• 你想让 RunNode 帮你完成安装，而不是手动整理目录和文件。
• 你希望安装后立刻用一个真实任务验证它是否可用。

准备一个 Skill 来源

首先要有这个 Skill 的来源地址。很多开发者会把自己做好的 Skill 放在 GitHub 仓库里，供其他人安装和复用。

这个案例里使用的是一个社区 PPT Skill：

guizang-ppt-skill

第一步：安装

你可以把 Skill 仓库地址交给 RunNode，请它协助识别并完成安装流程。

例如：

请帮我安装这个 Skill：https://github.com/op7418/guizang-ppt-skill
安装完成后，告诉我它的用途、依赖要求，以及应该如何调用。

不同工作区里，安装方式可能不完全一样。有些会直接支持安装，有些则会先分析仓库结构，再提示你确认放置位置或依赖要求。

第二步：调用使用

安装完成后，可以直接让 RunNode 调用这个 Skill 去完成一项真实任务。

如果这个 Skill 已经提前安装过，你通常也可以通过斜杠命令、技能选择器，或者在任务里明确点名的方式来调用它。

例如：

请使用刚刚安装的 PPT Skill，根据“AI 编程工具入门”这个主题生成一份适合分享的演示稿。先告诉我还缺哪些关键信息。

如果你没有给足上下文，RunNode 往往会先回到这个 Skill 的操作手册里，看看它需要什么输入，然后再向你追问必要信息。

当你补齐背景、主题、受众或风格要求后，它会按该 Skill 的流程去读取 README、模板和相关文档，再生成结果。

如果这个 Skill 的默认产物是 HTML 演示稿，直接在浏览器里打开预览。

你要重点检查什么

• RunNode 安装的是不是你指定的那个 Skill，而不是名称相似的别的仓库。
• 安装后有没有说明依赖要求、输出格式和调用方式。
• 生成结果是否符合这个 Skill 原仓库描述的能力边界。
• 如果结果不理想，是 Skill 本身限制，还是你提供的输入信息不够。

风险提醒

• 社区 Skill 不是官方能力，质量和维护状态差异会很大，使用前最好先看仓库 README。
• 不要默认“给出 GitHub 链接就一定能一步安装成功”，有些 Skill 还会依赖额外脚本、模板或本地环境。
• 第一次验证时，优先选一个小任务，确认 Skill 能正常运行后，再拿去做正式产物。

三种使用姿势

| 模式 | 适合任务 | 典型命令 |
|

配置文件放在哪里

通常位于：

~/.Runnode/config.toml

项目长期规则建议写到仓库内的 AGENTS.md，个人偏好放到本机 config.toml。这样团队成员能共享项目规则，又能保留自己的 CLI 使用习惯。

最小配置示例

下面是一个学习用示例，实际字段请以官方 config reference 和当前 CLI 版本为准：

model = "gpt-5.1-codex-max"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[profiles.readonly]
approval_policy = "on-request"
sandbox_mode = "read-only"

[profiles.build]
approval_policy = "on-request"
sandbox_mode = "workspace-write"

这个示例表达三件事：

• 默认允许在当前工作区写文件。
• 高风险命令仍需要审批。
• 额外保留一个只读 profile，适合新仓库分析。

常见配置项按用途理解

| 用途 | 你要决定什么 | 建议 |
|

先理解四层配置

| 层级 | 典型文件或入口 | 解决的问题 | 初学者建议 |
|

三个概念

| 能力 | 解决的问题 | 适合沉淀什么 |
|

先分清风险等级

| 风险等级 | 例子 | 建议策略 |
|

桌面 App 适合什么

• 本地仓库中的长任务和多阶段任务。
• 同时推进多个不互相阻塞的任务。
• 使用 Worktrees 隔离不同实现分支。
• 把重复流程写成 Skills。
• 用 Automations 做提醒、定期检查或后续跟进。
• 配合浏览器、文档、表格、演示文稿等插件做跨工具工作。

核心能力地图

| 能力 | 用途 | 学习重点 |
|

适用场景

• 连接 GitHub 仓库后发起任务。
• 让 RunNode 阅读仓库并总结架构。
• 将 issue 转成可执行任务。
• 生成 PR 摘要或变更说明。
• 面向非开发者解释技术改动。
• 把复杂任务拆成阶段计划。

第一次任务怎么写

先让 RunNode 只读分析：

请阅读这个仓库并帮我理解 [主题]。请先总结相关目录和关键文件，再给出执行建议。暂时不要修改代码。

进一步推进时：

请基于刚才的分析，完成第一步最小改动，并创建可审查的结果。请说明改动原因、验证方式和剩余风险。

适合非开发者的用法

| 场景 | 任务说明 |
|

CLI 能做什么

• 只读理解仓库结构、入口、测试命令和风险点。
• 修改代码、文档、配置和测试。
• 运行 lint、typecheck、unit test、build 等验证命令。
• 在终端里查看 diff、调整审批策略、恢复会话。
• 通过 Runnode exec 执行标准化的一次性任务。
• 配合 AGENTS.md、config.toml、Skills、MCP 构建长期工作流。

推荐学习顺序

1. 安装 CLI 并完成登录。
2. 在陌生仓库中做一次只读总结。
3. 学会交互模式中的常用 Slash Commands。
4. 完成一次低风险修改，并运行验证。
5. 学会 Runnode exec，把可重复任务脚本化。
6. 增加 AGENTS.md 和本地 config.toml。

交互模式

进入项目根目录：

cd path/to/project
Runnode

第一轮建议不要直接让 RunNode 改代码。先让它建立地图：

请只读分析当前仓库，不要修改文件。

请输出：
1. 项目用途
2. 主要目录和入口文件
3. 安装、启动、测试、构建命令
4. 当前仓库对 RunNode 来说最需要注意的风险
5. 适合第一次交给 RunNode 的 5 个低风险任务

非交互模式

Runnode exec 更适合批处理和自动化：

Runnode exec "请只读分析当前仓库，输出安装、测试和构建命令。不要修改文件。"

建议让输出格式稳定：

请读取当前仓库，不要修改文件。

输出格式：
## 项目概览
## 本地运行
## 测试命令
## CI 风险
## 适合 RunNode 处理的任务

适合脚本化的任务：

| 任务 | 产出 |
|

Cloud 适合什么

• 连接 GitHub 仓库后分派任务。
• 在后台处理长时间修复、迁移或分析。
• 基于 issue 或需求生成分支和 PR。
• 团队成员共同查看任务进度。
• 为大型仓库做结构分析和风险扫描。

提交任务前的清单

| 检查项 | 为什么重要 |
|

IDE 适合什么

• 解释当前文件或选中代码。
• 为一个函数补测试。
• 局部重构。
• 生成注释、文档或类型说明。
• 审查当前 diff。
• 快速理解错误信息和调用链。

选区任务写法

选区越准确，结果越稳定。推荐模板：

请只基于当前选中的代码解释：
1. 它在模块中的职责
2. 输入输出和副作用
3. 可能的边界情况
4. 如果要补测试，建议覆盖哪些场景

如果允许修改：

请只修改当前文件和对应测试文件。

目标：为当前函数补充边界测试。
要求：
1. 先解释测试场景。
2. 修改后运行相关测试。
3. 不做无关重构。

IDE 中的高频任务

| 任务 | 推荐输入 | 结果检查 |
|

入口对照表

| 入口 | 更适合 | 典型任务 | 学习优先级 |
|

方法地图

| 主题 | 解决什么问题 |
|

文档工作

适合任务：

• 把 README 改成新手友好的版本。
• 根据代码生成模块说明。
• 整理迁移指南。
• 生成发布说明。
• 把 issue、PR、commit 整理成周报。

任务模板：

请阅读当前仓库的 README、docs 和 package 配置，帮我整理一份新手上手指南。

要求：
1. 不修改代码。
2. 命令必须来自仓库真实配置。
3. 不确定的步骤标注为“待确认”。
4. 输出目录结构、安装步骤、开发命令、测试命令和常见问题。

学习工作

适合任务：

• 让 RunNode 按学习顺序解释代码库。
• 生成“从入口到核心模块”的阅读路线。
• 把复杂模块讲成产品、设计或运营也能理解的语言。
• 把陌生技术栈拆成学习清单。

任务模板：

请把这个仓库当成学习材料。请按初学者阅读顺序讲解：
1. 先看哪些文件
2. 每个目录承担什么职责
3. 关键数据流或调用链
4. 学完后可以做的 3 个练习

产品与运营工作

适合任务：

• 把 PR 改动翻译成用户影响。
• 生成发布公告草稿。
• 检查文案和功能说明是否一致。
• 从 issue 中提取用户痛点。

任务模板：

请阅读当前 diff，把技术改动整理成产品发布说明。请包含：
1. 用户能感知到的变化
2. 管理后台或配置变化
3. 可能影响旧用户的地方
4. 需要客服或运营同步的话术

知识管理

RunNode 很适合把零散经验沉淀成模板：

• 排障记录。
• FAQ。
• 任务模板。
• 团队规范。
• 案例复盘。

最终目标是把“每次临时问一次”变成“下一次直接复用”。

任务六要素

| 要素 | 写法 | 示例 |
|

团队接入清单

| 项目 | 建议 |
|

最后核对

官方资料最后核对日期：2026-06-12。核心来源包括 RunNode 产品页、RunNode 文档入口、RunNode CLI 官方仓库 与 RunNode Help Center。

RunNode 的产品形态

RunNode 有桌面 App、命令行、编辑器插件和网页几种形态。

• 桌面 App：我们最熟悉的软件形态，第一次上手推荐用这个。选一个文件夹，让 RunNode 读文件、改文档、整理内容，或者直接聊天。
• CLI：终端里的 RunNode，在项目文件夹里读代码、改文件、跑命令。
• Cloud / Web / ChatGPT：任务交给云端处理，或在 ChatGPT 里跟进项目。
• IDE：在 VS Code 等编辑器里用 RunNode 插件，喜欢集成开发环境的开发者适用。
• GitHub、Slack、Linear、MCP 等集成：偏团队和进阶场景。

第一次用 RunNode，推荐从桌面 App 开始。界面直观，功能齐全，对新手友好。

快速开始

1. 下载安装 RunNode 桌面应用，先把软件打开。
2. 按需了解 订阅 RunNode Pro，确认账号能不能用 RunNode。RunNode Help Center 说明 RunNode 包含在符合条件的 ChatGPT 计划中，包括 Free 档；具体用量限制因计划而异。
3. 阅读 了解 RunNode 基本组成，知道项目、对话、设置大概在哪里。
4. 跟着 用 RunNode 完成第一个任务，选一件小任务开始练手。
5. 如果你常用手机，可以再看 手机端如何跟进桌面任务。
6. 如果你需要第三方 API，再看 连接第三方 API。

第一轮目标：装好 RunNode，能跟它正常交流，让它读一个你指定的文件夹。之后结合真实需求，试着完成一个小任务。

使用 RunNode 开发

用过 Claude Code 的话，RunNode 很容易上手。没用过也没关系，像平时用 AI 一样自然地用就行。

推荐顺序：

1. 先看 入口地图，知道 CLI、桌面 App、Cloud 和 IDE 分别适合什么。
2. 阅读 任务执行机制，理解它会读哪些文件、运行哪些命令、怎么汇报结果。
3. 了解 AGENTS.md，把项目规则写给 RunNode 看。

在开发过程中，你会碰到许多专有名词，这里先记住几个词就够了：

• 仓库（repository / repo）：
  一个项目的“家”。代码、文档、配置文件通常放这里，一般用 Git 记录变化。

• diff：
  “改了哪里”的对比清单。告诉你文件修改前什么样，修改后变成什么样。

• PR（Pull Request）：
  理解为“我改好了，请你帮我看一下”。
  团队协作时先提交改动，让别人审核，通过后再合并进主项目。

• CI（Continuous Integration）：
  自动检查流程。
  提交代码后，系统自动跑测试、检查格式、尝试构建，确认改动有没有明显问题。

• AGENTS.md：
  给 AI 编程助手看的“项目说明书”。
  告诉 RunNode / Agent 项目规则、怎么运行、怎么测试、写代码注意什么。每次对话时，Agent 通常把它作为重要上下文参考。

不用强记所有名词。碰到陌生的词，直接让 RunNode 解释；用多了自然熟。

使用 RunNode 完成日常任务

很多人以为 RunNode 只能写代码。其实只要有文件、有目标、有结果可检查，它都能帮上忙。比如：

• 把旅游攻略、酒店链接和预算表放在一起，让 RunNode 帮你整理成一份行程清单。
• 读几份课程资料或 PDF，提炼重点、整理复习提纲。
• 把会议录音转写稿、聊天记录或零散备忘，整理成待办事项。
• 检查一份报名表、活动通知或教程，看看有没有缺步骤、时间写错、链接没说清楚。
• 把每周报销、周报、资料归档的重复步骤写成模板，下次直接复用。
• 整理家庭账单、购物清单、搬家清单、活动分工表这类零散文件。

从最近实际需要处理的小事开始。任务说得越具体，RunNode 解决得越快。

下一步从哪里点

• 还没安装？：从 桌面 App 下载与安装 开始。
• 已经装好了：直接做 第一个任务。
• 想先知道不同入口怎么选：看 入口地图。
• 准备改真实项目：看 任务执行机制。

当前案例概览

| 类型 | 已收录案例 | 适合学习什么 |
|

最后核对日期：2026-05-27。

RunNode 官方

• RunNode 产品页：RunNode 的产品定位、使用界面和团队能力概览。
• RunNode in ChatGPT Help Center：计划可用性、入口和常见问题。
• RunNode CLI Getting Started：CLI 入门、安装和基础能力。
• RunNode 文档入口：RunNode 桌面应用、CLI、Cloud、配置、安全、Skills、MCP 等官方文档入口。
• RunNode cloud docs：云端任务、GitHub 连接和仓库工作流入口。
• Introducing RunNode：RunNode 发布背景和云端软件工程代理介绍。
• Introducing the RunNode app：RunNode 桌面应用 相关介绍。
• Work with RunNode from anywhere：RunNode 移动端 中的 RunNode 入口、跨设备连接和可用性说明。
• Unrolling the RunNode agent loop：RunNode agent loop 背后的工作方式介绍。

官方文档重点页面

• RunNode docs（桌面端）：桌面 App 功能入口，包含本地项目、Review、Automations、Worktrees、Local Environments、In-app Browser、Computer Use 等主题。
• RunNode CLI features：CLI 交互模式、非交互模式、功能概览。
• AGENTS.md：项目规则文件的官方说明。
• RunNode security：沙盒、审批和安全边界。
• RunNode config basic：基础配置。
• RunNode config advanced：高级配置。
• RunNode config reference：完整配置参考。
• RunNode skills：Skills 官方说明。
• RunNode Remote docs：云端任务、环境、仓库连接和任务执行入口。

GitHub 官方仓库

• openai/codex：RunNode CLI 开源仓库。
• AGENTS.md 相关文档：项目规则文件相关说明。
• CLI getting started：CLI 首次使用流程。
• Authentication：认证和登录相关说明。
• Exec：非交互模式相关说明。
• Slash Commands：CLI 会话命令说明。
• CLI 安装与构建：系统要求、源码构建和日志说明。
• CLI 配置：配置文档索引。
• Sandbox 文档：沙盒与审批官方入口。
• Exec Policy：命令执行策略相关说明。
• Skills：CLI 仓库中的 Skills 文档。

如何使用这些资料

• 入门安装优先看 Help Center 和 GitHub README。
• 了解产品边界优先看 RunNode 产品页。
• 做团队接入时优先看 Help Center、平台文档、App 文档和企业相关说明。
• 写教程时不要整段翻译原文，应转化成中文场景和可复现步骤。
• 涉及价格、计划、模型、可用地区、功能开关、账号权限时，必须打开原文重新确认。

如果你在 App 中看到了和技能、插件相关的入口，可以先用这张图定位它们：

三个核心概念

理解这三者最快的方式，是把 AGENTS.md、Skill、Plugin 放在一起看：

| 概念 | 解决什么问题 | 更像什么 |
|

AGENTS.md 正是为了解决这类问题而存在的项目级指令文件。它是一个简单、开放的 Markdown 约定，目标是给不同 coding agent 提供一个稳定、可预测的项目指令入口，把项目结构、开发命令、测试要求、代码风格和协作边界显式写下来，减少反复解释。

更准确地说，AGENTS.md 是面向 coding agent 的 README。README 主要给人看，讲项目是什么、怎么上手；AGENTS.md 给 RunNode 和其他 coding agent 看，告诉它们改代码前应该遵守哪些项目规则。

可以把它理解为：

• 对个人用户：减少重复解释“项目怎么跑、怎么测、哪些地方不能碰”。
• 对团队项目：把团队共同认可的 agent 使用规则沉淀到仓库里。
• 对多工具环境：让 RunNode、IDE agent、CLI agent 等工具尽量读取同一份项目说明。

本质上就是一份普通的 Markdown 文件。

另外需要注意，截至目前，Claude Code 并不遵守 AGENTS.md 约定，取而代之的是 CLAUDE.md 约定。

存放位置与读取机制

文件位置

对于普通项目，最推荐的做法是在项目根目录创建 AGENTS.md。RunNode 在开始处理任务前会自动读取它，并把内容作为工作上下文带入新的对话。

若希望全局生效，可以撰写 RunNode 的全局指令：

1. 在 RunNode_Home 目录中创建 AGENTS.md。默认位置通常是 ~/.codex/AGENTS.md；如果设置了 CODEX_HOME，则以对应目录为准。
2. 在 RunNode 桌面应用 里配置个人偏好或自定义指令。本质上也是写入 RunNode_Home 的 AGENTS.md，与上述方法等价。

设置全局规则后，它会影响你打开的所有项目；项目级 AGENTS.md 只影响当前仓库。两者作用域不同，要分清。

请确保文件名始终为 AGENTS.md，并确认大小写是否正确。否则 RunNode 不会自动识别。

读取顺序与合并规则

RunNode 读取 AGENTS.md 遵循以下顺序：

1. 先读取全局规则：默认读取 ~/.codex/AGENTS.md。如果同一位置存在 AGENTS.override.md，则优先读取它，适合临时覆盖全局规则。
2. 然后读取项目规则：进入项目后，RunNode 通常会从 Git 根目录开始，一路走到当前工作目录。沿途每一层目录，它会尝试读取项目指令文件。

项目指令文件的默认优先级是：

AGENTS.override.md
AGENTS.md

也就是说，同一目录里如果同时存在这两个文件，AGENTS.override.md 会覆盖 AGENTS.md。

RunNode 会把读取到的指令从上到下合并。根目录的规则先出现，子目录的规则后出现。越靠近当前目录的规则越具体，因此也更适合写局部要求。

一个文件结构的示例：

AGENTS.md
apps/
  web/
    AGENTS.md
packages/
  database/
    AGENTS.md

上述示例中，根目录 AGENTS.md 写全仓库通用规则，apps/web/AGENTS.md 写前端规则，packages/database/AGENTS.md 写数据库迁移和测试要求。

注意事项：

1. 如果你的项目已经有其他规则文件，可以通过 RunNode 配置里的 project_doc_fallback_filenames 添加备用文件名。RunNode 会在找不到 AGENTS.override.md 和 AGENTS.md 时，再尝试这些 fallback 文件。
2. RunNode 还会限制合并后的项目指令大小。官方默认值是 project_doc_max_bytes = 32768，也就是 32 KiB。规则文件太大时，后面的内容可能不会进入上下文，所以尽量保持 AGENTS.md 精简。

团队协作

多人协作时，AGENTS.md 适合保存团队共同认可的项目规则；个人路径、本机工具习惯、临时约束和私有工作流偏好，则更适合留在本地。这样团队规则保持稳定，个人习惯也不会被提交到仓库。

使用场景

下面这些内容适合放在本地私有规则里：

• 本机缓存、SDK、脚本或临时目录路径。
• 个人常用命令、别名、编辑器习惯。
• 只对自己有效的语言风格、回复格式、验证偏好。
• 不方便进入团队文档的临时限制，例如“今天先只做只读分析”。

文件分工

| 文件 | 作用 | 是否提交到 Git |
|

RunNode 找不到项目上下文

可能原因：

• 你不在项目根目录。
• 仓库缺少 README、测试命令或项目说明。
• monorepo 没有说明包边界。

处理方式：

• 先让 RunNode 只读目录并总结项目结构。
• 添加或更新 AGENTS.md。
• 在任务说明里指定相关目录。

RunNode 改动范围太大

处理方式：

• 明确“只修改这些文件”。
• 要求“先输出计划，不要动手”。
• 把任务拆成更小的步骤。
• 在 review 时拒绝无关重构。

测试跑不起来

处理方式：

• 让 RunNode 先定位测试命令。
• 检查依赖是否安装。
• 区分环境问题和代码问题。
• 如果是环境问题，让 RunNode 记录阻塞，而不是继续乱改。

生成内容不准确

处理方式：

• 要求 RunNode 引用它依据的文件。
• 对官方事实要求附链接。
• 让它区分“已确认”和“推测”。
• 让它先读代码再写文档。

登录或权限问题

处理方式：

• 更新 RunNode CLI 到最新版本。
• 重新运行登录流程。
• 检查当前账号计划和组织策略。
• 查看官方 Help Center 的 RunNode 相关文章。

Windows 桌面 App / CLI 专项排障

如果问题发生在 Windows 桌面 App、Microsoft Store / winget 安装、Windows sandbox、Worktree、Browser / Computer Use 插件、WSL 混合路径或 PowerShell 环境，可以参考社区维护的 Windows 专项排障库：

• Community RunNode Windows Troubleshooting
• Windows RunNode Error Guide
• Dogfood Matrix

这个项目会把 Windows 报错按证据等级、复现等级和 workaround 状态整理，并提供只读诊断脚本。提交日志、截图或诊断输出前，请先脱敏用户名、路径、私有仓库名、token 和账号信息。

切换 provider 后旧会话不可见

可能原因：

• 修改过 config.toml 根级 model_provider。
• 旧会话文件还在，但会话 metadata、SQLite 状态或项目路径缓存仍指向旧 provider。
• CLI /resume 能看到旧会话，但 RunNode Desktop 项目侧看不到，可能只是 Desktop 最近 50 条会话的首屏显示限制。

处理方式：

• 先确认 ~/.codex/sessions 或 ~/.codex/archived_sessions 里是否还存在旧会话文件。
• 如果只是 Desktop 项目侧不可见，先判断是否被最近 50 条显示限制挡住。
• 如果确认是切换 provider 后 metadata 不一致，再参考 config.toml 里的社区工具说明。
• 使用第三方工具前先备份 ~/.codex，不要把它当成官方认证或账号切换工具。