FAQ

🌐 English | 中文

FAQ & Troubleshooting

General

Q: How is Philont different from OpenClaw / Hermes? The projects overlap and evolve quickly. Philont's design center is persistent pursuits: authorization, execution evidence, recovery, memory, and learning governance are explicit runtime objects around a replaceable model. Selfhood Engineering is the deeper design thesis; support for smaller models is the practical developer entry point. See Design Centers and Why Smaller Models.

Q: What can smaller models realistically do with Philont? Smaller models are a first-class target, not a proven parity claim. Philont moves state, bounds, evidence, and recovery into the runtime, but it cannot manufacture reasoning ability the model lacks. No reproducible cost-per-verified-success comparison has been published yet; stronger models may still plan better and solve harder single-inference problems. See Why Smaller Models and Evaluation Status.

Q: Which platforms are supported? Developed primarily on Windows. Linux and macOS (Apple Silicon) build and boot are verified in CI; real-provider round trips and every platform-specific workflow are not. Native modules such as better-sqlite3 and sharp must be installed for the host platform. Reports and PRs are welcome.

Q: Do I need a Rust toolchain? No. The runtime is pure TypeScript; Node.js ≥ 20 is the only prerequisite besides an API key.

Setup

Q: The agent gives canned/nonsense replies. You're probably in mock mode — LLM_PROVIDER is empty/unset. Set it explicitly (anthropic, openai, …). See Configuration.

Q: How do I run it on DeepSeek V4 Flash? LLM_PROVIDER=openai + point OPENAI_BASE_URL / OPENAI_MODEL / OPENAI_API_KEY at DeepSeek's OpenAI-compatible endpoint. Configuration → cheap path.

Q: Downloads/files aren't landing where I expect. PHILONT_DOWNLOAD_DIR is case-sensitive. Check the exact casing.

Q: Can I expose the Web UI publicly? Not as-is — it ships without auth and binds to localhost. Put a reverse proxy with auth + TLS in front (see DEPLOYMENT.md).

Behaviour

Q: Why did the agent refuse to act until it "made a plan"? A multi-step, world-changing task is classified slow, which arms plan_protocol_gate — it blocks write/execute tools until a plan exists. This is by design. Read-only exploration is not blocked. See Plan Protocol.

Q: The agent said something was done, then "corrected" itself in the same reply. That's an honesty gate firing: it detected a completion/fabrication claim unsupported by the turn's real tool results and forced one honest regeneration before the text reached you.

Q: It keeps reflecting / refusing to retry the same thing. After two same-root-cause failures in a turn, in-turn reflection forces the model to classify the failure and consult docs instead of retrying blindly. See Honesty Gates → in-turn reflection.

Q: deep_explore ran for a long time and concluded "unresolved / stuck." That's honest behaviour, not a bug. deep_explore counts only substantive progress and reports a genuinely stuck frontier rather than fabricating a conclusion. See Deep Reasoning.

Security

Q: Is it safe to point this at untrusted input / run it unattended in production? Not yet. It's a developer preview; the real isolation control (an OS sandbox) is not shipped. The current controls are defense in depth around a trusted-operator model. Read Permission & Security for the current enforcement matrix. The repository's SECURITY-DESIGN.md is a historical design record, not the current security contract.

Q: Where do I report a security issue? Via SECURITY.md — not a public issue.

---

中文

English | 中文

常见问题与排错

总览

问:Philont 和 OpenClaw / Hermes 有何不同? 这些项目的能力彼此重叠，也都在快速变化。Philont 的设计中心是持续性 pursuit：把授权、执行证据、恢复、记忆和学习治理做成围绕可替换模型的一等 runtime 对象。自我工程是更深层的设计命题；较小模型支持是开发者容易理解的实际入口。参见设计中心和为什么把较小模型作为一等目标。

问：Philont 能让较小模型实际承担哪些工作？ 较小模型是一等目标，不是“已经达到前沿模型水平”的结论。Philont 把状态、边界、证据和恢复移进 runtime，但不能凭空创造模型缺少的推理能力。目前还没有发布可复现的“每次验证成功成本”对照；更强模型仍可能做出更好的计划并解决更困难的单次推理。参见为什么把较小模型作为一等目标和评测状态。

问:支持哪些平台? 主要在 Windows 上开发；Linux 与 macOS（Apple Silicon）的 build 和 boot 已由 CI 验证，但真实 provider 往返和所有平台专属流程尚未覆盖。better-sqlite3、sharp 等原生模块需要针对宿主平台安装。欢迎反馈与 PR。

问:需要 Rust 工具链吗? 不需要。运行时纯 TypeScript;除 API key 外唯一前置是 Node.js ≥ 20。

安装

问:agent 给出预设/胡乱回复。 你大概在 mock 模式 —— LLM_PROVIDER 为空/未设。请显式设置(anthropic、openai…)。见 配置。

问:怎么跑在 DeepSeek V4 Flash 上? LLM_PROVIDER=openai + 把 OPENAI_BASE_URL / OPENAI_MODEL / OPENAI_API_KEY 指向 DeepSeek 的 OpenAI 兼容端点。配置 → 便宜路线。

问:下载/文件没落到我预期的位置。 PHILONT_DOWNLOAD_DIR 大小写敏感。检查准确大小写。

问:能把 Web UI 公开暴露吗? 原样不能 —— 它不带鉴权且绑定 localhost。在前面放带鉴权 + TLS 的反向代理(见 DEPLOYMENT.md)。

行为

问:为什么 agent 在「做计划」前拒绝行动? 一个多步、改变世界的任务被分类为 slow,从而武装 plan_protocol_gate —— 它在计划存在前挡住 写/执行 工具。这是设计使然。只读探索不被挡。见 计划协议。

问:agent 先说某事完成了,又在同一条回复里「自我更正」。 那是 诚实门 触发:它检出一个不被本 turn 真实工具结果支撑的完成/编造声明,并在文本到达你之前强制一次诚实重写。

问:它一直反思 / 拒绝重试同一件事。 一 turn 内两次同根因失败后,turn 内反思强制模型分类失败并查文档,而非盲目重试。见 诚实门 → turn 内反思。

问:deep_explore 跑了很久,结论是「未解决 / 卡住」。 这是诚实行为,不是 bug。deep_explore 只计实质进展,并如实报告真正卡住的前沿,而非编造结论。见 深度推理。

安全

问:把它对准不可信输入 / 在生产无人值守地跑,安全吗? 暂时不。它是开发者预览；真正的隔离控制（OS 沙箱）尚未交付。当前控制是围绕可信操作者模型的纵深防御。当前执行矩阵见权限与安全；仓库里的 SECURITY-DESIGN.md 是历史设计记录，不是当前安全契约。

问:在哪报告安全问题? 经 SECURITY.md —— 不要开公开 issue。