搞技术的都知道，英文文档读起来没什么问题，但有些配置项的命名确实不太好理解，再加上不同版本的文档可能有变动，找一个准确的中文参考有时候能省下大量时间。我最近花了几天时间把OpenClaw的配置参数系统过了一遍，把自己翻译整理的内容分享出来，希望能帮到需要的朋友。声明一下，这不是官方翻译，是我根据实际使用经验和源码注释做的理解和整理，如果有不准确的地方欢迎指正。

OpenClaw最新版本一键部署包下载地址：TopClaw官网一键免费部署OpenClaw

一、核心配置区块

OpenClaw的配置文件通常采用YAML或者JSON格式，按照功能模块分成不同的区块。我先从最核心的几个开始说。

gateway：这是网关相关的配置。gateway.host设置服务监听的主机地址，默认是127.0.0.1，意味着只接受本机连接。如果你想从局域网其他设备访问，需要改成0.0.0.0。gateway.port是端口号，默认8080。gateway.tls.enabled控制是否启用HTTPS，如果开启的话还需要配置证书路径和密钥路径。对于本地开发来说一般不需要开TLS，但如果是远程部署，建议打开。

agent：Agent是OpenClaw里最重要的概念，它代表一个具体的AI助手实例。agent.name是Agent的显示名称，agent.model指定使用的AI模型。agent.system_prompt是系统提示词，用于设定Agent的行为和角色。这个字段支持多行文本，你也可以把它指向一个外部文件，用file://前缀加路径的方式引用。

agent.max_tokens控制单次请求允许的最大token数，这个值不应该超过模型本身的上限。agent.temperature控制输出的随机性，值域0到2，0表示完全确定性输出，2表示高度随机。日常使用0.7到0.9是一个比较合理的范围。agent.top_p是核采样的概率阈值，和temperature配合使用，通常设成0.9左右。

二、工具与技能配置

skills：这是技能模块的配置。skills.enabled控制是否启用技能系统，默认为true。skills.directory指定技能文件的存放目录，支持绝对路径和相对路径（相对于工作目录）。skills.auto_load控制是否在启动时自动加载所有已安装的技能。如果你有很多技能但不是每次都需要全部加载，可以关掉这个选项，然后在需要的时候手动启用特定的技能。

tools：工具配置区。tools.browser.enabled控制浏览器自动化功能是否开启，开启后可以使用网页操作相关的指令。tools.browser.headless设置是否使用无头模式运行浏览器，服务器部署时一般设为true，本地开发可以设为false方便调试。tools.file.allowed_paths设定文件操作允许访问的路径范围，这是一个安全相关的配置，建议只开放必要的目录。

三、消息与通信配置

messaging：消息模块配置。messaging.channels是一个列表，每个元素定义一个消息通道。常用的通道类型包括webchat（网页聊天）、telegram（Telegram机器人）、discord（Discord机器人）等。每个通道需要配置type、enabled以及通道特有的参数。比如Telegram通道需要配置bot_token，Discord通道需要配置token和guild_id。

messaging.rate_limit设置消息发送的频率限制，单位是每分钟消息数。默认值一般够用，但如果你的Agent会在短时间内发送大量消息（比如处理批量任务），可能需要适当调高。注意各平台有自己的API频率限制，设置值不应该超过平台允许的上限。

messaging.retry_policy：重试策略。retry_policy.max_retries是最大重试次数，retry_policy.backoff_factor是退避因子（单位秒），retry_policy.backoff_type是退避类型，支持fixed（固定间隔）和exponential（指数退避）。推荐用指数退避，在网络不稳定的情况下表现更好。

四、存储与缓存配置

storage：存储相关配置。storage.type指定存储后端类型，支持local（本地文件）和database（数据库）等。storage.path设置本地存储的根目录。storage.max_file_size设定单个文件的最大允许大小，默认是10MB。如果你经常需要处理大文件，记得调高这个值。

cache：缓存配置。cache.enabled控制是否启用缓存。cache.type支持memory（内存缓存）和disk（磁盘缓存）。cache.ttl设置缓存的有效期（秒）。cache.max_size限制缓存的最大容量。对于频繁访问但不常变更的数据（比如模型配置、用户偏好设置等），开启缓存可以明显提升响应速度。

五、日志与监控配置

logging：日志模块配置。logging.level设置日志级别，从低到高依次是debug、info、warn、error、fatal。logging.format控制日志输出格式，支持text（纯文本）和json（结构化JSON）。后者适合接入日志收集系统。logging.output指定日志输出的目标，支持stdout（标准输出）、file（文件）和both（两者同时）。

logging.file.path设置日志文件的路径。logging.file.rotation控制日志轮转策略，支持按大小（size）和按时间（time）两种模式。logging.file.max_size是单个日志文件的最大大小（字节）。logging.file.max_files是保留的历史日志文件数量。

monitoring：监控配置。monitoring.enabled控制是否启用监控端点。monitoring.port设置监控服务的端口（如果和主服务不同）。monitoring.metrics_path设置指标数据的访问路径，默认是/metrics，输出的是Prometheus格式的指标数据。

六、安全配置

security：安全相关配置。security.auth.enabled控制是否启用身份验证。security.auth.method指定认证方式，支持token和oauth2等。security.cors.allowed_origins设置允许跨域访问的来源列表，生产环境不建议用通配符，应该明确指定允许的域名。

security.rate_limit设置API级别的请求频率限制。security.timeout设置请求处理的超时时间。security.sanitize_input控制是否对输入内容进行清洗过滤，开启后可以防止一些常见的注入攻击。建议在对外暴露服务的场景下开启这个选项。

七、性能调优参数

performance：性能调优区块。performance.concurrency设置并发处理的最大数量。performance.queue_size设置任务队列的缓冲区大小。performance.worker_threads指定工作线程数，默认会根据CPU核心数自动判断。performance.batch_size设置批量处理的单批大小，适用于需要同时处理多条消息的场景。

performance.memory_limit设置内存使用上限，超过限制时会触发缓存清理和资源回收。performance.gc_interval设置垃圾回收的间隔时间。这些参数在资源受限的环境中（比如低配服务器或容器）比较有用，可以根据实际情况微调。

写在最后

以上是OpenClaw主要配置参数的中文说明。实际使用中你不需要把每个参数都配一遍——大部分参数有合理的默认值，你只需要关注和你的使用场景直接相关的那些。建议的步骤是：先用默认配置跑起来，然后根据实际需求和遇到的问题，有针对性地调整特定参数。配置这个东西，够用就行，过度优化反而容易引入新问题。

如果你发现有哪些参数我漏掉了或者解释得不够清楚，欢迎在评论区补充讨论。