先看对的文件

文档入口与操作入口

这个仓库把当前状态文档和目标设计草案放在了一起。官网应该优先把读者引到真正定义已发布行为的文件上。

真实依据

在把任何设计说明当成产品承诺之前，先打开这些文件。

Root README

当前版本边界、快速开始、runtime profile、API 语义和可选宿主 daemon，都以这里为准。

打开 README

README.zh-CN

项目主 README 的中文版本，适合中文团队做内部说明或 onboarding。

打开中文 README

docs/README.md

说明哪些 docs 描述的是已发布行为，哪些仍然是路线图或设计背景。

打开文档状态说明

config.example.yaml

本地启动 runtime 时最实用的配置参考，包括 auth、models 和 hosts。

打开示例配置

Quick start

最干净的路径仍然是 README 那条：复制配置、设置环境变量、跑测试、再启动服务。

cp config.example.yaml local.yaml
export HOPCLAW_AUTH_TOKEN=change-me
export OPENAI_API_KEY=your-key
make run CONFIG=./local.yaml

Runtime config

把宿主能力和安全 profile 放进配置，不要埋进 prompt 里。

runtime:
  profile: desktop
  audit:
    enabled: true

hosts:
  browser:
    enabled: true
    base_url: http://127.0.0.1:9223
    auth_token: ${HOPCLAW_BROWSER_TOKEN}

skills:
  install_policy: ask

API 快速参考

本地 operator console 本质上也是建立在这些端点之上的。

MethodEndpoint说明

GET/healthz健康检查，适合监控或本地冒烟测试。

GET/runtime/tools列出当前环境下运行时可见的工具。

POST/runtime/runs创建并入队新的 run。

GET/runtime/runs/:id查询 run 的状态、结果和相关细节。

GET/runtime/approvals当 run 因确认而暂停时，列出待审批项。

POST/runtime/approvals/:id/resolve批准或拒绝审批单，并让暂停的 run 继续。

后续值得看的文档

先搞清发布边界，再继续往下读这些文档，效率最高。

skills-v2-compat.md

SKILL.md 与 ClawHub 风格 bundle 的兼容契约。

extension-guide.md

扩展点、store、hooks 以及策略集成的长篇参考。

web-ui-plan.md

基于当前 HTTP API 继续扩展 Web UI 的规划文档。