OpenClaw02_基础知识手册

OpenClaw02_基础知识手册

版本：基于 OpenClaw 官方文档（2025-2026）

适用对象：OpenClaw 初学者

用途：安装后目录结构解析与常见问题速查

---

第一章：安装后目录结构总览

OpenClaw 安装后会在用户主目录下创建 ~/.openclaw/ 目录（旧版本可能为 ~/openclaw），这是整个系统的核心状态目录（State Directory）。

1.1 根目录文件清单

文件/目录	类型	核心功能说明
openclaw.json	配置文件	主配置文件，包含Agent、Provider、全局工具策略等所有核心配置
openclaw.json.bak / .bak.1	备份文件	配置自动备份，用于配置回滚
update-check.json	状态文件	版本更新检查记录
exec-approvals.json	安全文件	执行审批记录，记录已批准/拒绝的危险操作
agents/	目录	Agent配置目录，每个子目录对应一个独立Agent
credentials/	目录	凭证存储目录，API密钥、OAuth令牌等敏感信息
extensions/	目录	扩展插件目录，通道插件、功能扩展等
skills/	目录	技能包目录，从ClawHub安装的技能（如weather、github等）
workspace/	目录	Agent工作区，Agent唯一可操作的工作目录
logs/	目录	日志目录，运行日志和调试信息
browser/	目录	浏览器自动化相关数据（CDP会话、缓存等）
canvas/	目录	可视化工作区数据
cron/	目录	定时任务配置和状态
devices/	目录	已连接设备的管理信息
identity/	目录	身份认证相关数据
completions/	目录	自动补全历史或缓存

---

第二章：核心配置文件详解

2.1 openclaw.json（主配置文件）

这是OpenClaw最重要的配置文件，使用 JSON5 格式（支持注释和 $include 指令）。

关键配置节：

{
  // Agent默认配置
  "agent": {
    "workspace": "~/.openclaw/workspace",  // 工作区路径
    "skipBootstrap": false,                // 是否跳过引导文件创建
    "sandbox": {
      "enabled": false,                    // 是否启用沙箱隔离
      "workspaceAccess": "rw"              // 工作区访问权限
    }
  },
  
  // Provider配置（LLM服务商）
  "providers": {
    "anthropic": {
      "apiKey": "$ANTHROPIC_API_KEY",      // 引用环境变量
      "defaultModel": "claude-sonnet-4-20250514"
    },
    "moonshot": {
      "apiKey": "$MOONSHOT_API_KEY",
      "defaultModel": "moonshot/kimi-k2.5"
    }
  },
  
  // 工具策略（9层权限体系）
  "tools": {
    "policy": "default-deny",              // 默认拒绝策略
    "allowedTools": ["Bash", "Read", "Write"],
    "blockedTools": ["Bash(sudo:*)"]       // 禁止sudo命令
  },
  
  // 网关配置
  "gateway": {
    "port": 18789,
    "bind": "127.0.0.1",                   // 默认仅本地绑定
    "auth": {
      "enabled": false
    }
  }
}

常见问题：

Q: 修改配置后需要重启吗？

A: 是的，大部分配置修改后需要重启 Gateway（openclaw gateway restart）才能生效。但部分运行时配置可通过 openclaw configure 命令热更新。

Q: 如何恢复默认配置？

A: 备份文件 openclaw.json.bak 是最近一次的自动备份，可直接覆盖恢复。建议定期手动备份：cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.manual.bak

2.2 exec-approvals.json（执行审批系统）

记录所有需要人工确认的危险操作审批状态，是安全审计的重要依据。

{
  "approvals": [
    {
      "id": "uuid-xxx",
      "tool": "Bash",
      "command": "rm -rf /important",
      "status": "rejected",
      "timestamp": "2026-02-25T10:30:00Z",
      "reason": "Dangerous delete operation"
    }
  ]
}

安全机制：

• 预批准列表：安全命令（如 jq, grep）自动通过
• 拦截列表：危险构造（如命令替换 $(...), sudo 子shell）默认阻止
• 9层策略体系：profile → provider → global → agent → group → sandbox → subagent...

---

第三章：关键工作目录

3.1 workspace/（Agent工作区）

这是Agent的主工作目录，所有文件工具（读/写/编辑）默认在此操作。

特性：

• 默认路径 ：~/.openclaw/workspace
• 多Profile支持 ：若设置 OPENCLAW_PROFILE=prod，则路径变为 ~/.openclaw/workspace-prod
• 沙箱模式 ：启用沙箱后，实际工作在 ~/.openclaw/sandboxes/ 下的隔离目录

重要提示：

Workspace 不是硬沙箱！Agent 仍可通过绝对路径访问主机其他目录（除非启用 sandbox.enabled）。建议将敏感文件移出工作区。

常见问题：

Q: 如何查看当前工作区路径？

A: 运行 openclaw doctor 命令，会检测并警告多余的workspace目录。

Q: 可以自定义工作区位置吗？

A: 可以，在 openclaw.json 中设置 agent.workspace 或使用环境变量 BRAIN_DIR。

3.2 agents/（Agent配置目录）

每个子目录代表一个独立的Agent人格，包含核心Markdown文件：

文件	作用
IDENTITY.md	Agent身份定义（名称、角色、基础能力）
SOUL.md	人格/语气/边界设定（性格、说话风格、安全限制）
AGENTS.md	操作规则（工具使用策略、记忆管理、子Agent委托）
USER.md	用户画像和偏好
HEARTBEAT.md	定时自检任务清单（可为空）
MEMORY.md	持久化记忆（仅私密会话）
TOOLS.md	环境特定的工具使用指南

创建新Agent：

openclaw agent create my-assistant
# 会在 agents/my-assistant/ 下生成标准文件结构

3.3 skills/（技能包目录）

Skills 是自包含的能力扩展，每个Skill是一个目录，包含 SKILL.md 文件。

目录结构：

~/.openclaw/skills/
├── weather/                    # 天气查询技能
│   ├── SKILL.md               # 技能定义（YAML frontmatter + Markdown）
│   ├── scripts/
│   └── assets/
├── github/                     # GitHub操作技能
│   └── SKILL.md
└── ...

安装方式：

# 从ClawHub安装（推荐）
clawhub install publisher/skill-name
npx openclaw skill install weather

# 手动安装
git clone <skill-repo> ~/.openclaw/skills/my-skill

加载优先级：

1. 工作区技能（~/openclaw/skills/）- 最高
2. 用户全局技能（~/.openclaw/skills/）
3. 内置捆绑技能 - 最低

3.4 credentials/（凭证管理）

存储所有敏感信息，务必设置严格权限 （chmod 700）。

内容示例：

credentials/
├── anthropic_api_key
├── github_token
├── aws_credentials
└── ...

安全建议：

• 永远不要将此目录提交到Git
• 建议使用 openclaw credentials add 命令而非手动编辑
• 可通过 openclaw.json 引用环境变量，避免硬编码

3.5 extensions/（扩展插件）

存放通道插件（Channels）和功能扩展：

extensions/
├── telegram/          # Telegram机器人插件
├── whatsapp/          # WhatsApp集成
├── slack/             # Slack机器人
├── discord/           # Discord集成
├── imessage/          # iMessage支持（macOS）
├── signal/            # Signal集成
└── ...

---

第四章：日志与调试

4.1 logs/ 目录结构

logs/
├── gateway.log        # 网关主日志
├── agent-*.log        # 各Agent运行日志
├── error.log          # 错误日志
└── audit.log          # 审计日志（操作记录）

查看实时日志：

tail -f ~/.openclaw/logs/gateway.log

4.2 常用诊断命令

命令	用途
openclaw doctor	健康检查，检测配置问题、重复工作区
openclaw status	查看Gateway和各Agent运行状态
openclaw logs	查看日志（支持 --follow）
openclaw configure	交互式配置向导

---

第五章：安全与权限

5.1 9层权限体系

OpenClaw 使用分层策略评估工具调用权限（按优先级排序）：

1. Profile - 当前激活的配置文件
2. Provider - LLM提供商级别
3. Global - 全局默认设置
4. Agent - 特定Agent配置
5. Group - Agent分组策略
6. Sandbox - 沙箱环境限制
7. Subagent - 子Agent委托限制
8. Session - 当前会话临时策略
9. Invocation - 单次调用参数

5.2 执行审批系统

自动批准： 安全命令如 jq, grep, cat（只读）
需要审批： 文件删除、网络请求、shell执行（含危险参数）
自动阻止： sudo, 命令替换 $(), 管道到shell等

配置示例（openclaw.json）：

{
  "tools": {
    "executionApproval": {
      "enabled": true,
      "autoApprove": ["Read", "Glob"],
      "autoReject": ["Bash(sudo:*)", "Bash(*rm -rf*)"]
    }
  }
}

---

第六章：常见问题速查（FAQ）

Q1: 安装后找不到配置文件？

A: 默认在 ~/.openclaw/openclaw.json。若使用旧版本，可能位于 ~/openclaw/。运行 openclaw doctor 可定位实际路径。

Q2: 如何迁移配置到新机器？

A: 复制整个 ~/.openclaw/ 目录，但不要复制 credentials/ 和 exec-approvals.json。建议重新设置凭证。

Q3: 为什么有多个 .bak 备份文件？

A: OpenClaw 在每次配置变更时自动创建备份（.bak 是最近一次的，.bak.1 是更早的）。最多保留2个历史版本。

Q4: workspace 和 sandbox 有什么区别？

A:

• Workspace: Agent的默认工作目录，无强制隔离
• Sandbox : 启用后，Agent在隔离环境中运行，无法访问主机文件系统（除非显式配置 workspaceAccess）

Q5: 如何清理日志文件？

A: 日志不会自动清理。建议设置cron任务：

# 保留最近7天日志
find ~/.openclaw/logs -name "*.log" -mtime +7 -delete

Q6: 更新检查文件 update-check.json 可以删除吗？

A: 可以，这是缓存文件。删除后下次运行会重新检查更新。

Q7: 如何完全卸载OpenClaw？

A:

# 停止服务
openclaw gateway stop

# 删除主目录
rm -rf ~/.openclaw/

# 删除旧版本目录（如有）
rm -rf ~/openclaw/

# 清理环境变量（从 ~/.bashrc 或 ~/.zshrc 中移除）

---

附录：重要参考资源

• 官方文档: https://docs.openclaw.ai/
• 技能市场（ClawHub）: 超过10,700+社区技能
• 社区目录: https://clawnavigator.com/
• 规则与配置: https://www.ruleofclaw.ai/

---

💡 学习建议 ：刚开始建议从修改 agents/default/SOUL.md 调整Agent性格入手，逐步熟悉 AGENTS.md 的操作规则配置，最后掌握 openclaw.json 的全局策略控制。