第五章：Agent 配置与 CLI 参考

openclaw.json 完整说明、Agent 创建配置、workspace 目录结构、CLI 速查手册。

本章概览

在这一章中，你将了解：

openclaw.json 配置文件的格式、位置和完整字段说明
如何创建和配置 Agent（单 Agent / 多 Agent / 路由绑定）
workspace 目录的结构和核心文件的作用
CLI 常用命令速查（按使用场景分类）

本章定位

本章是偏向动手操作和查阅的参考手册。建议先跟着前几章把 OpenClaw 跑起来，遇到想深入配置的地方再回来查。

5.1 openclaw.json 配置文件

文件位置与格式

OpenClaw 的所有配置都在一个文件里：

~/.openclaw/openclaw.json

这个文件使用 JSON5 格式（不是普通 JSON），支持注释和末尾逗号：

json5

// ~/.openclaw/openclaw.json
// 这是注释 ✓
{
  identity: {
    name: "Clawd",   // 不需要给 key 加引号 ✓
    emoji: "🦞",      // 末尾逗号合法 ✓
  },
  agent: {
    workspace: "~/.openclaw/workspace",
  },
}

Schema 验证很严格

OpenClaw 在启动时对配置文件做严格的 Schema 检查。只要有一个未知字段，Gateway 就会拒绝启动。 没有警告模式，没有降级处理。

安全编辑流程：

bash

# 1. 先备份
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak

# 2. 编辑文件

# 3. 验证语法
openclaw doctor --fix

配置作用域

作用域	位置	作用范围
用户配置（推荐）	`~/.openclaw/openclaw.json`	当前用户所有项目
项目配置	`.openclaw.json`（项目目录）	仅当前工作目录
环境变量覆盖	`OPENCLAW_CONFIG_PATH=...`	指向任意路径

顶层配置结构总览

json5

{
  // ── 由向导写入，一般不要手动改 ──────────────
  meta: { lastTouchedVersion: "...", lastTouchedAt: "..." },

  // ── 身份信息 ────────────────────────────────
  identity: { name: "Clawd", emoji: "🦞" },

  // ── Gateway 网络配置 ─────────────────────────
  gateway: { port: 18789, bind: "loopback", ... },

  // ── Agent 配置（核心） ────────────────────────
  agents: { defaults: { ... }, list: [ ... ] },

  // ── 模型 Provider ────────────────────────────
  models: { mode: "merge", providers: { ... } },

  // ── 认证与 failover ──────────────────────────
  auth: { profiles: { ... }, order: { ... } },

  // ── 消息渠道 ─────────────────────────────────
  channels: { telegram: { ... }, discord: { ... } },

  // ── 多 Agent 路由规则 ─────────────────────────
  bindings: [ { agentId: "...", match: { ... } } ],

  // ── 会话策略 ─────────────────────────────────
  session: { dmScope: "per-channel-peer", ... },

  // ── 工具 / 定时任务 / 沙盒 ───────────────────
  tools: { ... },
  cron: { enabled: true },
  sandbox: { mode: "non-main" },

  // ── 日志 / 更新 ──────────────────────────────
  logging: { level: "info" },
  update: { channel: "stable" },
}

gateway 节

控制 Gateway 的监听地址、端口和认证：

json5

gateway: {
  port: 18789,
  mode: "local",

  // loopback = 只监听 127.0.0.1（推荐）
  // all      = 监听 0.0.0.0（必须配 auth.token）
  bind: "loopback",

  auth: {
    mode: "token",
    token: "your-random-token",
    allowTailscale: true,   // Tailscale IP 免 token
  },

  controlUi: {
    enabled: true,
  },

  // hot    = 尽量热更新，不能热更新的字段也不重启（可能悄悄失效）
  // hybrid = 能热更新就热更新，必须重启的字段触发重启（推荐）
  // restart = 任何改动都重启
  reload: "hybrid",
}

公网部署必读

在 VPS 上部署时，绝对不要 把 bind 改成 "all" 却不配 auth.token。已有泄露 API Key 和对话历史的真实案例。推荐用 Tailscale 或 SSH 隧道做远程访问。

models 节

配置 LLM Provider 和模型：

json5

models: {
  mode: "merge",  // merge = 与内置列表合并；replace = 完全替换

  providers: {
    anthropic: {
      apiKey: "${ANTHROPIC_API_KEY}",  // 用环境变量引用，不要硬写密钥
    },
    openai: {
      apiKey: "${OPENAI_API_KEY}",
    },
    deepseek: {
      apiKey: "${DEEPSEEK_API_KEY}",
    },

    // Ollama 本地模型
    ollama: {
      baseUrl: "http://localhost:11434",
      apiKey: "ollama-local",
      api: "openai-completions",
      models: [
        {
          id: "ollama/qwen2.5",
          name: "Qwen 2.5",
          contextWindow: 32768,
          maxTokens: 8000,
          cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
        },
      ],
    },
  },
}

auth 节（多账号 failover）

为同一 Provider 配置多个认证档案，自动在限流时切换：

json5

auth: {
  profiles: {
    // Claude 订阅（OAuth，不消耗 API 额度）
    "anthropic:subscription": { mode: "oauth", email: "your@email.com" },
    // Claude API Key（按量计费）
    "anthropic:api": { mode: "api_key", apiKey: "${ANTHROPIC_API_KEY}" },
  },
  // 优先用订阅，订阅限流后自动切到 API Key
  order: {
    anthropic: ["anthropic:subscription", "anthropic:api"],
  },
}

session 节

控制会话隔离策略：

json5

session: {
  // "main"                  = 所有 DM 共享一个会话（单用户默认）
  // "per-peer"              = 按发送者隔离
  // "per-channel-peer"      = 按渠道+发送者隔离（多用户场景推荐）
  // "per-account-channel-peer" = 最细粒度
  dmScope: "per-channel-peer",

  reset: {
    mode: "daily",    // none | daily | idle
    atHour: 4,        // UTC 凌晨 4 点重置
    idleMinutes: 120, // idle 模式下闲置多少分钟重置
  },

  // 跨渠道绑定同一用户身份
  identityLinks: {
    alice: ["telegram:123456", "discord:987654"],
  },
}

多用户场景务必配置

如果多个用户都能给你的 Agent 发消息，必须把 dmScope 改为 "per-channel-peer"。否则所有人共享同一个会话，A 的对话内容 B 也能看到。

热更新说明

大多数配置改动会被 Gateway 实时感知并应用，无需重启。只有以下情况需要手动重启：

需要重启	可以热更新
`gateway.port` / `gateway.bind`	模型配置 (`agents.*.model`)
沙盒 Docker 镜像或网络配置	渠道策略 (`allowFrom`、`requireMention`)
插件安装 / 卸载	定时任务、心跳间隔
`gateway.reload` 字段本身	工具配置、会话设置

5.2 Agent 创建与配置

单 Agent 配置（最常用）

绝大多数个人用户只需要一个 Agent，在 openclaw.json 里直接配置 agent（单数）：

json5

{
  agent: {
    workspace: "~/.openclaw/workspace",

    model: {
      primary: "anthropic/claude-sonnet-4-5",
      // 主模型限流时自动切换到备用
      fallbacks: [
        "deepseek/deepseek-chat",
        "openai/gpt-4o-mini",
      ],
    },

    // 心跳：每 30 分钟 Agent 主动向上次对话的人发送检查
    heartbeat: {
      every: "30m",
      mode: "next-heartbeat",
    },

    // 工具权限白名单/黑名单
    tools: {
      allow: ["exec", "read", "write", "edit", "browser"],
      deny: [],
    },
  },
}

通过 CLI 交互式创建

不想手写 JSON，用命令行向导：

bash

# 引导式初始化（最推荐，覆盖所有常见设置）
openclaw onboard

# 只跑配置向导（不重做渠道配对）
openclaw configure

# 非交互式创建（适合脚本 / Docker）
openclaw onboard --non-interactive

多 Agent 配置

需要让不同渠道 / 群组对应不同 Agent（比如工作和私人分开）：

json5

{
  agents: {
    // defaults 是所有 Agent 的基础配置
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: { primary: "anthropic/claude-sonnet-4-5" },
      heartbeat: { every: "30m" },
    },

    // list 中的每个 Agent 可以覆盖 defaults 中的字段
    list: [
      // 默认 Agent（没有规则匹配时使用）
      { id: "main", default: true },

      // 工作 Agent：独立 workspace，更强的模型
      {
        id: "work",
        workspace: "~/.openclaw/workspace-work",
        model: { primary: "anthropic/claude-opus-4-6" },
      },

      // 家庭 Agent：不同的个性设定（通过 workspace/SOUL.md 区分）
      {
        id: "home",
        workspace: "~/.openclaw/workspace-home",
      },
    ],
  },

  // 路由规则：把特定渠道 / 群组指向特定 Agent
  bindings: [
    // Telegram 里的工作群 → 工作 Agent
    {
      agentId: "work",
      match: {
        channel: "telegram",
        groupId: "-1001234567890",
      },
    },
    // WhatsApp 业务账号 → 工作 Agent
    {
      agentId: "work",
      match: {
        channel: "whatsapp",
        accountId: "business",
      },
    },
    // 其余所有消息 → 默认 main Agent（无需显式配置，default: true 自动处理）
  ],
}

路由匹配优先级

当一条消息到达时，OpenClaw 按以下顺序匹配路由规则：

1. match.peer        — 精确匹配某个对话 / DM（最高优先级）
2. match.guildId     — 匹配整个 Discord 服务器 / Slack 工作区
3. match.groupId     — 匹配特定群组
4. match.accountId   — 匹配特定 Bot 账号
5. default: true     — 兜底（最低优先级）

用 CLI 管理多 Agent

bash

# 查看所有 Agent
openclaw agents list

# 交互式添加新 Agent
openclaw agents add

# 非交互式添加
openclaw agents add --id "work" --workspace ~/work-agent --non-interactive

# 查看路由绑定规则
openclaw agents acp list

# 添加绑定（把某个 Telegram 群路由到 work Agent）
openclaw agents acp add --agent work --channel telegram --group-id -1001234567890

# 删除绑定
openclaw agents acp remove --agent work --channel telegram

# 直接向 Agent 发送消息（不经过渠道，调试用）
openclaw agent --message "今天有什么需要处理的？"

# 删除 Agent
openclaw agents delete --id work

重要限制：只能在 defaults 里配置的字段

以下字段只能写在 agents.defaults，写在具体 Agent 的配置里会被静默忽略：

compaction（上下文压缩策略）
contextPruning（上下文裁剪策略）
浏览器默认配置

如果你发现某个 Agent 配置不生效，用 openclaw doctor --fix 检查是否有误放的字段。

5.3 workspace 目录详解

workspace 是什么？

workspace 是 Agent 的工作主目录，也是它的"长期记忆仓库"：

文件工具（read、write、edit）的默认操作目录
目录里的文件会被自动注入到系统提示词（System Prompt）中，给 Agent 持久化上下文
类似于你给助理准备的"参考资料文件夹"

注意：workspace 和 ~/.openclaw/ 是两个不同的东西：

~/.openclaw/                  ← 系统目录（配置、凭证、会话）
├── openclaw.json             ← 配置文件（不在 workspace 里）
├── credentials/              ← OAuth Token、API Key（不在 workspace 里）
├── agents/                   ← 各 Agent 的会话数据
└── workspace/                ← 默认 workspace（在这里）
    ├── AGENTS.md             ← Agent 行为规范
    ├── SOUL.md               ← Agent 个性与价值观
    ├── IDENTITY.md           ← Agent 的自我认知
    ├── USER.md               ← 关于你（用户）的背景信息
    ├── TOOLS.md              ← 工具使用规范
    ├── HEARTBEAT.md          ← 心跳任务配置
    └── memory/               ← 长期记忆（Markdown 文件）
        ├── 2026-01-10.md
        ├── 2026-01-11.md
        └── ...

默认位置与自定义

默认：~/.openclaw/workspace

在 openclaw.json 中修改：

json5

{
  agent: {
    workspace: "~/my-custom-workspace",  // 自定义路径
  },
}

或用 CLI：

bash

openclaw config set agent.workspace "~/my-custom-workspace"

核心 Bootstrap 文件详解

这些文件在首次运行 openclaw onboard 时自动生成，之后可以自由编辑来定制 Agent 行为：

AGENTS.md — Agent 行为规范

告诉 Agent 它应该怎么工作，比如：

回复语气（正式 / 随意）
处理任务的优先级原则
不应该做的事情

markdown

# Agent 行为规范

## 回复风格
- 简洁明了，不废话
- 中文回复，专业词汇可保留英文

## 工作原则
- 不确定时先问清楚再行动
- 涉及文件操作前告知用户

## 禁止行为
- 不执行任何删除操作，除非用户明确确认

SOUL.md — Agent 个性

描述 Agent 的"灵魂"：个性特点、价值观、对话风格。这是 OpenClaw 的一个特色设计——让 Agent 有独特的个性而不是千篇一律的"AI 助手"。

markdown

# My Assistant

我是一个专注、高效的 AI 助手。我不喜欢废话，直接说重点。
我有点幽默感，但不会在工作场合滥用。
我重视隐私和数据安全。

IDENTITY.md — Agent 自我认知

Agent 对自己的描述：名字、能力、局限性。主要用于在被问到"你是谁"时给出准确回答。

USER.md — 关于你的背景信息

让 Agent 了解你是谁，这样它能提供更个性化的帮助：

markdown

# 关于我

- 职业：产品经理，负责电商平台
- 工作节奏：早 9 晚 7，周末不工作
- 常用工具：飞书、Notion、Linear
- 偏好：回复简洁、给出建议时列举 2-3 个选项
- 不喜欢：冗长的解释、重复问题

TOOLS.md — 工具使用规范

告诉 Agent 何时使用哪些工具，以及使用限制：

markdown

# 工具使用规范

## exec（命令执行）
- 执行前告知用户
- 避免使用 sudo
- 不要执行网络请求命令

## write（文件写入）
- 只在 workspace 目录内操作
- 修改已有文件前先展示 diff

HEARTBEAT.md — 心跳任务

配置 Agent 定期主动发起的任务（比如每天早上提醒你重要事项）：

markdown

# 心跳任务

每次心跳时：
1. 检查 memory/ 目录里有没有待办事项
2. 如果今天有日程，提前提醒
3. 如果没有特别的事，回复 NO_REPLY 保持安静

什么是心跳（Heartbeat）？

心跳让 Agent 主动联系你，而不只是被动等消息。每隔一段时间，Agent 会自动读取 HEARTBEAT.md 里的指令，判断有没有值得汇报的事——有就主动发消息给你，没有就回复 HEARTBEAT_OK 静默收场。

你可以把 HEARTBEAT.md 写成一份巡检清单：检查邮件、看看日程、有没有紧急任务……相当于给 Agent 安排了一个定期"主动汇报"的习惯。

比如你每天早上出门前，Agent 已经在 Telegram 上发来一条消息："今天 14:00 有产品评审会，昨晚有 3 封未读邮件需要回复，Linear 上有 2 个 P1 任务逾期。" —— 这就是心跳在工作。

心跳 vs 定时任务（Cron）

OpenClaw 有两套自动化机制，初学者容易混淆：

	心跳（Heartbeat）	定时任务（Cron）
一句话	有没有值得注意的事？	到点了，做这件事
运行位置	主会话，有完整对话上下文	独立会话，干净启动
适合场景	轻量、高频的巡检（查邮件、看日程、扫通知）	精确定时、耗时较长的任务（发日报、生成周报）
时间精度	约定间隔，允许有漂移	精确到分钟（如每天 9:00:00）
多任务	一次心跳可批量执行多个检查项	每个任务独立调度
典型用法	在 `HEARTBEAT.md` 里列清单	`openclaw cron add --cron "0 9 * * *"`

最佳实践：两者配合使用。心跳负责日常"有什么要汇报的"，Cron 负责"到点必须执行"的具体任务。

memory/ 目录 — 长期记忆

Agent 在对话中学到的重要信息会自动写入这里，按日期命名（2026-01-10.md）。这就是为什么 OpenClaw 能"记住"你之前说过的事情。

markdown

<!-- memory/2026-01-10.md -->
# 记忆 - 2026-01-10

## 用户偏好
- 喜欢简洁的回复
- 不喜欢在消息里加表情

## 项目进展
- 电商平台重构项目预计 Q2 上线
- 主要负责人是张工

workspace 的 Git 备份（推荐）

workspace 是你 Agent 的"大脑"，强烈建议用 Git 备份：

bash

cd ~/.openclaw/workspace

# 初始化仓库（首次运行 onboard 时可能已自动初始化）
git init

# 添加 .gitignore（避免提交敏感信息）
cat > .gitignore << 'EOF'
.env
**/*.key
**/*.pem
**/secrets*
memory/   # 如果记忆内容涉及隐私，也可以排除
EOF

# 提交初始文件
git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md
git commit -m "初始化 workspace"

# 推送到私有仓库（不要用公开仓库！）
git remote add origin https://github.com/yourname/my-openclaw-workspace-private
git push -u origin main

必须用私有仓库

workspace 包含你的个人信息、行为偏好、以及可能的工作内容摘要。务必使用私有仓库备份，绝不能公开。

5.4 CLI 常用命令速查

安装与初始化

bash

# 首次安装并初始化（含后台服务注册）
openclaw onboard --install-daemon

# 重新运行配置向导
openclaw configure

# 重置配置（保留会话和凭证）
openclaw reset --scope config

# 重置配置 + 凭证 + 会话（保留 workspace）
openclaw reset --scope config+creds+sessions

Gateway 管理

bash

# 前台运行（调试用，关闭终端即停止）
openclaw gateway run

# 指定端口运行
openclaw gateway run --port 18789 --bind loopback

# 强制重启（杀掉端口上的进程后重新启动）
openclaw gateway run --force

# 后台服务管理（需先 onboard --install-daemon）
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway status

# 在浏览器中打开控制面板
openclaw dashboard

诊断与排错

bash

# 基础健康检查（最常用，遇到问题先跑这个）
openclaw doctor

# 健康检查 + 自动修复
openclaw doctor --fix

# 深度扫描
openclaw doctor --deep --yes

# 查看完整状态
openclaw status --all

# 实时查看日志
openclaw logs --follow

# 按日志级别过滤
openclaw logs --level warn

# 渠道专项日志
openclaw channels logs --channel telegram

配置操作

bash

# 查看某个配置项的当前值
openclaw config get agents.defaults.model.primary
openclaw config get gateway.port

# 修改配置项
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config set agents.defaults.maxConcurrent 8
openclaw config set gateway.bind "loopback"

# 删除配置项
openclaw config unset tools.web.search.apiKey

# 查看全部配置
openclaw config get

渠道管理

bash

# 查看已配置的渠道
openclaw channels list

# 检查渠道连接状态
openclaw channels status
openclaw channels status --probe --all   # 更深入的连通性检查

# 添加渠道（交互式）
openclaw channels add --channel telegram
openclaw channels add --channel discord

# 非交互式添加 Telegram
openclaw channels add --channel telegram \
  --account main \
  --name "我的机器人" \
  --token "$TELEGRAM_BOT_TOKEN"

# WhatsApp / 飞书等 OAuth 登录（扫码）
openclaw channels login
openclaw channels login whatsapp

# 移除渠道
openclaw channels remove --channel telegram

模型管理

bash

# 查看已配置的模型
openclaw models list
openclaw models list --all   # 含完整目录

# 检查模型连接状态
openclaw models status
openclaw models status --probe   # 测试每个 Provider 的连通性

# 切换主模型
openclaw models set anthropic/claude-sonnet-4-5

# 管理别名（在对话中用 /model haiku 快速切换）
openclaw models aliases list
openclaw models aliases add haiku anthropic/claude-haiku-4-5

# 管理备用模型
openclaw models fallbacks list
openclaw models fallbacks add openai/gpt-4o-mini

# 管理认证档案（多账号）
openclaw models auth add
openclaw models auth order get
openclaw models auth order set anthropic "anthropic:subscription,anthropic:api"

Memory 与 Skills

bash

# 查看记忆索引状态
openclaw memory status

# 重新索引所有记忆文件
openclaw memory index --all

# 搜索记忆内容
openclaw memory search --query "部署相关的笔记"

# 查看已安装的 Skills
openclaw skills list
openclaw skills info web-search   # 查看某个 Skill 的详情

# 查看插件
openclaw plugins list
openclaw plugins doctor   # 检查插件加载错误

定时任务（Cron）

bash

# 查看所有定时任务
openclaw cron list --all

# 添加一次性任务（指定时间运行）
openclaw cron add \
  --name "morning-brief" \
  --at "2026-04-15T09:00:00Z" \
  --message "总结今天的日程和待办事项"

# 添加循环任务（每天早上 9 点）
openclaw cron add \
  --name "daily-standup" \
  --cron "0 9 * * *" \
  --message "今天有什么需要我关注的？"

# 立即手动触发
openclaw cron run --id morning-brief

# 启用 / 禁用任务
openclaw cron enable --id morning-brief
openclaw cron disable --id morning-brief

# 删除任务
openclaw cron rm --id morning-brief

发消息与会话

bash

# 直接向 Agent 发送消息（不经过渠道，适合测试）
openclaw agent --message "你好，帮我写一个工作日报模板"

# 向指定会话发送消息
openclaw message agent --session "session-key" --message "状态更新"

# 查看所有会话
openclaw sessions --json

# 清理过期会话
openclaw sessions cleanup

更新与版本管理

bash

# 更新到最新稳定版
openclaw update

# 切换更新渠道
openclaw update --channel stable   # stable | beta | dev

# 大版本升级后迁移配置
openclaw migrate

全局参数

以下参数适用于所有命令：

bash

--profile <name>    # 使用独立的配置/状态目录（多实例隔离）
--json              # 输出 JSON 格式（适合脚本处理）
--verbose           # 详细输出
--no-color          # 关闭颜色（适合 CI/日志）
--log-level debug   # 设置日志级别（debug | info | warn | error）

5.5 环境变量参考

变量优先级（高到低）

1. Shell 环境变量（启动 Gateway 时已在 shell 里的变量）
2. 工作目录的 .env 文件
3. ~/.openclaw/.env（全局兜底）
4. openclaw.json 中的 env.vars（最低优先级，只能设默认值）

常用环境变量

bash

# 路径配置
OPENCLAW_HOME=~/.openclaw           # 基础目录
OPENCLAW_CONFIG_PATH=/path/to/openclaw.json  # 自定义配置文件位置

# 日志
OPENCLAW_LOG_LEVEL=debug            # debug | info | warn | error
OPENCLAW_LOG_FORMAT=json            # 结构化日志输出

# API Key（在 openclaw.json 中用 ${VAR} 引用）
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
DEEPSEEK_API_KEY=sk-...
OPENROUTER_API_KEY=sk-or-...

# Gateway
OPENCLAW_GATEWAY_TOKEN=your-token   # 覆盖配置文件中的 auth.token

在配置文件中引用环境变量

json5

models: {
  providers: {
    anthropic: {
      apiKey: "${ANTHROPIC_API_KEY}",   // ← 引用环境变量，不要硬写密钥
    },
  },
},
channels: {
  telegram: {
    botToken: "${TELEGRAM_BOT_TOKEN}",
  },
},

最佳实践：凭证放 .env，结构放 JSON

把所有 API Key 放在 ~/.openclaw/.env，在 openclaw.json 中只保留 ${VAR} 占位符。这样 openclaw.json 可以放版本控制，而凭证永远不会意外提交。

本章小结

主题	核心要点
openclaw.json	JSON5 格式，Schema 验证严格，改错字段 Gateway 无法启动
配置编辑	优先用 `openclaw config set`，直接编辑后用 `openclaw doctor --fix` 验证
单 Agent	用 `agent`（单数）节，通过 `openclaw configure` 向导快速配置
多 Agent	用 `agents.defaults` + `agents.list` + `bindings` 三件套
workspace	Agent 的工作目录和记忆仓库，重点维护 SOUL.md / USER.md / memory/
CLI	`openclaw doctor` 是万能排错命令；`openclaw config set` 是安全修改配置的推荐方式

继续探索

OpenClaw 官方配置文档：docs.openclaw.ai
CLI 完整参考：openclawlab.com/docs/cli
Gateway 配置参考：openclawlab.com/docs/gateway/configuration

返回课程目录

第五章：Agent 配置与 CLI 参考 ​

本章概览 ​

5.1 openclaw.json 配置文件 ​

文件位置与格式 ​

配置作用域 ​

顶层配置结构总览 ​

gateway 节 ​

models 节 ​

auth 节（多账号 failover） ​

session 节 ​

热更新说明 ​

5.2 Agent 创建与配置 ​

单 Agent 配置（最常用） ​

通过 CLI 交互式创建 ​

多 Agent 配置 ​

路由匹配优先级 ​

用 CLI 管理多 Agent ​

重要限制：只能在 defaults 里配置的字段 ​

5.3 workspace 目录详解 ​

workspace 是什么？ ​

默认位置与自定义 ​

核心 Bootstrap 文件详解 ​

AGENTS.md — Agent 行为规范 ​

SOUL.md — Agent 个性 ​

IDENTITY.md — Agent 自我认知 ​

USER.md — 关于你的背景信息 ​

TOOLS.md — 工具使用规范 ​

HEARTBEAT.md — 心跳任务 ​

memory/ 目录 — 长期记忆 ​

workspace 的 Git 备份（推荐） ​

5.4 CLI 常用命令速查 ​

安装与初始化 ​

Gateway 管理 ​

诊断与排错 ​

配置操作 ​

渠道管理 ​

模型管理 ​

Memory 与 Skills ​

定时任务（Cron） ​

发消息与会话 ​

更新与版本管理 ​

全局参数 ​

5.5 环境变量参考 ​

变量优先级（高到低） ​

常用环境变量 ​

在配置文件中引用环境变量 ​

本章小结 ​

第五章：Agent 配置与 CLI 参考

本章概览

5.1 openclaw.json 配置文件

文件位置与格式

配置作用域

顶层配置结构总览

gateway 节

models 节

auth 节（多账号 failover）

session 节

热更新说明

5.2 Agent 创建与配置

单 Agent 配置（最常用）

通过 CLI 交互式创建

多 Agent 配置

路由匹配优先级

用 CLI 管理多 Agent

重要限制：只能在 defaults 里配置的字段

5.3 workspace 目录详解

workspace 是什么？

默认位置与自定义

核心 Bootstrap 文件详解

AGENTS.md — Agent 行为规范

SOUL.md — Agent 个性

IDENTITY.md — Agent 自我认知

USER.md — 关于你的背景信息

TOOLS.md — 工具使用规范

HEARTBEAT.md — 心跳任务

memory/ 目录 — 长期记忆

workspace 的 Git 备份（推荐）

5.4 CLI 常用命令速查

安装与初始化

Gateway 管理

诊断与排错

配置操作

渠道管理

模型管理

Memory 与 Skills

定时任务（Cron）

发消息与会话

更新与版本管理

全局参数

5.5 环境变量参考

变量优先级（高到低）

常用环境变量

在配置文件中引用环境变量

本章小结