Agentic Planner#

RPent 通过一个 CLI 参数选择 Agentic Planner 的后端：

--planner {api, claude_code, codex}

三种 planner 接收相同的系统提示词和用户提示词，也使用同一套 RPent 工具定义。 它们的区别在于如何将这些工具接入模型、如何组织工具调用循环，以及使用哪个模型 SDK。

--planner

它是什么

什么时候选它

api

基于 Pydantic AI 实现的工具调用循环， 不绑定特定模型提供商。当前支持 Anthropic Messages API、OpenAI Responses API 和 OpenAI 兼容的 Chat Completions API，内置 prompt 缓存和历史图片剪枝。

需要精细控制模型调用、支持更多模型提供商，或降低单轮调用成本。

claude_code

Claude Agent SDK。 把 RPent 的 toolkit 暴露为进程内 MCP 服务，由 Claude Agent SDK 驱动循环。

想使用 Claude Code 原生提供的 agent 能力（memory、thinking-mode 预算和更完善的工具重试机制）。

codex

OpenAI Codex Python SDK。RPent 在进程内启动 Streamable HTTP MCP 服务，把 toolkit 接入 Codex。

想使用 Codex 原生提供的 agent 能力，或者已有可用的 OpenAI 或 Codex 配额。

flash

Flash Mode，仅用于评测。重放 memory 中保存的成功执行计划，并对每个路点 的锚点重新定位，使方案能跟随移动过的物体。参见 Flash Mode。

想在新布局上低成本地重跑一个已知可行的方案，无需 LLM 在线规划；仍需要感知和 VLA 服务。

api planner（直接调用模型 API）#

--planner api 是默认选项。它使用 Pydantic AI 实现工具调用循环，并要求 --model 带有模型提供商前缀。当前项目安装的依赖包含 Anthropic 和 OpenAI 集成，因此可以直接使用 Anthropic Messages API、OpenAI Responses API， 以及 OpenAI 兼容的 Chat Completions API。

通过 --model 前缀选择模型提供商：

# Anthropic Claude
rpent --planner api --model anthropic:claude-opus-4-8 ...

# OpenAI Responses (例如 GPT-5.5)
rpent --planner api --model openai:gpt-5.5 ...

# OpenAI 兼容的 Chat Completions（例如 GLM 5.2，纯文本）
rpent --planner api --model openai-chat:glm-5.2 --no-images ...

它读取以下环境变量；需要覆盖 API 地址时使用 --base-url：

  • anthropic:* → ANTHROPIC_BASE_URL / ANTHROPIC_API_KEY

  • openai:* / openai-chat:* → OPENAI_BASE_URL / OPENAI_API_KEY

api planner 的相关调节参数：

  • --max-tokens —— 单次 LLM 回复的 token 上限（默认 8192）。

  • --max-turns —— 工具调用轮数上限（默认 100）。

  • --no-images —— 不向模型发送图片字节；纯文本模型必须加此参数。此时 智能体只依赖文本状态推理，任务表现可能不够理想。

claude_code planner#

--planner claude_code 将工具调用循环交给 Claude Agent SDK。 RPent 通过 SDK 创建进程内 MCP 服务，并把 toolkit 的工具注册到 mcp__rpent__<name> 命名空间。

RPent 为 Claude 规划会话关闭文件系统配置来源，因此不会自动加载项目的 CLAUDE.md 和开发 skills。工作目录仍为仓库根目录。

rpent --robot libero --planner claude_code \
  --model claude-opus-4-8 \
  --suite libero_object_swap --task 2 --seed 0

注意事项：

  • --model 不要 加模型提供商前缀；省略时默认使用 sonnet。

  • --max-turns 会传给 Claude Agent SDK，默认 100。

  • 非交互运行受 --planner-timeout-s 限制；默认读取 CELL_TIMEOUT_S，未设置时为 1200 秒。--interactive 模式 不应用这一时限。

  • 通过 --claude-code-max-budget-usd 设置美元预算（默认取 MAX_BUDGET_USD 环境变量或 10）。

  • RPent 的依赖中已包含 Claude Agent SDK；该 SDK 自带 Claude Code 二进制文件，无需单独安装 CLI。认证通常使用 ANTHROPIC_API_KEY，详见 Claude Agent SDK 文档。

通过 Claude Code 使用本地模型#

Claude Code 可以连接兼容 Anthropic Messages API 的本地模型服务。假设服务将 Qwen3.6-27B 注册为 Qwen/Qwen3.6-27B，可以这样配置：

export ANTHROPIC_BASE_URL=http://127.0.0.1:8000
export ANTHROPIC_API_KEY=EMPTY

rpent --robot libero --planner claude_code \
  --model Qwen/Qwen3.6-27B \
  --suite libero_goal_task --task 1 --seed 0

对于无法识别的本地模型名称，Claude Code 默认按 200,000 token 的上下文窗口 管理会话。如果本地服务使用其他长度，请参考 Claude Code 环境变量文档 配置它的上下文和自动压缩参数。

codex planner#

--planner codex 使用 OpenAI Codex Python SDK。每次运行时，RPent 会在当前进程的后台线程中启动本地 Streamable HTTP MCP 服务，Codex 通过 该服务调用同一个 toolkit；无需预先启动 scripts/codex_proxy/。

Codex 规划会话不会自动加载仓库的 AGENTS.md 和 .agents/skills/ 中的开发 skills。工作目录仍为仓库根目录，机器人指南和 memory 仍可通过 已有工具读取。

rpent --robot libero --planner codex \
  --model gpt-5.5 \
  --suite libero_goal_task --task 1 --seed 0

注意事项：

  • 设置 CODEX_SERVICE_TIER=fast 可向 Codex 后端传入 fast 服务档位， 不改变 --reasoning-effort。未设置时 RPent 不覆盖服务档位。

  • --model 会覆盖 CODEX_MODEL；两者都未设置时使用 Codex SDK 配置的默认模型。

  • --planner-timeout-s 限制 Codex 运行时间。默认依次读取 CODEX_TIMEOUT_S、CELL_TIMEOUT_S，均未设置时为 1200 秒。

  • 默认情况下，Codex SDK 会复用已有的 Codex 认证。若要接入自定义的 Responses API 兼容端点，请设置 CODEX_BASE_URL 和 CODEX_API_KEY；这里不读取 OPENAI_BASE_URL 或 OPENAI_API_KEY。

通过 Codex 使用本地模型#

Codex 可以连接兼容 OpenAI Responses API 的本地模型服务。下面以通过 vLLM 启动 Qwen3.6-27B 为例：

vllm serve /path/to/Qwen3.6-27B \
  --served-model-name Qwen/Qwen3.6-27B \
  --max-model-len 262144 \
  --reasoning-parser qwen3 \
  --enable-auto-tool-choice \
  --tool-call-parser qwen3_coder

然后让 Codex 连接本地服务，并填写该服务实际开放的上下文限制：

export CODEX_BASE_URL=http://127.0.0.1:8000
export CODEX_API_KEY=EMPTY
export CODEX_MODEL_CONTEXT_WINDOW=262144
export CODEX_AUTO_COMPACT_TOKEN_LIMIT=230000

rpent --robot libero --planner codex \
  --model Qwen/Qwen3.6-27B \
  --suite libero_goal_task --task 1 --seed 0

vLLM 在兼容 OpenAI 的 /v1/models 响应中用 max_model_len 表示该上限， 而 Codex 使用的模型目录格式要求 context_window 字段。因此，Codex 无法识别 vLLM 返回的模型元数据时会使用备用配置。请将 CODEX_MODEL_CONTEXT_WINDOW 设置为当前 vLLM 服务的 --max-model-len。这是服务实际接受的上限；为了适应可用显存，它可以低于 checkpoint 配置中标注的最大长度。

CODEX_AUTO_COMPACT_TOKEN_LIMIT 用于设置 Codex 自动压缩会话历史的触发点。 该值应小于 CODEX_MODEL_CONTEXT_WINDOW，为下一次回复预留空间；当服务窗口为 262144 token 时，230000 是一个示例值。这两个变量都是可选的；如果未 设置，Codex 将使用自身的默认值。

RPent 的 --model 必须与 vLLM 的 --served-model-name 保持一致。使用其他 模型时，请按照对应的 vLLM 部署说明设置解析参数。

验证你的配置#

一次完整运行会先启动 env server、VLA server 并同步 memory 语料，之后才 会真正调用模型；因此一个写错的 API key 往往要等数分钟启动之后才暴露。 rpent-check-llm 会向所选后端发出它支持的最小真实请求——不带工具、 不带图像、不启动任何机器人运行时——并报告结果：

rpent-check-llm --planner api --model anthropic:claude-opus-4-8
rpent-check-llm --planner claude_code
rpent-check-llm --planner codex --json

成功时退出码为 0，任何失败为 1，并将失败归类为 missing_config、unsupported_provider、missing_api_key、 auth_failed、network_error、provider_error、sdk_error 之一。脚本与 CI 建议使用 --json。--base-url 覆盖后端端点， --timeout-s 覆盖诊断超时（api 为 30 秒，两个 SDK 后端为 90 秒； 运行时的 1200 秒默认值不会被复用）。

Dashboard 提供同一项检查：启动页的 测试连接 按钮会针对表单中当前 选定的 planner 与模型执行检查，因此你测试的配置与 启动 Session 将 要使用的配置完全一致。两个前端调用的是 rpent.planner.check 中的同 一份实现。

检查通过只能证明认证与网络可达。它并不能证明模型会接受图像块 （参见 --no-images）、你的工具 schema，或你的上下文长度。

接入自定义 planner#

如果三种内置 planner 都不合适，例如需要接入内部 planner、研究原型或其他 agent SDK，可以实现 rpent.planner.base.Planner 协议，并在 rpent.planner.base.build_planner 中增加对应的构造分支：

# rpent/planner/my_planner.py
from rpent.planner.base import PlannerResult
from rpent.utils.templates import substitute

class MyPlanner:
    def solve(
        self,
        *,
        system_prompt,
        user_message,
        toolkit,
        max_turns,
        input_queue=None,
    ):
        tool_specs = [
            {
                "name": declaration.name,
                "description": declaration.description,
                "input_schema": substitute(declaration.input_schema),
            }
            for declaration in toolkit.list_tools()
        ]
        # 使用 system_prompt、user_message 和 tool_specs 调用模型。
        # 每次工具调用都通过下面的接口执行：
        tool_result = toolkit.execute_tool(tool_name, arguments)
        ...
        return PlannerResult(
            finish_result=toolkit.finish_result,
            messages=messages,
            stats=stats,
            error=error,
        )

任何 planner 必须：

  1. 接收已经渲染好的 system_prompt 和 user_message。

  2. 从 toolkit.list_tools() 取得工具定义，并通过 toolkit.execute_tool(name, arguments) 执行工具。

  3. 将 tool_result.to_text() 和 tool_result.images 转换成模型 SDK 所需的格式，同时保留 tool_result.is_error 错误标记。

  4. finish 调用被接受、toolkit.finish_result 设置后结束循环，并遵守 max_turns 等运行限制。

  5. 返回包含结束状态、消息、统计信息和可选错误的 PlannerResult。

由于 RPent 工具定义和 prompt 渲染流程保持不变，新增 planner 不需要修改 工具或环境服务。接口参见 系统说明；想给 自定义 planner 暴露新工具，见 添加动作原语。

设置 planner 的运行限制#

以下参数的作用范围并不相同：

  • --max-tokens 只限制 api planner 每次回复 的 token 数。 LIBERO 类任务通常 8192 就够；更长时序的 RoboCasa episode 如果模型支持可以调大。

  • --max-turns 限制工具调用的总轮数。单个 LIBERO 任务通常 不会超过 30 轮；RoboCasa 的长时序任务可能接近默认的 100。

  • --planner-timeout-s 限制 planner 的运行时间。

模型调用 finish 工具后，planner 会记录相应的结束状态。达到轮数上限或 超时时，运行结束，主程序仍会保存 transcript。超时或 SDK 异常会写入 planner 结果，并输出到日志。