OpenClaw02_基础知识手册

坐吃山猪2026-02-26 8:40

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 指令）。

关键配置节：

json5 复制代码 
{
  // 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（执行审批系统）

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

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：

bash 复制代码 
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
└── ...

安装方式：

bash 复制代码 
# 从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          # 审计日志（操作记录）

查看实时日志：

bash 复制代码 
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）：

json5 复制代码 
{
  "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任务：

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

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

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

Q7: 如何完全卸载OpenClaw？

A:

bash 复制代码 
# 停止服务
openclaw gateway stop

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

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

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

附录：重要参考资源

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

相关推荐
Shacoray3 小时前
OpenClaw 接入阿里云百炼 Coding Plan 指南
阿里云·ai·云计算·qwen3·openclaw·coding plan
诸神缄默不语3 小时前
如何用腾讯云轻量应用服务器内置OpenClaw应用搭建OpenClaw并接入QQ、飞书机器人，下载skill，开启对话
大模型·腾讯云·qq机器人·智能助手·飞书机器人·clawdbot·openclaw
weiwei2284418 小时前
腾讯云部署OpenClaw并集成Telegram机器人
telegram·ai小助手·deepseek-v3.2·openclaw
烤鸭的世界我们不懂21 小时前
开箱即用：OpenCLaw集成飞书实用部署与使用心得
人工智能·ai编程·openclaw
Bruce_Liuxiaowei1 天前
在 macOS 上通过 Docker 本地安装 OpenClaw 完整教程
macos·docker·容器·openclaw
偕臧x1 天前
OpenClaw + 飞书（Feishu）环境搭建指南
部署·飞书·openclaw·feishu·spawn einval
福大大架构师每日一题2 天前
openclaw v2026.2.21版本正式发布：新增Gemini 3.1支持、火山引擎对接、全新Discord语音系统与超200项安全和性能升级
安全·火山引擎·openclaw
liuyunshengsir2 天前
1分钟使用openclaw生成ppt
人工智能·openclaw
Boxsc_midnight2 天前
【windows电脑浏览器直接访问虚拟机或云端openclaw的方法】一个不需要HTTPS的安全连接通道（基于SSH）
windows·安全·https·openclaw
热门推荐
01GitHub 镜像站点02Claude Code + GLM4.7 避坑指南：解决 Unable to connect to Anthropic services03【OpenClaw 本地实战 Ep.3】突破瓶颈：强制修改 openclaw.json 解锁 32k 上下文记忆04AI Agent 平台横评：ZeroClaw vs OpenClaw vs Nanobot05OpenClaw 使用和管理 MCP 完全指南06Clawdbot部署教程：解决‘gateway token missing’授权问题的完整步骤07AI 规范驱动开发“三剑客”深度对比：Spec-Kit、Kiro 与 OpenSpec 实战指南08AI agent：介绍 ZeroClaw 安装，使用09OpenClaw 安装之（三）DeepSeek模型接入配置和详细配置参数10EvoMap 是什么？