AiTimes 智能时代

Appearance

OpenClaw配置完全指南：openclaw.json详解 📘 ​

📌 来源： 虾哥AI 公众号 | 转载说明： 本文经整理排版后发布，版权归原作者所有

这篇文章把OpenClaw配置文件 openclaw.json 拆成模块来讲，结合示例说明每一个配置的作用。

OpenClaw配置指南

📑 目录 ​

一、文件结构：先搞清楚有哪些模块 ​

~/.openclaw/openclaw.json 文件里有哪些顶层字段？

├── auth          认证配置（API Key等）
├── models        模型配置（提供商、API地址、模型列表）
├── agents        智能体配置（默认模型、工作区、会话）
├── tools         工具配置（启用/禁用哪些工具）
├── channels      渠道配置（飞书、企业微信等）
├── gateway       网关配置（端口、访问控制）
├── session       会话配置（生命周期、超时）
├── hooks         自动化配置（定时任务等）
├── bindings      多路由配置（消息分流到不同Agent）
├── plugins       插件配置
├── skills        技能配置
├── env           环境变量（敏感信息存储）
├── logging       日志配置
├── messages      消息行为配置
└── commands      斜杠命令配置

按使用频率排序，常用的详细讲，不常用的简单带过。

二、auth模块：你的API Key存在这里 ​

作用： 存储所有外部服务的API Key认证信息

json
{
  "auth": {
    "profiles": {
      "zai:default": {
        "provider": "zai",
        "mode": "api_key",
        "apiKey": "${ZAI_API_KEY}"
      },
      "openrouter:default": {
        "provider": "openrouter",
        "mode": "api_key",
        "apiKey": "${OPENROUTER_API_KEY}"
      }
    }
  }
}

⚠️ 关键点：

  • provider 的值必须和 models 里的提供商名称对应
  • apiKey 务必使用 ${ENV_VAR} 格式，不要明文填写
  • 先设置环境变量：export ZAI_API_KEY="你的Key"

三、models模块：最核心的配置 ​

作用： 定义可以用哪些模型，通过哪个API调用

示例（智谱AI） ​

json
{
  "models": {
    "mode": "merge",
    "providers": {
      "zai": {
        "baseUrl": "https://open.bigmodel.cn/api/coding/paas/v4",
        "api": "openai-completions",
        "models": [
          {
            "id": "glm-5",
            "name": "GLM-5",
            "contextWindow": 204800,
            "maxTokens": 131072,
            "reasoning": true
          },
          {
            "id": "glm-4-flash",
            "name": "GLM-4-Flash",
            "contextWindow": 128000,
            "maxTokens": 8192,
            "reasoning": false
          }
        ]
      }
    }
  }
}

示例（OpenRouter） ​

json
{
  "models": {
    "mode": "merge",
    "providers": {
      "openrouter": {
        "baseUrl": "https://openrouter.ai/api/v1",
        "api": "openai-completions",
        "models": [
          {
            "id": "google/gemini-2.0-flash",
            "name": "Gemini 2.0 Flash",
            "contextWindow": 1000000,
            "maxTokens": 8192,
            "reasoning": true
          },
          {
            "id": "anthropic/claude-sonnet-4-5",
            "name": "Claude Sonnet 4.5",
            "contextWindow": 200000,
            "maxTokens": 8192,
            "reasoning": true
          }
        ]
      }
    }
  }
}

⚠️ 关键点：

  • mode: "merge" = 合并内置模型和自定义模型（通常选这个）
  • id 必须是模型提供商的准确ID，不能自己编
  • contextWindow 单位是Token，影响上下文长度
  • reasoning: true = 启用推理能力（复杂任务建议开启）

四、agents模块：控制Agent的行为 ​

作用： 设置Agent默认用什么模型、工作区在哪、会话怎么管理

json
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "zai/glm-5",
        "fallbacks": ["openrouter/google/gemini-2.0-flash"]
      },
      "workspace": "~/.openclaw/workspace",
      "compaction": {
        "mode": "safeguard"
      },
      "heartbeat": 300
    }
  }
}

⚠️ 关键点：

  • primary 的格式是 提供商/模型ID，必须和models里配置的完全一致
  • fallbacks 是备用模型列表，当前模型不可用时自动切换
  • workspace 是Agent的工作目录，Agent只能读写这个目录下的文件
  • heartbeat: 300 = 每5分钟检测一次Agent是否存活
  • compaction.mode: "safeguard" = 长对话自动压缩，防止超出上下文限制

五、tools模块：Agent能用哪些工具 ​

作用： 控制Agent能做什么——搜索、执行命令、读写文件等

示例（启用全部工具） ​

json
{
  "tools": {
    "profile": "full",
    "deny": [],
    "allow": [],
    "web": {
      "search": {
        "enabled": true
      },
      "timeout": 10
    }
  }
}

示例（禁用浏览器工具，仅保留基础工具） ​

json
{
  "tools": {
    "profile": "basic",
    "deny": ["browser", "canvas"],
    "allow": [],
    "web": {
      "search": {
        "enabled": true
      }
    }
  }
}

⚠️ 关键点：

  • profile: "full" = 启用全部工具
  • profile: "basic" = 仅启用基础工具（exec, read, write等）
  • deny 是禁用列表，allow 是白名单（allow优先于deny）
  • web.search.enabled: true = 启用网页搜索

六、channels模块：连接飞书/企业微信 ​

作用： 让Agent能接收和回复飞书消息

飞书配置示例 ​

json
{
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "cli_axxxxxxxx",
      "appSecret": "${FEISHU_APP_SECRET}",
      "connectionMode": "websocket",
      "streaming": true,
      "timeout": 30
    }
  }
}

企业微信配置示例 ​

json
{
  "channels": {
    "wecom": {
      "enabled": true,
      "corpId": "wwxxxxxxx",
      "corpSecret": "${WECOM_CORP_SECRET}",
      "agentId": 1000001,
      "connectionMode": "websocket"
    }
  }
}

⚠️ 关键点：

  • appId 是 cli_ 开头的字符串，不是纯数字
  • connectionMode: "websocket" = 长连接（实时性好，推荐）
  • streaming: true = 消息流式输出，边生成边显示
  • 务必在飞书开发者平台开启机器人和相关权限

七、gateway模块：网关安全配置 ​

作用： 控制网关端口、访问权限、认证方式

示例（本地安全模式） ​

json
{
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",
    "auth": {
      "mode": "token",
      "token": "${GATEWAY_TOKEN}"
    },
    "timeout": 60
  }
}

示例（公网访问模式） ​

json
{
  "gateway": {
    "port": 18789,
    "mode": "public",
    "bind": "0.0.0.0",
    "auth": {
      "mode": "token",
      "token": "${GATEWAY_TOKEN}"
    }
  }
}

⚠️ 关键点：

  • bind: "loopback" = 仅本机可访问（安全，本地使用选这个）
  • bind: "0.0.0.0" = 所有地址可访问（需要配合token认证）
  • 修改port后需确保端口不被占用：lsof -i :18789
  • 修改此模块后需重启网关：openclaw gateway restart

八、session模块：会话管理 ​

作用： 控制会话的生命周期、超时、自动重置规则

json
{
  "session": {
    "ttl": 86400,
    "timeout": 3600,
    "autosave": true,
    "autosaveInterval": 300
  }
}

⚠️ 关键点：

  • ttl: 86400 = 会话保留24小时（单位：秒）
  • timeout: 3600 = 1小时内无活动自动结束会话
  • autosaveInterval: 300 = 每5分钟自动保存会话状态

九、hooks模块：定时任务自动化 ​

作用： 设置定时任务，让Agent在特定时间自动执行

json
{
  "hooks": {
    "cron": [
      {
        "id": "daily-report",
        "schedule": "0 9 * * *",
        "agent": "main",
        "prompt": "生成今日AI资讯摘要，并发布到公众号草稿箱"
      }
    ]
  }
}

⚠️ 关键点：

  • schedule 使用标准cron表达式：分 时 日 月 周
  • 0 9 * * * = 每天早上9点执行
  • agent 指定用哪个Agent执行（需要bindings里配置过）

十、bindings模块：多Agent路由 ​

作用： 把不同用户/关键词路由到不同的Agent

json
{
  "bindings": {
    "rules": [
      {
        "channel": "feishu",
        "user": ["user1@company.com"],
        "agent": "coder"
      },
      {
        "channel": "feishu",
        "keyword": ["写代码", "debug", "编程"],
        "agent": "coder"
      },
      {
        "channel": "feishu",
        "keyword": ["报告", "总结", "周报"],
        "agent": "writer"
      }
    ]
  }
}

⚠️ 关键点：

  • 规则按顺序匹配，第一个命中的生效
  • user = 匹配特定用户
  • keyword = 匹配消息关键词
  • 多租户场景使用这个模块

十一、env模块：安全存储敏感信息 ​

作用： 在配置文件里安全存储环境变量，不暴露明文

json
{
  "env": {
    "ZAI_API_KEY": "sk-xxxx",
    "OPENROUTER_API_KEY": "sk-xxxx",
    "GATEWAY_TOKEN": "xxxx",
    "FEISHU_APP_SECRET": "xxxx"
  }
}

⚠️ 关键点：

  • env里的值是明文存储的，文件权限要控制好（chmod 600 openclaw.json）
  • 更好的做法：只在env里放标记，实际Key通过shell环境变量传入
  • 建议通过 ${ENV_VAR} 引用，而不是直接写值

十二、logging模块：日志配置 ​

作用： 控制日志输出级别和保留策略

json
{
  "logging": {
    "level": "info",
    "path": "~/.openclaw/logs",
    "maxSize": 100,
    "maxDays": 7
  }
}

⚠️ 关键点：

  • level: "debug" = 最详细（排查问题时用）
  • level: "info" = 普通日志（日常运行选这个）
  • level: "error" = 仅记录错误
  • maxSize: 100 = 单个日志文件最大100MB
  • maxDays: 7 = 保留7天后自动清理

十三、messages模块：消息行为配置 ​

作用： 控制Agent回复的格式、前缀、ACK反应等

json
{
  "messages": {
    "prefix": "[虾哥AI] ",
    "format": "markdown",
    "ack": {
      "enabled": true,
      "reaction": "✅"
    }
  }
}

⚠️ 关键点：

  • prefix = 回复前缀，方便区分是AI的回复
  • format: "markdown" = 支持富文本格式
  • ack.reaction = 飞书消息已读回执显示的表情

十四、快速参考表 ​

模块常用场景修改后需重启？
auth换API Key否
models添加/切换模型否
agents改默认模型否
tools禁用某个工具否
channels配置飞书是
gateway改端口/安全策略是
session改超时策略否
hooks设置定时任务否
bindings多租户路由否
env敏感信息存储否
logging改日志级别否
messages改回复格式否

总结 ​

每个模块都配上了直接能用的示例。改哪个字段，对照着复制过去就行。

有报错就对照上面的常见错误清单排查，十有八九是JSON格式或Key引用的问题。

虾哥AI

📢 原文作者： 虾哥AI | 如果这篇文章让你有收获，欢迎关注原作者公众号 🦐

📌 更多教程请访问： AiTimes 智能时代

Released under the MIT License.

Copyright © 2026 AiTimes 智能时代 | www.AiTimes.net
豫ICP备15008213号