OpenClaw Configuration Directory

OpenClaw (also known as Clawdbot) centralizes all of its configuration, state data, workspaces, and skills in the core directory ~/.openclaw/ (Linux/macOS) or %USERPROFILE%\.openclaw\ (Windows) under the user's home directory.

~/.openclaw/is the root configuration directory of the entire system; on first installation/runopenclaw onboardoropenclaw onboard --install-daemonit is automatically created.

~/.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                  # 加密凭证（可选）

Most Important Files：

  • openclaw.json: Global settings (model, channels, ports, security policies)
  • workspace/all under.mdFiles:You can directly edit with VS Code and it takes effect in real time.！

Command to view/modify configuration:

openclaw configure      # 交互式配置向导
openclaw config file          # 显示完整路径
openclaw config get agent.model
openclaw config set agent.model "anthropic/claude-3-5-sonnet"
openclaw config validate      # 校验合法性
Path Purpose Description
~/.openclaw/openclaw.json Main Configuration File(Most Important!)
Stores global settings (model, Gateway mode, bind address, Agents default values, plugins, etc.).
Can be viewed/modified with the command:
• openclaw config file(displays the full path)
• openclaw config get <json路径>
• openclaw config set <json路径> <值>
~/.openclaw/workspace/ Default Workspace(The location of the Agent's "soul")
Stores the following Markdown files (can be edited directly and take effect):
• SOUL.md: AI personality/tone settings
• USER.md: Your personal preferences and background
• MEMORY.md: Long-term memory records
• AGENTS.md: Instruction descriptions
• IDENTITY.md: Name/Theme
• BOOT.md: Startup configuration
• HEARTBEAT.md: Periodic checklist
~/.openclaw/agents/<cid>/ State directory of a single agent (<cid>for instance ID)
~/.openclaw/agents/<agentId>/agent/auth-profiles.json API Key & OAuth credentials(recommended location in new version)
Legacy version may be in~/.openclaw/credentials/
~/.openclaw/memory/<cid>.sqlite Vector index storage (for memory search)
~/.openclaw/skills/ Global skill directory
Viaopenclaw skills installorclawhub installAll installed skill packages are placed here (each skill is a subfolder containing SKILL.md)
~/.openclaw/memory/ Long-term memory related files (SQLite + vector embeddings)
/tmp/openclaw/*.log Gateway service logs (for debugging)

1. Main Configuration File

Path: ~/.openclaw/openclaw.json

Description:OpenClaw's core configuration file, containing all system-level settings.

Main configuration items:

  • gateway- Gateway service configuration
    • mode: Gateway mode (e.g., "local")
    • port: Gateway port (default 18789)
    • bind: Bind address (default 127.0.0.1)
    • token: Access token, used for Web UI authentication
  • models- AI model configuration
    • Default model settings
    • API authentication information
  • messages- Message processing configuration
    • TTS (text-to-speech) settings
    • Message format configuration

Example configuration snippet:

{
  "gateway": {
    "mode": "local",
    "port": 18789,
    "bind": "127.0.0.1",
    "token": "c9917c5a066beeb26266d09baed99495e7563b33c771e89a"
  }
}

Operation suggestions:

  • After first installation, it isopenclaw onboardautomatically generated by the wizard
  • After modifying the configuration, restart the Gateway service for it to take effect.
  • The token value is used for Web UI access; please keep it safe.

2. Workspace Directory

Path: ~/.openclaw/workspace/

Description:OpenClaw's default working directory, where all AI-generated files, temporary files, and output files from user requests are saved.

Main uses:

  • Default location for AI agent file read/write
  • Code execution output storage
  • Document generation and editing
  • Temporary data storage

Permission notes:

  • By default, AI can only access this directory and its subdirectories.
  • If access to other paths is required, configurefilesystem-mcpskills and grant additional permissions
  • Windows users may need to copy files from the workspace to other locations.

Usage suggestions:

  • Regularly clean up unneeded temporary files
  • It is recommended to back up important outputs outside the workspace.
  • You can create project subdirectories here for organization and management.

3. Agent State Directory

Path: ~/.openclaw/agents/<cid>/

Description:Directory for storing agent state and configuration for each conversation.<cid>It is the conversation ID, and each conversation has independent configuration space.

Directory structure:

~/.openclaw/agents/<cid>/
├── agent/
│   ├── auth-profiles.json    # 该会话的 OAuth 和 API 密钥
│   └── ...
└── ...

auth-profiles.json description:

  • Stores the API authentication information used by this agent
  • Contains OAuth tokens for various services
  • The new version uses this path; the old version is stored in~/.openclaw/credentials/

Data isolation:

  • Authentication information for each conversation is independent
  • Different API keys can be configured for different conversations
  • Supports parallel operation of multiple agents

4. Authentication Credentials Directory (Legacy)

Path: ~/.openclaw/credentials/

Description:Credential storage location for the old version of OpenClaw.

Migration notes:

  • The new version has migrated to~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • After upgrading from the old version, credentials may need to be reconfigured
  • It is recommended to useopenclaw models auth setupto reset

5. Memory Storage Directory

Path: ~/.openclaw/memory/

Description:Storage location for OpenClaw's persistent memory system, including vector indexes and conversation history.

Main files:

  • <cid>.sqlite- Vector index database

    • Stores semantic vectors of conversations
    • Supports semantic search functionality
    • Used for long-term memory retrieval

  • YYYY-MM-DD.md- Daily conversation logs

    • Markdown files named by date
    • Records all conversation content for the day
    • Facilitates manual review and archiving

Memory features:

  • Vector search:Usesmemory search "关键词"to search historical conversations
  • Context association:Supports cross-conversation context understanding
  • Long-term memory:The agent will 'remember' user preferences and habits

Maintenance recommendations:

  • Regularly back up the memory directory
  • Large databases may affect performance; consider regular archiving
  • Log files can be used for auditing and troubleshooting

6. Skills Directory

Path: ~/.openclaw/skills/

Description:Installation location for globally shared skills. Skills are plugins that extend OpenClaw's functionality.

Skill management:

  • Install skills: npx clawhub install <skill-name>
  • List skills: openclaw skills list
  • Search skills: npx clawhub search <关键词>

Common skill examples:

  • filesystem-mcp- File system operations
  • github- GitHub integration
  • nano-pdf- PDF editing
  • notion / obsidian- Note synchronization
  • weather- Weather query
  • summarize- Content summary generation

Skills ecosystem:

  • Community skills library ClawHub provides 500+ skills
  • Supports custom skill development
  • Skills can access external APIs and system resources

Configuration instructions:

  • Each skill may require separate API Key configuration
  • Some skills depend on system tools (e.g., GitHub CLI)
  • macOS-exclusive skills are not available on Windows/Linux

7. Gateway Log Directory

Path: /tmp/openclaw/*.log

Description:Runtime logs of the gateway service, stored in the system temporary directory.

Log types:

  • Gateway start/stop logs
  • API request/response logs
  • Error and exception logs
  • Performance monitoring information

Log management:

  • Logs in the temporary directory may be cleared after system restart
  • Useopenclaw gateway --verboseDetailed logs can be viewed
  • When troubleshooting, check the log files first

Gateway service management:

openclaw gateway start    # 启动网关
openclaw gateway status   # 查看状态
openclaw gateway stop     # 停止网关

Other Important Files

USER.md

Path:Usually located in the workspace or user-defined location

Description:User information file, containing personalized information about the user, helping AI better understand user needs.

Content examples:

  • User preference settings
  • Common workflows
  • Project background information
  • Custom instructions

Best Practices for Configuration File Management

1. Backup Strategy

Critical directory backup:

# 备份整个配置目录
tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw/

# 仅备份核心配置
cp ~/.openclaw/openclaw.json ~/backups/
cp -r ~/.openclaw/memory/ ~/backups/memory/

Recommended backup frequency:

  • Main configuration file: after each modification
  • Memory database: once a week
  • Skill configuration: after installing new skills

2. Security Recommendations

Sensitive information protection:

  • openclaw.jsonContains gateway token, should not be made public
  • auth-profiles.jsonContains API keys, needs encryption protection
  • Regularly change API keys
  • Do not commit configuration files to version control systems

Permission settings:

# 确保配置目录仅用户可访问
chmod 700 ~/.openclaw/
chmod 600 ~/.openclaw/openclaw.json
chmod 600 ~/.openclaw/agents/*/agent/auth-profiles.json

3. Migration and Upgrade

Version upgrade considerations:

  • Before upgrading, back up the entire~/.openclaw/directory
  • Check release notes for configuration changes
  • Old version credentials may need migration

Cross-device sync:

  • Can sync configuration files for multi-device consistency
  • Note path differences (Windows vs Unix)
  • Sensitive information is recommended to be configured separately

4. Troubleshooting

Configuration issue diagnosis:

# 检查配置文件语法
cat ~/.openclaw/openclaw.json | json_pp

# 深度检查
openclaw doctor --deep

# 查看网关状态
openclaw gateway status

Common issues:

  • Authentication expired:Runopenclaw models auth setupReconfigure
  • Gateway fails to start:Check port occupancy, view log files
  • Skills unavailable:Confirm skill dependencies are installed, check API keys

Environment Variable Configuration

OpenClaw supports configuration via environment variables:

# API 密钥环境变量
export ANTHROPIC_API_KEY="your-key-here"
export OPENAI_API_KEY="your-key-here"
export DEEPSEEK_API_KEY="your-key-here"

# 自定义配置目录
export OPENCLAW_HOME="~/custom-path/.openclaw"

Environment variable priority:

  • API Keys in environment variables are automatically detected by the onboard wizard
  • Can override default values in configuration files
  • Suitable for CI/CD environments and containerized deployment

Network and Deployment Configuration

Local Deployment

Default configuration:

  • Bind address: 127.0.0.1 (local access only)
  • Gateway port: 18789

Access method:

http://127.0.0.1:18789/#token=<your-token>

Cloud Deployment

OpenClaw supports deployment on cloud servers:

Supported platforms:

Cloud configuration features:

  • Need to configure public internet access permissions
  • May need to configure firewall rules
  • Supports domain binding and SSL certificates

Integration Platform Configuration

OpenClaw supports multiple instant messaging platforms:

Supported Platforms

  • International: WhatsApp, Telegram, Discord, Slack, iMessage
  • Domestic:Feishu, DingTalk

Configuration Location

Chat channel configuration is stored inopenclaw.json, including:

  • Channel type (Slack/Feishu, etc.)
  • Authentication token
  • Channel whitelist/blacklist
  • Response mode (DM/group chat)

Configuration Management

# 添加新渠道
openclaw channels add

# 列出已配置渠道
openclaw channels list

# 配对管理
openclaw pairing list
openclaw pairing approve <platform> <code>
Other extensions