使用 Raven¶
先选择与 Raven 交互的方式,为会话指定正确工作目录,再按需增加 Agent 或服务。
下文使用已安装的命令;源码检出时可在前面加 uv run。
选择入口¶
| 目标 | 入口 | 下一步指南 |
|---|---|---|
| 终端会话 | raven tui |
命令参考 |
| 浏览器会话 | raven web |
启动 WebUI |
| 在仓库执行单次任务 | raven agent -m "Summarize this project without editing files" |
权限与安全 |
| 从消息平台聊天 | 已配置渠道和常驻网关 | 渠道与消息 |
| 委派给专用 Agent | Roster 中已配置的 Agent | Agent 集成 |
| 与专用 Agent 继续协作 | 它的有状态实例 | 与子 Agent 协作 |
| 操作共享浏览器 | 浏览器工具和 WebUI 面板 | 浏览器协作 |
| 检索文档段落 | WebUI 知识库页面与会话中的知识库选择;集成使用 Python 库或 RPC | 知识库 |
| 执行并观察长任务 | 声明 campaign 后的 Raven-Oncall | 长任务托管(Oncall) |
| 集成编辑器或远程 peer | ACP 或 A2A | Agent 协议 |
raven agent 必须提供消息,不是交互式 REPL;连续会话使用 TUI 或 WebUI。
尚未配置模型服务商时,先读快速开始。
选择正确工作目录¶
工作目录保存任务操作的文件;Agent home 保存身份、记忆、技能和 transcript, 不能把它当作项目仓库的同义词。单次任务示例:
raven agent --workspace /absolute/path/to/project -m "Read the README and summarize the setup steps"
这会执行模型轮次,可能产生服务商费用。修改任务应明确可编辑文件和验证方式。
同一 Git 项目中有多个编码任务并行时,宿主的 multi-agent-coding skill 会要求各编码
Agent 创建独立 worktree,并汇报路径和分支。协调并发修改前,应检查这些汇报。
该流程见与子 Agent 协作;
手动构建任务图时参阅DAG 编排。
Raven 的状态存放位置¶
Raven 的运行时状态——配置、命令历史、日志——都放在一个目录下:设置了 $RAVEN_HOME
就用它;未设置或为空则用 ~/.raven。取值可以是绝对路径、裸 ~,或以 ~/ 开头;
裸 ~ 和 ~/ 前缀都会在各前端展开为用户主目录。~\ 是同一前缀的 Windows 写法:
Windows 上各前端都会展开,其他平台上只有 TUI 会展开。其他以 ~ 开头的形式(如
~name)在 TUI 中不展开,按相对路径处理。相对路径会相对每个进程各自的工作目录解析,
因此不同前端可能指向不同目录;建议使用绝对路径。
继续会话¶
每次单次 CLI 调用默认创建新会话。确实需要延续上下文时,选择 --continue、
--resume <id-or-prefix> 或 --session <full-key>;三者互斥。
raven sessions --help
raven agent --continue -m "Expand the previous summary; do not modify files"
交互式会话通过 UI 的会话选择器切换。子 Agent 的 instance 续接子 Agent 会话,
不是宿主 session id 或 DAG node id,详见DAG 编排。
设置思考深度¶
思考深度是模型每次回答前思考多少。可选的词由当前模型声明:多数模型是 minimal、
low、medium、high,厂商提供时还会有 xhigh、max;有些接口的档位更窄,只收其中
几个(DeepSeek 只收 low、high、max,把 minimal 归入 low、medium 归入
high)。档位跟随实际承接请求的服务商,而不只看模型名:同一个模型经网关访问时,用网关
的档位。没有声明任何档位的模型不会出现这一行。各厂商把这些词映射成自己的请求参数
(Anthropic 的自适应思考强度与思考预算,OpenAI 风格接口的 reasoning_effort 字段),
没有思考能力的模型会忽略它。不设置时使用厂商自己的默认值。
两处可以设置:
- 对所有会话:在 WebUI 打开设置页,在「主会话」一行点「参数」,再选「思考深度」;
或在
~/.raven/config.json里设置agents.defaults.reasoningEffort。第一档 「厂商默认」会清掉这个键。 - 只对当前会话:WebUI 模型选择器(点输入框旁的模型标签打开)里的「思考深度」行,
或 TUI 里的
/effort <词>。单独输入/effort查看当前生效的档位,/effort default让这个会话重新跟随全局设置。在与某个子智能体实例直聊时这条命令会被拒绝:这个选择 属于主会话,实例自己没有思考深度可设。
也可以在厂商的 model_overlay.reasoningEfforts 里声明某个模型的可用档位
(设置页该厂商的「高级」→「显示名」下的「添加」)。非空声明优先于 LiteLLM 的表,
包括表里标为不支持 reasoning 的路由;留空则回退到表。
单个会话的选择优先于全局设置和该会话的模式。它记录在会话自己的档案里,网关重启后仍在,
恢复会话时一并带回,从下一轮开始生效。当前模型不声明这个档位时,按该模型声明的、低于它的
最高档运行(在一个模型上选了 max,切到只到 high 的模型,就按 high 运行);只有当它
连更低的档都不声明时,才改为运行该会话模式的档位或全局设置。这个选择会按原词保留,切回
支持它的模型时继续生效。它只影响 Raven 自己的模型调用;子智能体仍按全局默认值运行。
有目的地增加能力¶
可复用指令用 skill,外部工具用 MCP,运行时贡献用 plugin。需要独立身份和执行配置 时使用专用 Agent,需要协调有依赖的工作时使用 DAG 或 playbook。A2A 面向独立运营 的 peer,不是本地 plugin 的另一种名称。
技能、记忆与扩展解释这些选择。定时或主动任务请读 主动提醒与跟进,并保持相应常驻宿主运行。
检查结果与排障¶
先使用 raven status 和 raven doctor。模型已配置、Agent 已列出或握手成功,
都不代表真实任务成功。应检查最终回答、生成文件、相关测试或任务证据。
任务停滞时,先检查审批请求、子 Agent 就绪状态、模型错误和运行进度,再决定重试;
重试可能重复外部副作用。使用 raven tracing、raven trajectory --help 查诊断,
分享前先脱敏私人材料。轨迹调试与回放说明如何保存证据,
以及如何在不重复录制的外部动作的情况下重现 harness 行为。