OpenClaw 设计与实现

附录 D：开发者速查手册

作者 杨艺韬 · 2,809 字 · 发布于 · 更新于

本附录为 OpenClaw 开发者和运营者提供日常最常用的配置项、CLI 命令和关键文件的快速参考。所有条目对照 openclaw/openclaw v2026.3.31（commit 213a704）核实。

D.1 关键配置项 Top 10

以下是最常调整的 10 个配置项。配置文件是 ~/.openclaw/openclaw.json——扩展名是 .json，但按 JSON5 解析（允许注释和尾逗号）。完整清单见附录 A。

# 配置项 默认值 说明 参考章节
1 agents.defaults.model 未配置时 anthropic/claude-opus-4-6 默认模型，字符串 "provider/model" 或 { primary, fallbacks } 第 4 章
2 agents.defaults.contextTokens 随模型 上下文窗口封顶（token 数） 第 5 章
3 gateway.port 18789 Gateway 监听端口（其余端口由它派生） 第 3 章
4 gateway.bind "loopback" 绑定模式：auto / lan / loopback / tailnet / custom 第 3 章
5 gateway.auth.mode "token" 认证模式：none / token / password / trusted-proxy 第 13 章
6 tools.profile 引导时写入 "coding" 工具基线：minimal / coding / messaging / full 第 10 章
7 tools.exec.security 按 host 分流（沙箱 deny，网关/节点 allowlist） 命令执行安全级别：deny / allowlist / full；host=sandbox 时命令直接在容器里执行，不走档位与审批 第 10、13 章
8 gateway.reload.mode "hybrid" 热重载模式：off / restart / hot / hybrid 第 3 章
9 logging.level "info" 文件日志级别（--verbose 只影响控制台，不影响它） 第 15 章
10 cron.enabled 启用（只有显式写 false 才关闭） 是否启用定时任务调度器 第 12 章

快速示例

// ~/.openclaw/openclaw.json —— 最小可用配置（JSON5，可写注释）
// 前提：主模型有 Anthropic 凭证（onboard 配好或导出 ANTHROPIC_API_KEY），并已导出 OPENCLAW_GATEWAY_TOKEN；
// 引用的环境变量未设置时，配置加载直接报错（MissingEnvVarError）
{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["openai/gpt-5.4"],
      },
    },
  },
  gateway: {
    mode: "local", // 缺了它，openclaw gateway run 会拒绝启动
    port: 18789,
    bind: "loopback",
    auth: { mode: "token", token: "${OPENCLAW_GATEWAY_TOKEN}" },
  },
  tools: {
    profile: "coding",
    exec: { security: "allowlist" },
  },
}

D.2 CLI 命令速查

D.2.1 Gateway 管理

命令 说明
openclaw gateway run 前台运行 Gateway
openclaw gateway install 注册为系统服务（launchd / systemd / schtasks）
openclaw gateway start / stop / restart 启动 / 停止 / 重启已安装的系统服务（未安装时 start 拉不起网关，先 install）
openclaw gateway status 服务状态 + RPC 探测（--deep 扫描系统级服务）
openclaw gateway probe 可达性 + 发现 + 健康 + 状态汇总
openclaw gateway health 拉取网关健康信息
openclaw gateway call <method> 直接调用一个 Gateway RPC 方法
openclaw gateway usage-cost --days 30 从会话日志汇总用量成本
openclaw logs --follow 跟随查看网关文件日志（顶层命令，不在 gateway 下）

D.2.2 配置与引导

命令 说明
openclaw onboard 交互式引导（网关、工作区、认证、通道、技能）
openclaw onboard --install-daemon 引导的同时安装网关系统服务——README 推荐的快速上手一步到位写法
openclaw setup 只初始化配置与 Agent 工作区
openclaw configure 交互式配置凭证 / 通道 / 网关 / Agent 默认值
openclaw config get <path> / set / unset 非交互式读写单个配置项
openclaw config file 打印当前生效的配置文件路径
openclaw config schema 导出配置 JSON Schema
openclaw config validate 校验配置文件

D.2.3 Agent 与会话

命令 说明
openclaw tui 启动 TUI 交互界面
openclaw tui --session <key> 指定会话进入 TUI
openclaw agent --agent <id> -m "<text>" 通过 Gateway 跑一个 Agent 回合；须用 --agent、--session-id 或 --to 之一选定会话，只给 -m 会报错
openclaw agents list 列出已配置的 Agent（--bindings 附带路由绑定）
openclaw sessions 列出已存储的会话（--active <分钟> 过滤，--json 输出 JSON）
openclaw sessions cleanup --dry-run 预览会话存储维护动作

D.2.4 诊断与安全

命令 说明
openclaw doctor 依次运行 25 个核心步骤（多数是检查）并给出修复建议
openclaw doctor --fix 自动应用推荐修复（--repair 同义）
openclaw doctor --non-interactive 无提示运行（仅安全迁移）
openclaw security audit 执行安全审计
openclaw security audit --fix 审计并自动修复（收紧默认值 + 修正文件权限）
openclaw security audit --deep 深度审计（尽力探测运行中的网关）
openclaw security audit --json 机器可读输出

openclaw doctor 本身是交互式流程，没有 --json；需要结构化输出请用 status / health / security audit 的 --json。

D.2.5 技能管理

命令 说明
openclaw skills list 列出所有技能（--eligible 只看依赖齐全的，-v 显示缺失项）
openclaw skills info <name> 查看某个技能的详情
openclaw skills check 哪些技能就绪、哪些缺依赖
openclaw skills search <query> 搜索 ClawHub 技能
openclaw skills install <slug> 从 ClawHub 安装到当前工作区（--version、--force）；这条下载路径不经本地安全扫描，启用前先自行审阅
openclaw skills update --all 更新所有 ClawHub 来源的技能

包管理器（brew / node / go / uv / download）出现在 SKILL.md 的 metadata.openclaw.install 里，用于安装技能所依赖的二进制，不是 skills install 的命令行开关。

D.2.6 备份与维护

命令 说明
openclaw backup create 在当前目录生成带时间戳的备份归档（当前目录位于被备份的目录内时改写到 home）
openclaw backup create --output <path> 写入指定的归档路径或已有目录
openclaw backup create --verify 生成后立即校验归档清单
openclaw backup create --only-config 只备份当前生效的配置文件
openclaw backup verify <archive> 单独校验一个归档

CLI 只有 create 与 verify，没有 restore 子命令——恢复是手工解包回状态目录。

D.2.7 TUI 斜杠命令

命令 说明 分类
/agent [id] 切换 Agent（不带参数则打开选择器） 导航
/agents 打开 Agent 选择器 导航
/session [key] / /sessions 切换会话 / 打开会话选择器 导航
/model [id] / /models 切换模型 / 打开模型选择器 模型控制
/think <level> 设置思考档位（可选值随 Provider 与模型动态变化） 模型控制
/fast <status|on|off> 开关快速模式 模型控制
/status 显示网关状态摘要 可观测性
/verbose <on|off> 详细输出开关 可观测性
/reasoning <on|off> 推理过程显示开关 可观测性
/usage <off|tokens|full> 每条回复后的用量行 可观测性
/elevated <on|off|ask|full>（别名 /elev） 提权级别 安全
/activation <mention|always> 群聊激活方式 安全
/abort 中止当前运行 流控
/new / /reset 重置会话 流控
/btw <问题> 问一个临时旁支问题，不写入后续会话上下文 流控
/settings / /help / /exit（/quit） 设置 / 帮助 / 退出 其他

另外两个前缀不是斜杠命令但同样重要：!<命令> 在你本机执行 Shell（首次使用需在会话内授权），普通文本则直接发给 Agent。

D.3 关键文件速查

D.3.1 用户工作区文件

这些文件放在工作区根目录（默认 ~/.openclaw/workspace/），由你维护。文件名常量定义在 src/agents/workspace.ts：

文件 用途 是否必需 参考章节
SOUL.md Agent 的身份与人格定义——"你是谁" 推荐 第 2、6 章
AGENTS.md Agent 的工作规范与流程——"你的工作流程" 推荐 第 2、6 章
USER.md 用户画像——"你在帮谁" 推荐 第 2 章
TOOLS.md 本地工具配置备注（设备名、SSH 地址等） 可选 第 10 章
IDENTITY.md Agent 自我认同（名字、emoji、头像） 可选 第 6 章
MEMORY.md（或 memory.md） Agent 的长期记忆 可选 第 5 章
BOOTSTRAP.md 新工作区首次运行时的引导模板（"你是谁"的初次对话，完成后按模板提示删除） 可选 —
BOOT.md Gateway 启动时由内置钩子 boot-md（gateway:startup 事件）交给 Agent 执行的一次性指令；常量在 src/gateway/boot.ts 可选 第 3 章
HEARTBEAT.md 心跳检查清单 可选 第 12 章
skills/*/SKILL.md 自定义技能定义 可选 第 16 章

单个工作区自举文件的读取上限是 2 MB（MAX_WORKSPACE_BOOTSTRAP_FILE_BYTES）。

D.3.2 系统文件位置

内容 位置 说明
主配置文件 ~/.openclaw/openclaw.json 按 JSON5 解析；OPENCLAW_CONFIG_PATH 可覆盖
状态目录 ~/.openclaw/ OPENCLAW_STATE_DIR 可覆盖；--profile <name> 切到 ~/.openclaw-<name>
会话存储 ~/.openclaw/agents/<agentId>/sessions/sessions.json 路径由 session.store 决定
运行日志 /tmp/openclaw/openclaw-YYYY-MM-DD.log 按天滚动，不在 ~/.openclaw 下；logging.file 可覆盖
工作区 ~/.openclaw/workspace/ agents.defaults.workspace 可覆盖
扩展/插件 ~/.openclaw/extensions/ 另可通过 plugins.load.paths 追加
环境变量文件 ~/.openclaw/.env 与当前目录 .env 均不覆盖已存在的进程环境变量

D.3.3 技能文件结构

skills/
  my-skill/
    SKILL.md          # 技能定义（必需）
    references/       # 参考资料（可选）
    scripts/          # 辅助脚本（可选）

SKILL.md 的关键字段：

---
name: my-skill
description: "一句话描述。Use when: ... NOT for: ..."   # 会进入系统提示的技能目录
user-invocable: true              # 是否生成斜杠命令（默认 true）：名字规范化为 /my_skill，也可用 /skill my-skill
disable-model-invocation: false   # 是否对模型隐藏（默认 false）
metadata:
  openclaw:
    emoji: "🔧"
    os: [darwin, linux]           # 平台限制
    requires:
      bins: [git]                 # 必需二进制
      env: [MY_API_KEY]           # 必需环境变量
---

# 技能名称

具体的操作指南和流程说明……

注意 frontmatter 里的调用控制字段用的是连字符形式（user-invocable / disable-model-invocation），解析见 src/agents/skills/frontmatter.ts。

D.4 常见错误速查

错误消息 解决方案
Gateway not running 已装服务：openclaw gateway start；未装：openclaw gateway install（装完即启动）或前台 openclaw gateway run；一步到位用 openclaw onboard --install-daemon
ECONNREFUSED 127.0.0.1:18789 检查端口占用：openclaw gateway status --deep、lsof -i :18789
Config invalid 按提示运行 openclaw doctor --fix（doctor/logs/health/status 不受配置错误阻断）
401 Unauthorized（Provider） 重跑 openclaw onboard 或 openclaw doctor 修复凭证
429 Too Many Requests 等待冷却，或配置 agents.defaults.model.fallbacks 走备用模型
Context overflow — … / Context limit exceeded … 系统已先自动压缩重试；仍报错就 /new 开新会话或缩短输入，必要时手动改用更大窗口的模型（降级链不会因溢出自动换模型）；压缩阶段溢出按提示调大 agents.defaults.compaction.reserveTokensFloor
Blocked hostname or private/internal/special-use IP address SSRF 防护拦截，检查目标是否为私有 / 链路本地地址
Pairing required 在设备上重新完成配对
multiple gateway processes are listening on port ... openclaw gateway status --deep 后清理多余进程再重启
ENOSPC 清理 /tmp/openclaw/ 下的滚动日志（超 24 小时的会自动清理，但突发写入可能来不及）

D.5 成本观测

本专栏不提供"每次多少 token、每月多少美元"的估算表——这类数字完全取决于你的提示体积、工具输出量、对话长度和所选模型的单价，脱离具体负载没有意义。请直接测量：

openclaw gateway usage-cost --days 30          # 近 30 天的用量成本汇总
openclaw gateway usage-cost --days 7 --json    # 机器可读，便于接入自己的看板

在 TUI 里则可以用 /usage tokens 或 /usage full 打开每条回复后的用量行，实时观察单轮开销。

三个影响成本的主要杠杆（前两项机理见第 16 章与第 5 章）：技能按需加载让技能数量不再线性推高常驻上下文；上下文压缩在历史逼近窗口时把它摘要收拢，不让它无限增长；prompt caching 按前缀匹配（Anthropic 官方文档：缓存命中要求断点之前的提示逐字相同），前缀里有一处每轮都变的内容（例如时间戳），其后的缓存全部作废。

提示：本手册为快速参考用途。各配置项和命令的完整说明，请参考对应章节与附录 A（配置速查表）；仓库内 docs/gateway/configuration-reference.md 是配置字段的权威出处。