OpenClaw 从安装到可用：把 Tools/Skills 变成“可控操控面板”，并用飞书做远程入口

OpenClaw 从安装到可用：把 Tools/Skills 变成"可控操控面板"，并用飞书做远程入口

摘要（先看结论）

先跑通最小闭环：workspace 可写 → 只开第 1 圈 Tools → exec 开审批 → 产物落盘可验收。
Tools 是权限面（能不能做），Skills 是流程面（怎么做得对）；Skill 不会新增权限，权限只在 Tools。
默认最小化：想不出今天就能验收的能力先别开；支付/下单/对外发布等不可撤回动作永远手动。
飞书当入口：新手优先用官方插件快速跑通；要强治理再走开放平台自建应用。
排障只认证据：openclaw status / openclaw models status / openclaw logs --follow / openclaw gateway status / openclaw doctor。

引言（你为什么会卡住）

不知道先配哪几项：配置项多，缺少"最短可跑闭环"。
不敢放权：Tool/Skill 边界不清，担心误触敏感动作。
没有验收：只停在对话里，没有可复查的产物与证据。

快速导航（按问题定位）

现象	看哪节	处理动作（最短）
不确定 Tools/Skills 差异，开关逻辑混乱	Tools/Skills、同心圆	先分清权限面/流程面，再做最小白名单
想先跑通最小闭环	快速上手、第 1 圈配置	workspace 可写 → 只开第 1 圈 Tools → exec 审批 → 落盘验收
web_search 不工作 / Key 不知道怎么配	web_search	用 `openclaw configure --section web` 或环境变量配置并验证
browser 能用但不稳定 / 总被"attach tab"卡住	浏览器	优先隔离浏览器（`openclaw` profile），再考虑 Relay 扩展（`chrome` profile）
Chrome 扩展要求 Gateway token，但界面打码了	浏览器（Relay）	轮换 token：写入新值 → 重启 Gateway → 扩展填新值
不回复 / 卡住 / 一直 queued(1)	排障速查	Stop → `/queue interrupt` → `/new` → 跑 `status/models/logs`
想用飞书当入口，但不想折腾开放平台	飞书入口	先用官方插件跑通私聊闭环，再按安全策略逐步放开

0. 快速上手（飞书入口，30 分钟最小闭环）

目标不是"把功能都配齐"，而是跑通一条可验收链路：飞书下发 → workspace 落盘 → 回到飞书给出可取证路径。

在机器上把 OpenClaw 跑起来：能打开 Dashboard（openclaw dashboard），并确认 workspace 可写（见 6.1）。
先只开第 1 圈 Tools：让它具备"落盘产出 + 上网取证 + exec 审批"的基本能力（见第 6 章）。
接入飞书：优先走飞书官方插件（见 9.1）；需要更强治理再走自建应用（见 9.3）。
在飞书私聊里发一条"只落盘"的任务模板（见 9.4 模板 A），要求产出到 workspace/notes/。
验收只认结果：文件落盘 + 内容含证据/风险边界 + 能复述路径与下一步，就算跑通。

1. 先搞懂：Tools 和 Skills 到底差在哪？

很多新手卡住不是因为"不会用"，而是把两件事混成了一件事：

Tools 是器官：决定 OpenClaw "能不能"做某类动作。
- 例如 read/write 能读写文件，exec 能执行命令，web_search/web_fetch 能上网，browser 能操控浏览器。
- 没开对应 Tool，就像没长手脚：Skill 再聪明也落不了地。
Skills 是教科书：教 OpenClaw "如何组合 Tools"完成某个具体场景。
- 例如 gog 负责 Google Workspace，github 负责仓库操作，obsidian/notion 负责笔记流。

一个常见误解是："装了 Skill 就新增权限"。不是。Skill 只是流程说明书，真正的权限边界在 Tools。

1.1 "在飞书里用 OpenClaw"这个例子：你至少要同时过三关

把它当成一条最小验收链路：

配置：你是否把飞书作为入口接好？（入口没通，你在飞书里发什么它都收不到）
权限：飞书侧该有的能力是否已授予？（没授权，读文档/发消息/建日程都不会放行）
运行：Gateway 是否常驻且可达？（Gateway 不在/断连，你看到的就是"不回复/queued"）

三者缺一不可。Skill 只负责"告诉你该怎么做"，不负责"替你获得权限"。

2. 同心圆架构：从核心到外围，把能力拆成 3 圈

把 25 个 Tools 和 53 个 Skills 平铺出来会非常吓人，但如果按"同心圆"去理解，决策会简单很多：

text 复制代码

第 1 圈：核心工具（先跑通）   -> 读写文件 / 执行命令 / 联网取信息
第 2 圈：进阶工具（再扩展）   -> 浏览器、记忆、多会话、自动化、消息推送
第 3 圈：知识层（只保留需要） -> 53 个官方 Skills：针对具体平台与场景的"操作手册"

你不需要一次把三圈全点亮。更稳的策略是：先把第 1 圈跑出"可验收产出"，再往外加。

2.1 workspace：不是目录，是"权限边界 + 产物归档"

很多人装完之后觉得"它会干活但我不敢让它干"，本质是没有把工作区当成边界来设计。

把 workspace 当成唯一默认读写根目录：所有产物（报告、日志、草稿、脚本）都落到这里。
把 workspace 当成"对外同步"的最小集合：你可以选择用 Git/iCloud/云盘去同步 workspace，但不要把整盘文件等价授权给 Agent。
把 workspace 当成"审计入口"：只要产物可回放（文件/日志/命令清单），你就能把自动化变成工程化。

2.2 persona：把"你是谁"和"禁区"写成固定条款

对外博客里最容易被忽略的一点是：persona 不是人设段子，而是"行为边界"。

你是谁：你的角色与目标（例如"研发负责人/客户端 TL"，追求可复现、可回滚、可证据交付）。
什么不能做：支付/下单/对外发言/不可撤回动作永远手动；任何 exec 必须审批。
产出格式：默认产出 Markdown，并包含"结论、风险、证据、下一步"四块。

2.3 搜索/浏览器：先"取证"，再"行动"

一个更稳的习惯是：先用 web_search/web_fetch 把关键依据抓回到本地（可引用、可复查），再考虑用 browser 去做交互操作。

3. 第 1 圈：核心能力（8 个 Tools）

只开这 8 个，OpenClaw 基本处于"被动响应"模式：你问它答、你让它改它改，但它不主动记忆、不主动推送、不主动编排复杂自动化。

3.1 文件操作：read / write / edit / apply_patch

read：只读
write / edit：改文件
apply_patch：应用结构化 patch（更适合代码改动）

绝大多数人的起步配置会把这 4 个全开，因为它们是"可验收产出"的基础：你至少得能写出一个文件，才能算"操控成功"。

3.2 执行与进程管理：exec / process

exec：执行任意 shell 命令（能力极大，风险也极大）
process：管理后台进程（查看列表、看输出、终止卡死任务）

这里只强调一条工程底线：exec 必须开启审批模式。

json 复制代码

{
  "approvals": {
    "exec": { "enabled": true }
  }
}

这不是"麻烦"，这是"最后一道门"。无论你担心模型误判，还是担心提示词注入，这道确认都能显著降低事故概率。

3.3 网络访问：web_search / web_fetch

web_search：搜关键词
web_fetch：抓网页内容

这对组合让 OpenClaw 具备"自己去查资料并回到你面前"的能力，几乎是所有实战工作流的底座。

3.4 Web Search 配置实战（Brave Search API Key 获取与配置）

这节只解决一个问题：让 web_search 真正能用，并且你知道它怎么计费、怎么控风险。

为什么需要 web_search
- web_search 用来找入口链接（最新文章、官网文档、Issue、Release）。
- web_fetch 用来抓正文内容（把"证据"拉回本地，落到 workspace 里复用）。
- 实战建议：搜索只做"发现"，抓取才做"沉淀"，这样能显著减少搜索次数与成本。
Brave Search API Key 获取
- 申请地址：https://api-dashboard.search.brave.com/app/dashboard
- 操作步骤（按它控制台走）：
  1. 登录后进入 API keys 页面
  2. Create API Key（建议命名 openclaw-search）
  3. 复制 Key 并妥善保存
- 安全建议：Key 视为密钥，不要粘贴进仓库、截图、群聊。
计费怎么理解（结合你截图那页）
- 常见形态是"每月赠送 credits + 超出按量付费"。
- 你截图里 Search 的单价大约是 $5 / 1000 requests，并提示每月包含 $5 credits：粗略等价于每月约 1000 次 Search 请求额度（以控制台展示与实际结算为准）。
在 OpenClaw 里怎么配（推荐走命令行/环境变量，Raw 作为兜底）
- 方式一：终端交互式配置（推荐）

bash 复制代码

openclaw configure --section web

按提示粘贴你的 API Key（不要把 Key 写进仓库、截图或群聊）。

方式二：环境变量（适合本机长期使用）

把下面这行加到 ~/.zshrc：

bash 复制代码

export BRAVE_API_KEY="BSAxxxxxxxx..."

然后让它生效并重启 Gateway：

bash 复制代码

source ~/.zshrc
openclaw gateway restart

方式三：Dashboard Raw（兜底）
1. 打开 Dashboard：openclaw dashboard
2. 左侧进入：设置 → 配置 → Raw（Raw JSON5）
3. 在 Raw 里用搜索（⌘F）查：brave / search / web
4. 找到对应字段后只改值并保存应用（必要时重启 Gateway）
- 注意：不同版本字段名可能略有差异，以你 Raw JSON5 里实际出现的字段为准，不要照抄不存在的 key。
怎么验证配置成功

text 复制代码

搜索 "OpenClaw security best practices"

能返回包含 URL 的结果，说明 web_search 已可用。

4. 第 2 圈：进阶能力（按需开启）

第 1 圈解决"能不能用"，第 2 圈解决"用得好不好"。但每多开一个 Tool，攻击面就扩大一分，所以这圈更需要按场景裁剪。

4.1 浏览器：browser / canvas / image

browser：操控浏览器（点击、填表、截图）
image：图像理解（截图/页面理解常用）

浏览器工具是典型的"价值大、风险也大"的能力：它能让 AI 真正走进网页，把"查资料"变成"完成操作"。

这里也有一条底线建议：

涉及支付/下单/转账/对外发布的最后一步，永远手动。

4.2 记忆：memory_search / memory_get

这组工具让 OpenClaw 跨会话记住信息：你常用的写作目录、偏好的输出结构、你部署环境的限制等。

工程上把它当成"长期状态"，而不是"临时对话上下文"。

4.3 多会话：sessions_*（5 个）

sessions_list：列出会话
sessions_history：会话历史
sessions_send：会话间发送消息
sessions_spawn：派生子会话/子任务
session_status：状态检查

这组工具让你把"一个大任务"拆成多条并行链路：一个做资料抓取、一个做总结输出、一个做执行验证，互不干扰。

新手建议先别开（等你第 1 圈稳定后再说）

message：外部出口，高风险（以你名义发出的内容不可撤回）
nodes：跨设备硬件能力，边界更复杂
cron：后台常驻与定时任务，容易把问题从"对话卡住"升级成"后台默默跑"
工作流/多代理类工具：收益高，但排障成本也高

5. 第 3 圈：知识层（Skills 白名单）

Skills 听起来很多，但真正与你相关的往往只有十几个。策略很简单：

不做"全家桶"
只保留与你现实场景强相关的 Skills
用 skills.allowBundled 做白名单（见第 8 章）

Bundled Skills 可能会在你系统装了对应 CLI 后自动激活，所以"我没用"不等于"它没在那儿"。

6. 第 1 圈配置：先跑通"可验收产物"（详细步骤）

第 1 圈的目标不是"功能最全"，而是"确定可用"：你给它一个任务，它能在本机落下可验收产物（文件/日志/报告），并且全程可控、可审计。

6.0 从哪里改配置（两种方式，选一个）

本文默认全程使用 Web UI（Raw）。

打开 Dashboard：openclaw dashboard
在左侧侧边栏进入：设置 → 配置
在页面底部切换到 Raw（Raw JSON5；你会看到一份完整配置）
修改对应字段后：
- 先点 Save（保存）
- 再点 Update/Apply（应用配置）
- 必要时在 Dashboard 里重启 Gateway（让新配置完全生效）

最常用的验收/排障命令（先记这五条）

bash 复制代码

openclaw status
openclaw models status
openclaw skills check
openclaw logs --follow
openclaw gateway status

科普：openclaw gateway install 是干什么的

很多新手会把 "restart / install / run" 混为一谈。记住一句话：install 是把 Gateway 装成后台常驻服务，restart 是重启这项服务，run 是在当前终端前台跑一遍。

openclaw gateway install：把 Gateway 安装为系统后台服务（macOS 是 launchd，Linux 是 systemd user service），让它不依赖你开着终端也能常驻运行，并且通常用于把"服务使用的配置/入口"对齐到你当前的 OpenClaw 安装与 profile。
openclaw gateway restart：重启后台服务，让配置变更/插件变更更确定地生效（你文里大多数"重启 Gateway"指的就是这个）。
openclaw gateway（或 openclaw gateway run）：前台启动 Gateway，适合临时调试；终端关了它就停了。

什么时候需要显式跑一次 openclaw gateway install：

你希望 Gateway 真正 24/7 常驻（例如远程入口、机器人长期在线）。
你切换了安装方式/入口（例如 npm ↔ git），或者切换了 profile，导致 openclaw gateway status 里提示 "Config (cli) / Config (service) 不一致"。这类场景通常用 openclaw gateway install --force 修复对齐。

6.1 设定 workspace（先定边界再谈动作）

workspace 是一个目录，不是文件。

你可以把它理解成 OpenClaw 的"工作台根目录"：默认情况下，所有需要落地的产物（笔记、报告、脚本、日志、临时文件）都应该写到这个目录下面，避免 AI 误触你的真实工程目录、私人目录或敏感目录。

结合你当前 macOS 环境（/Users/bytedance），我建议把 workspace 固定为：

/Users/bytedance/.openclaw/workspace

目录结构建议（你一眼能找到产物，后续也方便做归档/同步）：

notes/：总结、会议纪要、方案草稿
reports/：跑检查后的报告、诊断输出
specs/：spec.md / tasks.md / checklist.md
memory/：如果你后续开启 session-memory/沉淀类能力，用来放长期材料
tmp/：临时文件（下载的网页摘录、生成中间产物等）

你至少要明确两件事：

workspace 路径在哪里（确保不指向敏感目录）
产物落盘到哪（例如 notes/、reports/、specs/）

在 Web UI（Raw）里配置 workspace 的位置：

JSON Path：agents.defaults.workspace
建议值：/Users/bytedance/.openclaw/workspace

可直接粘贴的片段（只展示关键字段）：

json 复制代码

{
  "agents": {
    "defaults": {
      "workspace": "/Users/bytedance/.openclaw/workspace"
    }
  }
}

6.2 只打开第 1 圈 Tools（越少越稳）

原则：想不出今天就能验收的场景，一律先关。先只开这 8 个：

文件：read / write / edit / apply_patch
执行：exec / process
网络：web_search / web_fetch

示例（仅展示结构，具体字段以你实际配置为准）：

json 复制代码

{
  "tools": {
    "allow": [
      "read", "write", "edit", "apply_patch",
      "exec", "process",
      "web_search", "web_fetch"
    ]
  }
}

在 Web UI（Raw）里配置 Tools 白名单的位置：

JSON Path：tools.allow
如果你当前看到的是 tools.profile（例如 "profile": "messaging"），它表示"预设工具组合"。想按白名单精确控制时，直接删掉 profile，改成 allow 即可。

示例：把

json 复制代码

{
  "tools": { "profile": "messaging" }
}

替换为

json 复制代码

{
  "tools": {
    "allow": [
      "read", "write", "edit", "apply_patch",
      "exec", "process",
      "web_search", "web_fetch"
    ]
  }
}

6.3 exec 必须审批（第 1 圈的硬闸门）

json 复制代码

{
  "approvals": {
    "exec": { "enabled": true }
  }
}

在 Web UI（Raw）里配置 exec 审批的位置：

JSON Path：approvals.exec.enabled

6.4 第 1 圈验收：做一次"产物落盘"的任务

验收标准只认结果，不认聊天：

产物必须落在 workspace（例如 notes/openclaw-today-setup.md）
如果涉及命令执行，必须先报备命令列表，逐条确认再执行

可复制的验收任务模板：

text 复制代码

你现在要帮我完成一个可验收的最小闭环：
1) 用 web_search 找 3 篇关于 OpenClaw Tools/Skills 安全配置的文章
2) 用 web_fetch 抓取每篇的核心段落
3) 产出一份 Markdown：包含"结论（5 条）+ 风险边界（3 条）+ 我今天先开哪些 Tools/Skills（清单）"
4) 把文件写入 <YOUR_WORKSPACE>/notes/openclaw-today-setup.md
约束：
- exec 如需执行命令必须先向我展示命令并等待确认
- 不进行任何支付/登录/对外发送消息动作

7. 第 2 圈配置：把"能用"升级为"好用"（按需开启）

第 2 圈不追求全开，追求"为你的工作流补短板"。每多开一个 Tool，攻击面就扩大一分，所以按场景逐个打开，并配套写清边界。

7.0 第 2 圈怎么改配置（通用步骤）

所有第 2 圈的改动，都遵循同一个动作模板：

打开 Dashboard：openclaw dashboard
左侧进入：设置 → 配置 → Raw
找到 tools.allow，在数组里追加你要开启的 Tool 名称
保存并应用（必要时重启 Gateway）
用一个"可验收任务"验证它真的可用（产物落 workspace，不认聊天）

如果你当前还在用 tools.profile，先按第 1 圈的做法切换到 tools.allow 白名单模式，再做第 2 圈增量。

7.1 浏览器（browser/image）：两种"拿到页面"的方式

适合场景：网页查资料、截图取证、把"需要点点点的动作"变成可回放流程
安全底线：涉及支付/下单/转账/对外发布的最后一步永远手动

先把一句话讲清楚：browser-profile 不是"功能开关"，只是你要控制的浏览器来源。

lane	profile	你控制的对象	适合	你需要接受的代价
隔离浏览器	`openclaw`	OpenClaw 启动并管理的独立 Chrome（独立 user data dir）	频繁自动化、要稳定可控、要隔离风险	登录态需要在这套隔离浏览器里单独登录维护
接管现有标签页	`chrome`	你日常 Chrome 里"手动 attach 的 tab"（通过 Relay 扩展桥接）	偶尔操作现有页面、要复用当前网页上下文/登录态	需要手动 attach；扩展要配置 relay 端口与 Gateway token

参考官方文档：

7.1.1 lane 1：openclaw（隔离、OpenClaw-managed）

核心机制：OpenClaw 自己启动一套隔离 profile（默认名 openclaw），与日常 Chrome 完全分开，所以"更可控"，但也天然"不复用你日常登录态"。

在 tools.allow 里加入：browser、image，保存并应用（必要时重启 Gateway）

bash 复制代码

openclaw gateway restart

最短验收：启动 → 打开 → 截图落盘

bash 复制代码

openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw screenshot --full-page

如果能成功截图并在输出里看到落盘路径，说明隔离浏览器链路已跑通。

登录态怎么来：

需要访问登录态页面时，就在这套 openclaw 隔离浏览器里登录一次（它有自己的 user data dir）。
不要指望复用你日常 Chrome 的 cookie/session，这是隔离 lane 的收益与边界。

安全提示：

建议只在隔离 lane 登录工作需要的账号（权限最小）。
默认只走本机 loopback 控制面；不要为了"手机能访问"暴露到局域网。

7.1.2 lane 2：chrome（扩展 relay，接管现有标签页）

核心机制：Relay 扩展把"你当前 Chrome 的某个 tab"桥接给 OpenClaw。它不会启动新浏览器，也不会自动接管所有 tab，只能控制你手动 attach 的那一个/几个。

安装/加载扩展（官方推荐 unpacked 方式）

bash 复制代码

openclaw browser extension install
openclaw browser extension path

然后：

Chrome 打开 chrome://extensions
打开 Developer mode
Load unpacked，选择上一步打印出来的目录
Pin 扩展到工具栏

配置扩展 Options（只需做一次）

Relay 地址默认是 http://127.0.0.1:18792（默认端口 18792）
Gateway token 必须与 gateway.auth.token（或环境变量 OPENCLAW_GATEWAY_TOKEN）一致
如果你改了 gateway.port，Relay 端口会变成 gateway.port + 3，扩展里的 Port 也要跟着改

如果 Raw 里显示的是 __OPENCLAW_REDACTED__（token 被保护不再明文展示），直接轮换即可：

把 gateway.auth.token 改成一个你自己生成的新随机值
openclaw gateway restart
扩展填你新写进去的值

attach + 验收链路

打开要控制的页面 → 点击扩展图标 → Attach（徽标显示 ON）
CLI 验收（能看到被 attach 的 tab 就算通）：

bash 复制代码

openclaw browser --browser-profile chrome tabs

如果 tabs 列表为空，优先按这个顺序排障：没 attach → attach 的 tab 被关了 → Port 不匹配 → Token 不匹配。

7.2 记忆（memory_search/memory_get）：新手最短闭环

适合场景：偏好、决策、工程约束、常用路径、常见排障结论等"以后还会用"的信息
不建议：把密钥/Token/个人隐私/不可撤回信息当作"记忆"长期保存

先把一句话讲清楚：OpenClaw 的"记忆"不是聊天记录，它的真相是 workspace 里的 Markdown 文件 ；memory_search/memory_get 只是"在这些文件里搜/按行取证"的两把工具。官方说明：https://docs.openclaw.ai/concepts/memory

你只需要做三件事

配置：指定 workspace（可选，但建议明确）+ 开启记忆工具 + 限制文件访问只在 workspace 内
文件：准备两类记忆文件（长期 + 当日）
验收：先写入，再用 memory_search → memory_get 取证召回（不要靠感觉）

最小配置（新手推荐，可直接粘贴到 Raw）

json5 复制代码

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace"
    }
  },
  tools: {
    allow: ["memory_search", "memory_get"],
    fs: { workspaceOnly: true }
  }
}

改完建议做两步让它生效且可控：

bash 复制代码

openclaw config validate
openclaw gateway restart

记忆文件放哪（按官方默认布局）

MEMORY.md：长期精选（稳定事实、偏好、禁区）
memory/YYYY-MM-DD.md：当日要点（运行上下文、TODO、踩坑）

验收（可取证）

让 OpenClaw 写入一条稳定偏好到 MEMORY.md（或当天的 memory/YYYY-MM-DD.md）
新开一个会话只问一句："我的偏好是什么？请先 memory_search 再回答；必要时用 memory_get 展开行号范围"
把本次验收记录写入 workspace/notes/openclaw-memory-sanity.md

回滚（不想启用/担心泄露/噪声太大）

禁用记忆插件槽位并重启：

json5 复制代码

{
  plugins: {
    slots: { memory: "none" }
  }
}

进阶（先别急着上）：当你遇到"命中差/返回空/想更强语义检索"时，再去看 embedding provider 配置（入口在 agents.defaults.memorySearch）以及可选的 QMD backend（memory.backend="qmd"）。

7.3 多会话（sessions_*）：把一个大任务拆成并行链路

适合场景：一条会话做资料抓取，一条做总结，一条做执行验证，互不干扰
核心作用：把"一个聊天窗口里的长任务"拆成多个独立会话并行跑，主会话只收结果与产物路径
注意：会话越多，越需要把产物都落回 workspace，避免"只在对话里存在"

它能不能解决你说的"卡住不回复"？

能解决一部分，但不是万能钥匙：

能缓解：主会话被长任务占住（你连续发新消息时看到 queued(1)/排队），用子会话把重活搬走，主会话更容易保持"可对话、可控节奏"。
不能替代：Gateway 链路不通、模型鉴权不可用、会话状态坏掉、队列模式不合适。这些问题仍然要按 11.1 的排障手册处理（Stop / /queue interrupt / /new / openclaw status 等）。

你到底打开了什么

sessions_spawn：创建一个"新会话"去做事（把任务隔离出去）
sessions_send：给某个会话继续发指令（把任务编排成流水线）
sessions_list：列出当前活跃会话（找 sessionId）
sessions_history：拉取某个会话历史（审计/复盘/补上下文）
session_status：拿状态卡（相当于一个可取证的"现在跑到哪了"）

具体步骤（Web UI / Raw）：

在 tools.allow 里加入 5 个会话相关工具：
- sessions_list
- sessions_history
- sessions_send
- sessions_spawn
- session_status
保存并应用（必要时重启 Gateway）
验收任务（用多会话跑一个三段式流水线）：
- 会话 A：只负责 web_search/web_fetch 抓资料，落 workspace/tmp/sources.md
- 会话 B：只负责从 sources.md 写总结，落 workspace/notes/summary.md
- 会话 C：只负责把 summary.md 转成 checklist，落 workspace/specs/checklist.md

推荐配置（新手最稳）

先开"能拆分 + 能观测"的最小集合，跑顺再加：

必开：sessions_spawn、session_status
推荐：sessions_list（方便找会话）、sessions_history（方便取证）
按需：sessions_send（只有当你想把多会话做成"流水线编排"时才需要）

增量片段（只展示 tools，按需删掉 sessions_send）：

json 复制代码

{
  "tools": {
    "allow": [
      "read", "write", "edit", "apply_patch",
      "exec", "process",
      "web_search", "web_fetch",
      "sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "session_status"
    ]
  }
}

8. 第 3 圈配置：Skills 白名单（只留你真的会用的）

Skills 的原则是：只保留与你的现实场景强相关的；其余全部不激活。Bundled Skills 可能会因为你装了对应 CLI 而自动激活，所以白名单要显式写出来。

一个更适合"工程负责人日常"的最小白名单示例：

json 复制代码

{
  "skills": {
    "allowBundled": [
      "github",
      "tmux",
      "session-logs",
      "summarize",
      "clawhub",
      "healthcheck",
      "skill-creator"
    ]
  }
}

在 Web UI（Raw）里配置 Skills 白名单的位置：

JSON Path：skills.allowBundled

怎么确认现在到底哪些 Skills 可用

bash 复制代码

openclaw skills check

Ready to use：当前环境与配置下"真的能用"的 Skills
Blocked by allowlist：被白名单挡住（你需要把它加进 skills.allowBundled）
Missing requirements：缺依赖（没装 CLI / 没配 Token / 没配渠道）

想看"所有可见的 Skills 清单"（不管能不能用）：

bash 复制代码

openclaw skills list

想看某个 skill 细节（它需要什么依赖、做什么）：

bash 复制代码

openclaw skills info <skill-name>

9. 飞书作为远程入口：先选接入路，再谈权限治理

飞书的价值不是"更好聊天"，而是把 OpenClaw 变成一种"随时可触达的远程入口"，并天然带着你工作里最常见的上下文（群聊、文档、日程、多维表格）。对国内用户来说，它也通常比 Telegram 这类海外入口更容易上手（中文界面与文档、生态更集中）。但入口一旦打通，风险也会指数级上升，所以要把它当成一条需要治理的生产链路，而不是玩具。

9.1 先选接入路线（两条路，不是先后步骤）

路线	适合谁	关键收益	你需要接受的代价
方案 A：飞书官方插件（推荐新手）	想最快在飞书里把 Agent 跑起来	上手最省事；中文生态；能以你的身份调用飞书能力（读群聊/文档、写改文档、发消息、日程、多维表格等）	你的飞书身份与权限会进入自动化链路，必须更严格收敛 Tools 与对外出口
方案 B：开放平台自建应用（更可控）	需要明确权限/事件/群策略治理	权限与策略完全可控；更适合团队/企业治理	配置步骤多，需要维护 App ID/App Secret 与事件订阅

方案 A 的完整接入步骤可参考飞书社区文档（按它的流程操作即可）：https://larkcommunity.feishu.cn/wiki/LDmXwEVhJitBa5kU0mjc16VKneb

9.2 一句话安全策略（强制）

飞书只负责下发任务，不直接放大权限：工具权限仍由 Tools 控制。
exec 永远审批：任何命令执行前必须把命令原样发出来，等人确认。
群聊默认 deny-by-default：groupPolicy=allowlist 且 requireMention=true。
私聊默认 pairing：陌生人先配对，避免"被加好友就能操控机器"。

9.3 方案 B：自建应用的最短步骤（按官方口径）

前置：先在飞书开放平台创建企业自建应用，拿到 App ID / App Secret，并完成机器人能力、事件订阅（长连接/WS）与必要权限（如 im.message.receive_v1）。

在 Web UI（Raw）里写入飞书通道配置（只展示关键字段）：

json 复制代码

{
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "<APP_ID>",
      "appSecret": "<APP_SECRET>",
      "connectionMode": "websocket",
      "dmPolicy": "pairing",
      "groupPolicy": "allowlist",
      "requireMention": true
    }
  }
}

在 Web UI（Raw）里配置飞书通道的位置：

JSON Path：channels.feishu

上述步骤与字段名参考火山方舟官方 OpenClaw 接入文档：

https://www.volcengine.com/docs/82379/2183190?lang=zh

9.4 飞书里下发任务的"正确姿势"：三种高复利模板

模板 A（最稳）：只让它产出文件

text 复制代码

请在你的 workspace 内生成一份报告：notes/openclaw-runbook.md
内容包括：
1) 我今天启用的 Tools 白名单（以及为什么）
2) 我今天启用的 Skills 白名单（以及为什么）
3) 风险边界（至少 5 条，必须包含 exec 审批、对外发言/不可撤回手动）
约束：
- 不执行任何命令；如确需执行，先把命令原样发我确认
- 不进行任何登录/支付/对外发送消息动作

模板 B（效率高）：跑检查/跑脚本，但必须先报备命令

text 复制代码

目标：对指定仓库做一次"可复现检查"并输出 Markdown 报告。
仓库路径：<REPO_PATH>
要求：
1) 先列出你准备执行的命令列表（不要执行）
2) 我确认后再逐条执行
3) 把结果写入 workspace/reports/<YYYYMMDD>-repo-health.md

模板 C（工程交付）：用 Spec 锁住目标与证据

text 复制代码

目标：把我的需求写成 3 个文件：spec.md / tasks.md / checklist.md，并放到 workspace/specs/<TOPIC>/
约束：
- checklist 必须包含：可观测证据（截图/日志/测试报告）与回滚方案
- 任何命令执行前必须人工确认

10. 模型与计费：火山方舟 Coding Plan 的三个坑位（只讲关键）

如果你使用火山方舟 Coding Plan，配置时只盯三项：API Key / Base URL / Model Name，其中最常见的坑是 Base URL 填错导致"不走套餐、产生额外费用"。

Anthropic 兼容：https://ark.cn-beijing.volces.com/api/coding
OpenAI 兼容：https://ark.cn-beijing.volces.com/api/coding/v3
不要用：https://ark.cn-beijing.volces.com/api/v3

参考火山方舟官方说明：

https://www.volcengine.com/docs/82379/1928261?lang=zh

11. 排障速查（按现象定位）

把排障当成"运行手册"，而不是"玄学"。建议你先看三件套：status / logs / gateway status。

11.1 "不回复 / 卡住 / 一直 queued(1)"（最常见）

你描述的"像卡住一样不回复"，通常不是"提示词没写对"，而是下面三类问题之一：队列/会话被卡住、Gateway 链路不通、模型/鉴权不可用。先按最短闭环排：

先把当前卡住的 run 终止掉（否则新消息只会排队）
- Web UI 里看到 queued(1)：先点 Stop（中断当前 run）。
- 聊天里也可以直接发"stop / interrupt / abort / esc"（要作为单独一条消息发出去）。
把队列模式从 collect 切走（避免"永远在等更多消息"）
- 在当前聊天里发 /queue interrupt：直接打断当前 run，马上处理新消息。
- 或发 /queue followup：一条一条处理，适合你连续发多条指令的场景。
如果怀疑会话状态坏了：强制新开会话
- 发 /new 或 /reset（单独一条消息）。
- 典型触发：长时间对话后、工具 schema 更新后、你频繁打断/重试后。
在 Gateway 所在机器上跑"官方三件套"，只认证据

bash 复制代码

openclaw status
openclaw models status
openclaw logs --follow

status：看 Gateway 是否可达、会话/agent 是否正常。
models status：看模型鉴权是否就绪（很多"无回复"其实是没拿到可用凭证/被限流/模型不可用）。
logs --follow：看消息有没有进来、卡在模型请求还是卡在工具执行。

看 Gateway 服务状态（尤其是"看着在跑但就是不回"）

bash 复制代码

openclaw gateway status

如果你看到类似 "Runtime: running 但 RPC probe 失败"：说明服务可能活着，但实际不可用，优先按日志提示修复，再 openclaw gateway restart。
如果你看到 "Config (cli) / Config (service) 不一致"（常见于切换 profile、npm ↔ git 安装方式后）：用 openclaw gateway install --force 让服务入口对齐，再重启。

最后兜底：让 Doctor 做一次自动修复

bash 复制代码

openclaw doctor

补充：如果你是"把 Gateway 装成后台服务"运行（gateway install），但发现"模型 Key 明明在终端里有，服务里却没"，通常是服务不继承你 shell 的环境变量。更稳的做法是把必要 Key 放进 ~/.openclaw/.env，或按官方文档启用 shell env import，再重启 Gateway。

上述命令与排障思路对应官方 FAQ 的"First 60 seconds if something's broken / logs / doctor / queue mode"说明：https://docs.openclaw.ai/start/faq

11.2 飞书机器人"不回复"

优先级从高到低：

权限/发布：应用权限是否审批通过，版本是否已发布可用
事件订阅：是否选择了长连接/WS，是否订阅 im.message.receive_v1
机器人是否在会话里：群聊需拉进群；若开启 requireMention 需要 @ 才响应
OpenClaw 侧策略是否拦截：dmPolicy=pairing 未配对、groupPolicy=allowlist 未加白名单
是否重启网关：安装插件/改配置后通常需要 openclaw gateway restart

更完整的排障清单见：

https://www.volcengine.com/docs/82379/2183190?lang=zh

12. 常见问题（FAQ）

12.1 装了 Skill 会改变 OpenClaw 的权限吗？

不会。Skill 只是说明书，真正的权限由 tools.allow 控制。

12.2 为什么强烈建议 exec 开审批？

因为 exec 的能力边界是"任意命令"。审批是你在不可控情况下的最后一道防线。

12.3 OpenClaw 和 ChatGPT 的区别是什么？

ChatGPT 更像"对话工具"，OpenClaw 更像"对话之后还能继续干活的 Agent"：它能把对话变成文件、任务、自动化流程，并落到你的系统里。

附录 A：25 个 Tools 完整清单（含风险）

层级	Tool	功能	风险
1	read	读取文件	低
1	write	写入文件	中
1	edit	结构化编辑	中
1	apply_patch	应用 patch	中
1	exec	执行命令	极高
1	process	管理进程	中
1	web_search	网络搜索	低
1	web_fetch	获取网页	中
2	browser	浏览器操作	高
2	canvas	可视化工作区	低
2	image	图片分析	低
2	memory_search	搜索记忆	中
2	memory_get	获取记忆	中
2	sessions_list	列出 session	低
2	sessions_history	会话历史	中
2	sessions_send	发送消息	高
2	sessions_spawn	启动子 Agent	高
2	session_status	状态检查	低
2	message	跨平台消息	极高
2	nodes	硬件控制	极高
2	cron	排程任务	高
2	gateway	Gateway 管理	高
2	agents_list	列出 Agent	低
Ext	llm_task	工作流 LLM 步骤	中
Ext	lobster	工作流引擎	中