name: oracle description: 使用oracle CLI的最佳实践（提示词+文件打包、引擎、会话和文件附件模式）。 homepage: https://askoracle.dev metadata: { “openclaw”: { “emoji”: “🧿”, “requires”: { “bins”: [“oracle”] }, “install”: [ { “id”: “node”, “kind”: “node”, “package”: “@steipete/oracle”, “bins”: [“oracle”], “label”: “安装oracle（node）”, }, ], }, }
oracle — 最佳使用方式
Oracle将您的提示词+选定的文件打包成一个“一次性”请求，以便另一个模型能够基于真实的仓库上下文进行回答（通过API或浏览器自动化）。请将输出视为建议性内容：务必对照代码和测试进行验证。
主要使用场景（浏览器，GPT‑5.2 Pro）
这里的默认工作流是：在ChatGPT中使用--engine browser配合GPT‑5.2 Pro模型。这是常见的“长思考”路径：通常需要约10分钟到1小时；预期会生成一个可以重新附加的存储会话。
推荐默认设置：
- 引擎：浏览器 (
--engine browser) - 模型：GPT‑5.2 Pro (
--model gpt-5.2-pro或--model "5.2 Pro")
黄金路径
- 选择一个紧凑的文件集（包含所需信息的最少文件）。
- 预览有效负载和令牌消耗 (
--dry-run+--files-report)。 - 对于常规的GPT‑5.2 Pro工作流，使用浏览器模式；仅在明确需要时才使用API模式。
- 如果运行断开连接或超时：重新附加到存储的会话（不要重新运行）。
命令（推荐）
-
帮助：
oracle --help- 如果二进制文件未安装：
npx -y @steipete/oracle --help（此处避免使用pnpx；涉及sqlite绑定）。
-
预览（不消耗令牌）：
oracle --dry-run summary -p "<任务>" --file "src/**" --file "!**/*.test.*"oracle --dry-run full -p "<任务>" --file "src/**"
-
令牌合理性检查：
oracle --dry-run summary --files-report -p "<任务>" --file "src/**"
-
浏览器运行（主要路径；长时间运行是正常的）：
oracle --engine browser --model gpt-5.2-pro -p "<任务>" --file "src/**"
-
手动粘贴后备方案：
oracle --render --copy -p "<任务>" --file "src/**"- 注意：
--copy是--copy-markdown的隐藏别名。
附加文件 (--file)
--file接受文件、目录和通配符模式。您可以多次传递该参数；条目可以用逗号分隔。
-
包含：
--file "src/**"--file src/index.ts--file docs --file README.md
-
排除：
--file "src/**" --file "!src/**/*.test.ts" --file "!**/*.snap"
-
默认行为（实现细节）：
- 默认忽略的目录：
node_modules,dist,coverage,.git,.turbo,.next,build,tmp（除非明确作为字面目录/文件传递，否则会被跳过）。 - 展开通配符时遵循
.gitignore规则。 - 不跟随符号链接。
- 点文件默认被过滤，除非通过模式选择加入（例如
--file ".github/**"）。 - 拒绝大于1 MB的文件。
- 默认忽略的目录：
引擎（API 与 浏览器）
- 自动选择：当设置了
OPENAI_API_KEY时选择api；否则选择browser。 - 浏览器仅支持GPT和Gemini；对于Claude/Grok/Codex或多模型运行，请使用
--engine api。 - 浏览器附件：
--browser-attachments auto|never|always（自动模式下，在达到约6万字符前内联粘贴，之后上传）。
- 远程浏览器主机：
- 主机端：
oracle serve --host 0.0.0.0 --port 9473 --token <密钥> - 客户端：
oracle --engine browser --remote-host <主机:端口> --remote-token <密钥> -p "<任务>" --file "src/**"
- 主机端：
会话 + 标识符
- 存储在
~/.oracle/sessions下（可通过ORACLE_HOME_DIR覆盖）。 - 运行可能会断开连接或需要很长时间（浏览器+GPT‑5.2 Pro经常如此）。如果CLI超时：不要重新运行；重新附加。
- 列出：
oracle status --hours 72 - 附加：
oracle session <id> --render
- 列出：
- 使用
--slug "<3-5个单词>"来保持会话ID的可读性。 - 存在重复提示词防护机制；仅在确实需要全新运行时才使用
--force。
提示词模板（高信息量）
Oracle从零项目知识开始。请假设模型无法推断您的技术栈、构建工具、约定或“显而易见”的路径。请包含：
- 项目简介（技术栈 + 构建/测试命令 + 平台约束）。
- “文件位置”（关键目录、入口点、配置文件、边界）。
- 确切的问题 + 您尝试过的操作 + 错误文本（逐字逐句）。
- 约束条件（“不要更改X”、“必须保持公共API”等）。
- 期望的输出（“返回补丁计划+测试”、“提供3个选项并附上权衡”）。
安全性
- 默认情况下不要附加机密文件（
.env、密钥文件、身份验证令牌）。积极进行脱敏处理；仅分享必需的内容。
“详尽提示词”恢复模式
对于长时间的调查，编写一个独立的提示词+文件集，以便您可以在几天后重新运行：
- 6–30句的项目简介 + 目标。
- 重现步骤 + 确切错误 + 您尝试过的操作。
- 附加所有需要的上下文文件（入口点、配置文件、关键模块、文档）。
Oracle运行是一次性的；模型不会记住之前的运行。“恢复上下文”意味着使用相同的提示词 + --file …集重新运行（或重新附加仍在运行的存储会话）。