OpenClaw 部署后关键配置指南

部署完成只是开始，正确配置才能发挥 OpenClaw 的全部能力,内容是我的小龙虾创作，我个人觉得写得挺全面的。

1. 网关配置

1.1 访问控制台

部署完成后，通过浏览器访问控制台：

http://127.0.0.1:18789/

或使用 CLI 打开：

openclaw dashboard

1.2 网关基本命令

# 启动网关openclaw gateway start# 停止网关openclaw gateway stop# 重启网关openclaw gateway restart# 查看状态openclaw statusopenclaw gateway status# 前台运行（调试用）openclaw gateway --port18789

1.3 配置文件位置

用途	路径
主配置	`~/.openclaw/openclaw.json`
工作区	`~/.openclaw/workspace/`
日志	`~/.openclaw/logs/`
认证配置	`~/.openclaw/auth-profiles.json`

2. 模型配置

2.1 支持的模型提供商

提供商	模型示例	特点
Anthropic	claude-sonnet-4-5, claude-opus-4-5	性价比高，响应快
OpenAI	gpt-4o, gpt-4o-mini	能力全面
Google	gemini-2-flash, gemini-2-pro	速度快
Ollama	llama3, qwen2	本地运行
DeepSeek	deepseek-chat	中文优化

2.2 基本配置

{agents: {defaults: {model: {primary: "anthropic/claude-sonnet-4-5",fallbacks: ["openai/gpt-4o"]      }    }  }}

2.3 模型别名配置

{agents: {defaults: {models: {"anthropic/claude-sonnet-4-5": { alias: "Sonnet" },"anthropic/claude-opus-4-5": { alias: "Opus" },"openai/gpt-4o": { alias: "GPT" },"google/gemini-2-flash": { alias: "Flash" }      }    }  }}

2.4 CLI 配置命令

# 设置主模型openclaw config set agents.defaults.model.primary "anthropic/claude-sonnet-4-5"# 添加备用模型openclaw config set agents.defaults.model.fallbacks '["openai/gpt-4o"]'# 查看可用模型openclaw models list

2.5 环境变量配置模型

{env: {OPENROUTER_API_KEY: "sk-or-v1-xxx",OPENAI_API_KEY: "sk-xxx"  }}

3. 频道配置

3.1 钉钉配置

{"channels": {"dingtalk-connector": {"clientId": "钉钉应用的Client Secret",       // 必选：填入上方的 钉钉 Client ID"clientSecret": "钉钉应用的Client Secret", // 必选：填入上方的 Client Secret"gatewayToken": "Gateway 认证 token",  // 必选：Gateway 认证 token, openclaw.json配置中 gateway.auth.token 的值 "gatewayPassword": "",              // 可选：Gateway 认证 password（与 token 二选一）"sessionTimeout": 1800000// 可选：会话超时(ms)，默认 30 分钟    }  },"gateway": { // gateway通常是已有的节点，配置时注意把http部分追加到已有节点下"auth": {"mode": "token","token": "Gateway 认证 token"// 必选：一般是安装时默认就有    },"http": {"endpoints": {"chatCompletions": {"enabled": true// 必选        }      }    }  }}

3.2 Telegram 配置

{channels: {telegram: {enabled: true,botToken: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",dmPolicy: "pairing",allowFrom: ["tg:123456789"]    }  }}

3.5 频道管理命令

# 查看频道状态openclaw channels status# 重新扫描频道openclaw channels scan# WhatsApp 重新登录openclaw channels whatsapp login# 测试发送openclaw message send --target+15555550123--message"测试"

4. 安全访问控制

4.1 DM 策略 (dmPolicy)

策略	说明	适用场景
`pairing`	需要配对码验证（默认）	最佳安全
`allowlist`	仅白名单用户	严格控制
`open`	允许所有消息	测试环境
`disabled`	禁用私信	仅群组

4.2 基础安全配置

{channels: {whatsapp: {dmPolicy: "pairing",allowFrom: ["+15555550123", "+15555550124"]    },telegram: {dmPolicy: "allowlist",allowFrom: ["tg:123456789"]    }  }}

4.3 群组访问控制

{channels: {whatsapp: {groups: {"*": {requireMention: true,allowFrom: ["+15555550123"]        },"family-group": {requireMention: false        }      }    }  }}

4.4 设备配对管理

# 查看已配对设备openclaw devices list# 批准新设备openclaw devices approve <requestId># 撤销设备openclaw devices revoke --device <deviceId>

5. 会话管理

5.1 会话作用域 (dmScope)

作用域	说明	适用场景
`main`	所有用户共享	单用户
`per-peer`	每个用户独立	多用户简单隔离
`per-channel-peer`	按渠道+用户	推荐多渠道
`per-account-channel-peer`	最细粒度	复杂场景

5.2 会话配置

{session: {dmScope: "per-channel-peer",threadBindings: {enabled: true,idleHours: 24,maxAgeHours: 0    },reset: {mode: "daily",atHour: 4,idleMinutes: 120    }  }}

5.3 会话重置模式

{session: {reset: {mode: "daily",      // daily | weekly | neveratHour: 4,          // 重置时间idleMinutes: 120,   // 空闲后重置dayOfWeek: 1// weekly 模式有效    }  }}

5.4 会话管理命令

# 列出当前会话openclaw sessions list# 查看会话详情openclaw sessions get"agent:main:whatsapp:dm:+15555550123"# 重置会话openclaw sessions reset "agent:main:whatsapp:dm:+15555550123"

6. 沙箱安全

6.1 沙箱模式

模式	说明
`off`	关闭沙箱
`non-main`	非主智能体使用沙箱
`all`	所有智能体使用沙箱

6.2 沙箱配置

{agents: {defaults: {sandbox: {mode: "non-main",scope: "agent"      }    }  }}

6.3 构建沙箱镜像

# 首次使用前需要构建沙箱镜像./scripts/sandbox-setup.sh

6.4 完整沙箱配置

{agents: {defaults: {sandbox: {mode: "non-main",scope: "agent",allowedTools: ["web-search", "web-fetch", "memory-search"],blockedTools: ["exec", "database-write"]      }    }  }}

7. 心跳监控

7.1 心跳配置

{agents: {defaults: {heartbeat: {every: "30m",target: "last",directPolicy: "allow"      }    }  }}

7.2 配置说明

参数	说明	可选值
`every`	检查间隔	`30m`, `1h`, `2h`, `0m`(禁用)
`target`	发送目标	`last`, `whatsapp`, `telegram`, `discord`, `none`
`directPolicy`	DM 策略	`allow`, `block`

7.3 CLI 配置

# 设置心跳间隔openclaw config set agents.defaults.heartbeat.every "1h"# 设置心跳目标openclaw config set agents.defaults.heartbeat.target "telegram"# 禁用心跳openclaw config set agents.defaults.heartbeat.every "0m"

8. 日志配置

8.1 日志级别

级别	说明
`error`	仅错误
`warn`	警告及以上
`info`	信息及以上（默认）
`debug`	调试信息
`trace`	详细追踪

8.2 日志配置

{logging: {level: "info",file: "~/.openclaw/logs/openclaw.log",consoleLevel: "info",consoleStyle: "pretty",redactSensitive: "tools"  }}

8.3 日志管理命令

# 查看实时日志openclaw logs tail# 查看最近 100 行openclaw logs tail --lines100# 查看错误日志openclaw logs tail --level error# 导出日志openclaw logs export--output /tmp/openclaw-logs.zip

9. 工作区配置文件（非常重要）

OpenClaw 工作区中的 Markdown 配置文件定义了 AI 助手的行为方式和协作风格。

用Cursor远程打开服务器文件夹，用AI直接改效果非常好……

9.1 配置文件一览

文件	用途	优先级
`SOUL.md`	AI 能力范围、工作方法、交付标准	⭐⭐⭐
`USER.md`	用户偏好、约束、输出格式	⭐⭐⭐
`IDENTITY.md`	AI 身份标签、表达风格	⭐⭐
`TOOLS.md`	工具箱、命令清单、环境别名	⭐⭐
`AGENTS.md`	工作区总则、启动顺序、红线	⭐⭐
`MEMORY.md`	长期记忆、精炼要点	⭐
`HEARTBEAT.md`	周期性检查清单	⭐

9.2 文件结构

~/.openclaw/workspace/├── SOUL.md          # 能力定义├── USER.md          # 用户偏好├── IDENTITY.md      # 身份标签├── TOOLS.md         # 工具箱├── AGENTS.md        # 工作区总则├── MEMORY.md        # 长期记忆├── HEARTBEAT.md     # 心跳检查└── memory/    └── YYYY-MM-DD.md # 每日日志

9.3 SOUL.md 配置

作用：定义 AI 的能力范围、工作方法、专业领域和交付标准。

核心配置：

# SOUL.md - 协作内核## 核心目标- 快速收敛：先讲清楚问题，再做成事情- 工程化交付：可执行、可验证、可回滚、可审计- 安全优先：最小权限、最小暴露面## 输出格式- 结论先行- 可复制命令（含占位符）- 验证清单- 回滚方案## 专业领域- 网络/安全/服务器/虚拟化- AI 算力服务器- Python 自动化

9.4 USER.md 配置

作用：告诉 AI 如何与你协作。

核心配置：

# USER.md - 用户偏好## 基本信息- **称呼**：老师- **语言**：简体中文- **时区**：UTC+8## 优先级1. 安全性2. 可执行性3. 可验证性4. 可回滚性## 交付格式- 先结论后展开- 命令块含风险提示- 变量使用占位符## 敏感信息- 不粘贴明文密码/token- IP/域名可打码（如 10.1.x.x）

9.5 IDENTITY.md 配置

作用：定义 AI 的身份定位和表达风格。

核心配置：

# IDENTITY.md - 身份定义## 身份卡- **Name**: IT 工程师- **Role**: 一线交付与排障负责人- **Tone**: 专业、直接、事实导向## 表达风格结论先行 → 证据/依据 → 步骤与验证 → 风险与回滚## 边界原则- 不明文出现敏感信息- 变更必须可回滚- 证据优先保全

9.6 TOOLS.md 配置

作用：记录常用工具、命令和环境信息。

核心配置：

# TOOLS.md - 工具箱## SSH 别名

jump-prod -> 生产跳板机gpu-node-01 -> GPU 节点

## 网络采集```baship -br aip rss -sdig +time=2 <DOMAIN> A

脱敏规范

密码/token → <TOKEN>
IP → 10.1.x.x
主机名 → host-***

### 9.7 AGENTS.md 配置**作用**：定义会话启动顺序、记忆维护和红线边界。**核心配置**：```markdown# AGENTS.md - 工作区总则## 启动顺序1. SOUL.md2. USER.md3. TOOLS.md4. memory/YYYY-MM-DD.md5. MEMORY.md (仅主会话)## 红线- 不外传私有数据- 不做破坏性操作（需先给回滚方案）- 不确定就停## 记忆规则- 流水账 → memory/YYYY-MM-DD.md- 精炼要点 → MEMORY.md- Text > Brain（想记住就写下来）

9.8 MEMORY.md 配置

作用：存放长期有效、反复会用的信息。

核心配置：

# MEMORY.md - 长期记忆## 长期背景- 用户画像：IT 工程师- 协作偏好：见 USER.md## 标准做法### 生产故障止血 → 定位 → 修复 → 复盘### 变更/割接前置检查 → 分步执行 → 验收 → 观察窗口## 踩坑教训- GPU 驱动升级必须给兼容矩阵- 网络变更必须明确回滚点

9.9 HEARTBEAT.md 配置

作用：定义周期性检查任务。

核心配置：

# HEARTBEAT.md## 定期检查- 检查邮件（紧急消息）- 检查日历（2小时内事件）- 检查天气（出行参考）## 状态记录# 保持文件为空（或仅注释）可禁用心跳

9.10 快速配置命令

# 查看工作区文件ls-la ~/.openclaw/workspace/# 查看配置文件cat ~/.openclaw/workspace/SOUL.mdcat ~/.openclaw/workspace/USER.md# 编辑配置文件vim ~/.openclaw/workspace/SOUL.md# 通过 Control UI 编辑openclaw dashboard → Config

10. 快速配置命令汇总

# === 基础 ===openclaw status              # 查看状态openclaw doctor              # 诊断问题openclaw dashboard           # 打开控制台# === 配置 ===openclaw config get# 查看配置openclaw config set <key> <value>      # 设置配置openclaw config apply                  # 应用配置并重启openclaw config unset <key>            # 移除配置# === 频道 ===openclaw channels status    # 频道状态openclaw message send        # 发送消息# === 会话 ===openclaw sessions list       # 会话列表openclaw sessions reset      # 重置会话# === 设备 ===openclaw devices list        # 设备列表openclaw devices approve     # 批准设备

11. 最佳实践

从最小配置开始 — 先确保基础功能，再逐步添加高级配置
优先配置安全策略 — dmPolicy 和 allowFrom 应第一时间设置

生产环境推荐配置

{"session": { "dmScope": "per-channel-peer" },"logging": { "level": "info" },"agents": { "defaults": { "heartbeat": { "every": "30m" } } }}

工作区配置原则

分工明确：不重复定义
脱敏优先：不写明文敏感信息
少而精：只存长期价值内容
Text > Brain：想记住就写下来

12. 常见问题

Q: 配置修改后不生效？

# 重启 Gatewayopenclaw gateway restart# 或openclaw config apply

Q: 配置文件在哪里？

~/.openclaw/openclaw.json

Q: 配置出错导致无法启动？

openclaw doctoropenclaw doctor --fix

Q: 如何查看当前配置？

openclaw config getcat ~/.openclaw/openclaw.json

目录

1. 网关配置

1.1 访问控制台

1.2 网关基本命令

1.3 配置文件位置

2. 模型配置

2.1 支持的模型提供商

2.2 基本配置

2.3 模型别名配置

2.4 CLI 配置命令

2.5 环境变量配置模型

3. 频道配置

3.1 钉钉配置

3.2 Telegram 配置

3.5 频道管理命令

4. 安全访问控制

4.1 DM 策略 (dmPolicy)

4.2 基础安全配置

4.3 群组访问控制

4.4 设备配对管理

5. 会话管理

5.1 会话作用域 (dmScope)

5.2 会话配置

5.3 会话重置模式

5.4 会话管理命令

6. 沙箱安全

6.1 沙箱模式

6.2 沙箱配置

6.3 构建沙箱镜像

6.4 完整沙箱配置

7. 心跳监控

7.1 心跳配置

7.2 配置说明

7.3 CLI 配置

8. 日志配置

8.1 日志级别

8.2 日志配置

8.3 日志管理命令

9. 工作区配置文件（非常重要）

9.1 配置文件一览

9.2 文件结构

9.3 SOUL.md 配置

9.4 USER.md 配置

9.5 IDENTITY.md 配置

9.6 TOOLS.md 配置

脱敏规范

9.8 MEMORY.md 配置

9.9 HEARTBEAT.md 配置

9.10 快速配置命令

10. 快速配置命令汇总

11. 最佳实践

12. 常见问题

Q: 配置修改后不生效？

Q: 配置文件在哪里？

Q: 配置出错导致无法启动？

Q: 如何查看当前配置？