OpenClaw 配置目录

OpenClaw也称 Clawdbot的所有配置、状态数据、工作区和技能均集中在用户主目录下的 ~/.openclaw/Linux/macOS或 %USERPROFILE%\.openclaw\Windows这个核心目录中。~/.openclaw/ 是整个系统的根配置目录首次安装/运行 openclaw onboard 或 openclaw onboard --install-daemon 时会自动创建。~/.openclaw/ ├── openclaw.json # 主配置文件JSON/JSON5 ├── workspace/ # 你的 AI “灵魂”文件夹推荐 git 版本控制 │ ├── SOUL.md # 人格设定语气、风格 │ ├── USER.md # 你的个人信息让 AI 更懂你 │ ├── MEMORY.md # 长期记忆手动可编辑 │ ├── IDENTITY.md # Agent 名称、形象 │ ├── AGENTS.md # 多 Agent 路由规则 │ ├── BOOT.md # 启动提示词 │ ├── HEARTBEAT.md # 每日检查清单 │ └── skills/ # 已安装技能每个技能一个子文件夹 ├── agents/cid/ # 每个 Agent 的独立状态 ├── memory/cid.sqlite # 向量记忆库 ├── credentials/ # API Key、OAuth旧版 ├── skills/ # 全局技能包 └── secrets.json # 加密凭证可选最重要文件openclaw.json全局设置模型、渠道、端口、安全策略workspace/下所有.md文件直接用 VS Code 编辑即可实时生效查看/修改配置命令openclaw configure # 交互式配置向导 openclaw config file # 显示完整路径 openclaw config get agent.model openclaw config set agent.model anthropic/claude-3-5-sonnet openclaw config validate # 校验合法性路径用途说明~/.openclaw/openclaw.json主配置文件最重要存储全局设置模型、Gateway 模式、绑定地址、Agents 默认值、插件等。可用命令查看/修改•openclaw config file显示完整路径•openclaw config get json路径•openclaw config set json路径 值~/.openclaw/workspace/默认工作区Agent 的灵魂所在地存放以下 Markdown 文件可直接编辑生效•SOUL.mdAI 人格/语气设定•USER.md你的个人偏好和背景•MEMORY.md长期记忆记录•AGENTS.md指令说明•IDENTITY.md名称/主题•BOOT.md启动配置•HEARTBEAT.md定期检查清单~/.openclaw/agents/cid/单个智能体Agent的状态目录cid为实例 ID~/.openclaw/agents/agentId/agent/auth-profiles.jsonAPI Key OAuth 凭证新版推荐位置旧版可能在~/.openclaw/credentials/~/.openclaw/memory/cid.sqlite向量索引存储记忆搜索用~/.openclaw/skills/全局技能目录通过openclaw skills install或clawhub install安装的技能包均放在这里每个技能是一个子文件夹内含 SKILL.md~/.openclaw/memory/长期记忆相关文件SQLite 向量嵌入/tmp/openclaw/*.logGateway 服务日志调试用1. 主配置文件路径:~/.openclaw/openclaw.json说明:OpenClaw 的核心配置文件,包含所有系统级设置。主要配置项:gateway- 网关服务配置mode: 网关模式(如 local)port: 网关端口号(默认 18789)bind: 绑定地址(默认 127.0.0.1)token: 访问令牌,用于 Web UI 认证models- AI 模型配置默认模型设置API 认证信息messages- 消息处理配置TTS(文本转语音)设置消息格式配置示例配置片段:{ gateway: { mode: local, port: 18789, bind: 127.0.0.1, token: c9917c5a066beeb26266d09baed99495e7563b33c771e89a } }操作建议:首次安装后通过openclaw onboard向导自动生成修改配置后需重启网关服务生效token 值用于 Web UI 访问,请妥善保管2. 工作区目录路径:~/.openclaw/workspace/说明:OpenClaw 的默认工作目录,所有 AI 生成的文件、临时文件和用户请求的输出文件都保存在此。主要用途:AI 智能体读写文件的默认位置代码执行输出存储文档生成和编辑临时数据存储权限说明:默认情况下,AI 只能访问此目录及其子目录若需访问其他路径,需要配置filesystem-mcp技能并授予额外权限Windows 用户可能需要将文件从工作区复制到其他位置使用建议:定期清理不需要的临时文件重要输出建议备份到工作区外可以在此建立项目子目录进行组织管理3. 智能体状态目录路径:~/.openclaw/agents/cid/说明:每个会话(Conversation)的智能体状态和配置存储目录。cid是会话 ID,每个会话都有独立的配置空间。目录结构:~/.openclaw/agents/cid/ ├── agent/ │ ├── auth-profiles.json # 该会话的 OAuth 和 API 密钥 │ └── ... └── ...auth-profiles.json 说明:存储该智能体使用的 API 认证信息包含各个服务的 OAuth token新版本使用此路径,旧版本存储在~/.openclaw/credentials/数据隔离:每个会话的认证信息相互独立可以为不同会话配置不同的 API 密钥支持多智能体并行运行4. 认证凭据目录(旧版)路径:~/.openclaw/credentials/说明:旧版本 OpenClaw 的凭据存储位置。迁移说明:新版本已迁移至~/.openclaw/agents/agentId/agent/auth-profiles.json旧版本用户升级后,凭据可能需要重新配置建议使用openclaw models auth setup重新设置5. 记忆存储目录路径:~/.openclaw/memory/说明:OpenClaw 的持久化记忆系统存储位置,包含向量索引和对话历史。主要文件:cid.sqlite- 向量索引数据库存储对话的语义向量支持语义搜索功能用于长期记忆检索YYYY-MM-DD.md- 每日对话日志以日期命名的 Markdown 文件记录当天所有对话内容便于人工查看和归档记忆功能:向量搜索:使用memory search 关键词搜索历史对话上下文关联:支持跨会话的上下文理解长期记忆:智能体会记住用户的偏好和习惯维护建议:定期备份 memory 目录大型数据库可能影响性能,可考虑定期归档日志文件可用于审计和问题排查6. 技能目录路径:~/.openclaw/skills/说明:全局共享技能(Skills)的安装位置。技能是扩展 OpenClaw 功能的插件。技能管理:安装技能:npx clawhub install skill-name列出技能:openclaw skills list搜索技能:npx clawhub search 关键词常用技能示例:filesystem-mcp- 文件系统操作github- GitHub 集成nano-pdf- PDF 编辑notion/obsidian- 笔记同步weather- 天气查询summarize- 内容摘要生成技能生态:社区技能库 ClawHub 提供 500 技能支持自定义技能开发技能可访问外部 API 和系统资源配置说明:每个技能可能需要单独的 API Key 配置部分技能依赖系统工具(如 GitHub CLI)macOS 专有技能在 Windows/Linux 上不可用7. 网关日志目录路径:/tmp/openclaw/*.log说明:网关服务的运行日志,存储在系统临时目录。日志类型:网关启动/停止日志API 请求/响应日志错误和异常日志性能监控信息日志管理:临时目录的日志可能在系统重启后清除使用openclaw gateway --verbose可以查看详细日志排查问题时应首先检查日志文件网关服务管理:openclaw gateway start # 启动网关 openclaw gateway status # 查看状态 openclaw gateway stop # 停止网关其他重要文件USER.md路径:通常位于工作区或用户自定义位置说明:用户信息文件,包含关于用户的个性化信息,帮助 AI 更好地理解用户需求。内容示例:用户偏好设置常用工作流程项目背景信息自定义指令配置文件管理最佳实践1. 备份策略关键目录备份:# 备份整个配置目录 tar -czf openclaw-backup-$(date %Y%m%d).tar.gz ~/.openclaw/ # 仅备份核心配置 cp ~/.openclaw/openclaw.json ~/backups/ cp -r ~/.openclaw/memory/ ~/backups/memory/建议备份频率:主配置文件:每次修改后记忆数据库:每周一次技能配置:安装新技能后2. 安全建议敏感信息保护:openclaw.json包含网关 token,不应公开auth-profiles.json包含 API 密钥,需加密保护定期更换 API 密钥不要将配置文件提交到版本控制系统权限设置:# 确保配置目录仅用户可访问 chmod 700 ~/.openclaw/ chmod 600 ~/.openclaw/openclaw.json chmod 600 ~/.openclaw/agents/*/agent/auth-profiles.json3. 迁移和升级版本升级注意事项:升级前备份整个~/.openclaw/目录检查 release notes 了解配置变更旧版本凭据可能需要迁移跨设备同步:可以同步配置文件实现多设备一致性注意路径差异(Windows vs Unix)敏感信息建议独立配置4. 故障排查配置问题诊断:# 检查配置文件语法 cat ~/.openclaw/openclaw.json | json_pp # 深度检查 openclaw doctor --deep # 查看网关状态 openclaw gateway status常见问题:认证失效:运行openclaw models auth setup重新配置网关无法启动:检查端口占用,查看日志文件技能无法使用:确认技能依赖已安装,检查 API 密钥环境变量配置OpenClaw 支持通过环境变量进行配置:# API 密钥环境变量 export ANTHROPIC_API_KEYyour-key-here export OPENAI_API_KEYyour-key-here export DEEPSEEK_API_KEYyour-key-here # 自定义配置目录 export OPENCLAW_HOME~/custom-path/.openclaw环境变量优先级:环境变量中的 API Key 会被 onboard 向导自动检测可以覆盖配置文件中的默认值适合 CI/CD 环境和容器化部署网络和部署配置本地部署默认配置:绑定地址: 127.0.0.1(仅本机访问)网关端口: 18789访问方式:http://127.0.0.1:18789/#tokenyour-token云端部署OpenClaw 支持部署在云服务器上:支持平台:阿里云:https://www.aliyun.com/activity/ecs/clawdbot腾讯云https://cloud.tencent.com/developer/article/26249731PanelDocker 容器云端配置特点:需要配置公网访问权限可能需要配置防火墙规则支持域名绑定和 SSL 证书集成平台配置OpenClaw 支持多种即时通讯平台:支持的平台国外:WhatsApp, Telegram, Discord, Slack, iMessage国内:飞书, 钉钉配置位置聊天渠道配置存储在openclaw.json中,包含:渠道类型(Slack/飞书等)认证 Token频道白名单/黑名单响应模式(DM/群聊)配置管理# 添加新渠道 openclaw channels add # 列出已配置渠道 openclaw channels list # 配对管理 openclaw pairing list openclaw pairing approve platform code