热门
立即入驻

openclaw配置文件详解-openclaw安装-5章

博客1周前发布 骆驼
273 00

配置文件详解

OpenClaw 的强大之处在于它的高度可配置性。一个配置文件就能定义 AI 的行为、连接的渠道、可用的技能——几乎所有东西都可以通过配置来调整。本篇将带你深入了解配置文件的每个角落。

配置文件位置

OpenClaw 的配置文件默认位于：

~/.openclaw/openclaw.json

这是一个标准的 JSON 文件。如果你通过 openclaw onboard 向导完成了初始化，这个文件已经自动创建好了。

你也可以通过环境变量自定义配置文件路径：

export OPENCLAW_CONFIG_PATH=/etc/openclaw/config.json

💡 提示：配置文件使用 JSON 格式。如果你不熟悉 JSON 的语法，建议使用 Control UI 的可视化编辑器来修改配置，避免因格式错误导致 Gateway 无法启动。

最小配置示例

一个最简单的、能正常运行的配置文件长这样：

{  "agents": [    {      "name": "main",      "model": "anthropic/claude-sonnet-4-20250514",      "apiKey": "sk-ant-xxxxxxxxxxxx"    }  ],  "channels": [    {      "type": "telegram",      "token": "123456:ABC-DEF..."    }  ]}

就这么简单！你只需要定义一个 Agent（指定 AI 模型和 API Key）和至少一个 Channel（指定通讯渠道），OpenClaw 就能运行起来。

当然，这只是起点。OpenClaw 提供了丰富的配置项，让你可以精确控制每一个细节。

配置编辑方式

OpenClaw 提供了多种编辑配置的方式，从图形界面到命令行，总有一种适合你：

1. Onboarding Wizard

最适合新手的方式。交互式问答，一步步引导你完成配置：

openclaw onboard

2. CLI 命令

通过命令行直接修改特定配置项：

# 添加或更新配置项openclaw config set agents[0].model "anthropic/claude-opus-4-20250514" # 查看当前配置openclaw config get agents # 验证配置文件openclaw doctor

3. Control UI

通过浏览器访问控制面板，在可视化编辑器中修改配置：

http://localhost:18789

Control UI 提供了语法高亮、实时校验和自动补全，非常直观。修改后点击保存，支持热更新的配置项会立即生效。

4. 直接编辑

直接用你喜欢的编辑器打开配置文件：

# 使用 vimvim ~/.openclaw/openclaw.json # 使用 nanonano ~/.openclaw/openclaw.json # 使用 VS Code（需要 SSH Remote 扩展）code ~/.openclaw/openclaw.json

⚠️ 注意：直接编辑时请确保 JSON 格式正确。一个多余的逗号或缺失的引号都会导致解析失败。编辑完成后建议运行 openclaw doctor 验证。

核心配置项概览

OpenClaw 的配置文件由几个核心部分组成。下面逐一介绍：

agents — AI 智能体配置

agents 数组定义了你的 AI 智能体。每个 Agent 代表一个 AI 实体，有自己的模型、人格和技能：

{  "agents": [    {      "name": "main",      "model": "anthropic/claude-sonnet-4-20250514",      "apiKey": "${ANTHROPIC_API_KEY}",      "systemPrompt": "你是一个友好、幽默的 AI 助手。",      "temperature": 0.7,      "maxTokens": 4096,      "thinkingLevel": "medium",      "skills": ["web-search", "browser", "code-exec"]    },    {      "name": "coder",      "model": "anthropic/claude-opus-4-20250514",      "apiKey": "${ANTHROPIC_API_KEY}",      "systemPrompt": "你是一个资深程序员，擅长代码审查和架构设计。",      "skills": ["code-exec", "file-edit", "git"]    }  ]}

常用字段说明：

字段类型说明
namestringAgent 名称，用于在多 Agent 场景下标识
modelstring模型标识，格式为 provider/model-name
apiKeystringAPI Key，支持环境变量引用
systemPromptstring系统提示词（也可以用工作空间文件代替）
temperaturenumber温度参数（0-1），越高越有创造力
maxTokensnumber最大输出 token 数
thinkingLevelstring思考深度（low/medium/high），影响模型推理
skillsarrayAgent 可用的技能列表

channels — 通讯渠道配置

channels 数组定义了 OpenClaw 接入的通讯平台：

{  "channels": [    {      "type": "telegram",      "token": "${TELEGRAM_BOT_TOKEN}",      "allowedUsers": ["your_telegram_id"],      "agent": "main"    },    {      "type": "discord",      "token": "${DISCORD_BOT_TOKEN}",      "applicationId": "your_app_id",      "allowedGuilds": ["guild_id_1"],      "agent": "main"    },    {      "type": "qqbot",      "appId": "${QQ_APP_ID}",      "secret": "${QQ_SECRET}",      "agent": "main"    }  ]}

每种渠道类型有自己特定的配置字段。详细的渠道配置请参考各渠道的专题文档。

tools — 技能/工具配置

tools 用于配置 Agent 可使用的技能和工具：

{  "tools": {    "browser": {      "enabled": true,      "headless": true    },    "code-exec": {      "enabled": true,      "sandbox": true,      "timeout": 30000    },    "web-search": {      "enabled": true,      "provider": "brave",      "apiKey": "${BRAVE_API_KEY}"    }  }}

session — 会话配置

session 控制对话会话的行为：

{  "session": {    "ttl": 3600,    "maxHistory": 50,    "maxContextTokens": 128000,    "summarize": true,    "summaryModel": "anthropic/claude-haiku-4-20250514"  }}
字段说明
ttl会话超时时间（秒），超时后开始新会话
maxHistory最大保留的消息条数
maxContextTokens发送给模型的最大上下文 token 数
summarize是否启用自动摘要（上下文过长时压缩）
summaryModel用于生成摘要的模型（可选更便宜的模型）

gateway — Gateway 配置

gateway 控制 Gateway 本身的行为：

{  "gateway": {    "port": 18789,    "bind": "loopback",    "configReload": "hybrid",    "auth": {      "password": "${GATEWAY_PASSWORD}"    },    "log": {      "level": "info",      "file": "~/.openclaw/logs/gateway.log"    }  }}

热更新说明

OpenClaw 的配置热更新是一个非常实用的特性。当你修改配置文件后，Gateway 会自动检测到变更并尝试应用。

可以热更新的配置

以下配置修改后不需要重启 Gateway：

  • ✅ Agent 的 systemPrompt、temperature、maxTokens
  • ✅ Agent 的 skills 列表
  • ✅ session 相关配置（ttl、maxHistory 等）
  • ✅ tools 中各技能的参数调整
  • ✅ thinkingLevel 思考深度

需要重启的配置

以下配置修改后需要重启 Gateway：

  • ❌ channels 的增加或删除
  • ❌ gateway.port 端口变更
  • ❌ gateway.bind 绑定模式变更
  • ❌ gateway.auth 认证方式变更
  • ❌ 渠道的 Token/API Key 变更

在默认的 hybrid 模式下，Gateway 会自动判断变更是否可以热更新。如果需要重启，它会在日志中提示你。

# 手动重启以应用需要重启的配置openclaw gateway restart

环境变量引用

配置文件中支持使用 ${VAR_NAME} 语法引用环境变量。这是强烈推荐的做法——永远不要把 API Key 等敏感信息直接写在配置文件中。

{  "agents": [    {      "name": "main",      "model": "anthropic/claude-sonnet-4-20250514",      "apiKey": "${ANTHROPIC_API_KEY}"    }  ],  "channels": [    {      "type": "telegram",      "token": "${TELEGRAM_BOT_TOKEN}"    }  ],  "gateway": {    "auth": {      "password": "${GATEWAY_PASSWORD}"    }  }}

然后在你的环境中设置这些变量：

# 在 ~/.bashrc 或 ~/.zshrc 中添加export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxx"export TELEGRAM_BOT_TOKEN="123456:ABC-DEF..."export GATEWAY_PASSWORD="my-secure-password"

或者使用 .env 文件：

# ~/.openclaw/.envANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxTELEGRAM_BOT_TOKEN=123456:ABC-DEF...GATEWAY_PASSWORD=my-secure-password

⚠️ 安全提示：确保 .env 文件的权限设置正确（chmod 600），不要将包含敏感信息的文件提交到 Git 仓库。

严格验证模式

OpenClaw 在读取配置文件时会进行语法和语义校验。如果配置有误，Gateway 会拒绝启动并给出详细的错误提示。

常见的校验错误：

❌ Config Error: agents[0].model is required❌ Config Error: channels[0].type "wechat" is not a valid channel type❌ Config Error: session.ttl must be a positive number❌ Config Error: Invalid JSON: Unexpected token } at position 234

你可以随时使用 openclaw doctor 来验证配置文件：

openclaw doctor

输出示例：

OpenClaw Doctor───────────────✅ Config file: valid JSON✅ Schema validation: passed✅ Agent "main": model configured✅ Agent "main": API key resolved⚠️ Agent "main": systemPrompt is empty (will use workspace files)✅ Channel telegram: token resolved✅ Channel discord: token resolved✅ Tools: web-search API key resolved⚠️ Workspace: SOUL.md not found (optional)───────────────Result: 2 warnings, 0 errors

配置示例合集

以下是几个常见场景的完整配置示例，方便你参考和复用。

个人助手（最简配置）

适合个人使用的最简配置，一个 Agent + 一个 Telegram 渠道：

{  "agents": [    {      "name": "main",      "model": "anthropic/claude-sonnet-4-20250514",      "apiKey": "${ANTHROPIC_API_KEY}",      "temperature": 0.7,      "maxTokens": 4096    }  ],  "channels": [    {      "type": "telegram",      "token": "${TELEGRAM_BOT_TOKEN}",      "allowedUsers": ["your_telegram_id"]    }  ],  "session": {    "ttl": 7200,    "maxHistory": 30  }}

多渠道助手

同时接入 Telegram、Discord 和 QQ 的配置：

{  "agents": [    {      "name": "main",      "model": "anthropic/claude-sonnet-4-20250514",      "apiKey": "${ANTHROPIC_API_KEY}",      "temperature": 0.7,      "skills": ["web-search", "browser", "code-exec"]    }  ],  "channels": [    {      "type": "telegram",      "token": "${TELEGRAM_BOT_TOKEN}",      "allowedUsers": ["user_id_1"]    },    {      "type": "discord",      "token": "${DISCORD_BOT_TOKEN}",      "applicationId": "${DISCORD_APP_ID}",      "allowedGuilds": ["guild_id_1"]    },    {      "type": "qqbot",      "appId": "${QQ_APP_ID}",      "secret": "${QQ_SECRET}"    }  ],  "session": {    "ttl": 3600,    "maxHistory": 50,    "maxContextTokens": 128000  },  "gateway": {    "port": 18789,    "bind": "loopback",    "configReload": "hybrid"  }}

高级配置（多 Agent + 完整技能栈）

面向高级用户的完整配置示例：

{  "agents": [    {      "name": "main",      "model": "anthropic/claude-sonnet-4-20250514",      "apiKey": "${ANTHROPIC_API_KEY}",      "temperature": 0.7,      "maxTokens": 8192,      "thinkingLevel": "medium",      "skills": ["web-search", "browser", "code-exec", "file-edit", "tts"]    },    {      "name": "coder",      "model": "anthropic/claude-opus-4-20250514",      "apiKey": "${ANTHROPIC_API_KEY}",      "temperature": 0.3,      "maxTokens": 16384,      "thinkingLevel": "high",      "skills": ["code-exec", "file-edit", "git", "browser"]    }  ],  "channels": [    {      "type": "telegram",      "token": "${TELEGRAM_BOT_TOKEN}",      "allowedUsers": ["admin_user_id"],      "agent": "main"    },    {      "type": "discord",      "token": "${DISCORD_BOT_TOKEN}",      "applicationId": "${DISCORD_APP_ID}",      "agent": "main"    }  ],  "tools": {    "web-search": {      "provider": "brave",      "apiKey": "${BRAVE_API_KEY}"    },    "browser": {      "headless": true    },    "code-exec": {      "sandbox": true,      "timeout": 60000    },    "tts": {      "provider": "elevenlabs",      "apiKey": "${ELEVENLABS_API_KEY}",      "voice": "nova"    }  },  "session": {    "ttl": 7200,    "maxHistory": 100,    "maxContextTokens": 200000,    "summarize": true,    "summaryModel": "anthropic/claude-haiku-4-20250514"  },  "gateway": {    "port": 18789,    "bind": "loopback",    "configReload": "hybrid",    "log": {      "level": "info"    }  }}

配置文件管理技巧

备份配置

# 备份当前配置cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak # 带日期的备份cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.$(date +%Y%m%d).json

使用 Git 管理配置变更

cd ~/.openclawgit initecho ".env" >> .gitignoreecho "state/" >> .gitignoregit add openclaw.json workspace/git commit -m "Initial config"

⚠️ 注意：不要将包含明文 API Key 的配置文件提交到公开仓库。使用环境变量引用 ${VAR_NAME} 后，配置文件本身不包含敏感信息，可以安全地进行版本管理。

© 版权声明
文章版权归作者所有，未经允许请勿转载。

相关文章

暂无评论

none
暂无评论...
添加小工具
点此为“正文侧边栏”添加小工具