常见问题

关于 OpenClaw 的常见问题汇总。

基础问题

OpenClaw 是什么？

OpenClaw 是一个开源、自托管的 AI Agent 网关。它将 AI 接入 Telegram、Discord、微信等聊天平台，使 AI 能够执行代码、读写文件、操控浏览器、运行自动化任务。

OpenClaw 是免费的吗？

OpenClaw 本身是开源免费的（Apache 2.0 协议）。你需要自行承担 LLM API 的调用费用（如 Anthropic、OpenAI 等）。

支持哪些 LLM？

支持主流 LLM 提供商：Anthropic（Claude）、OpenAI（GPT）、DeepSeek、MiniMax、Moonshot、Ollama 等。也可以通过自定义 Provider 接入任何兼容 OpenAI API 格式的模型。

需要什么系统环境？

• Node.js 22+
• macOS / Linux / Windows（WSL2）
• 至少一个 LLM API Key

安装与配置

安装后命令找不到怎么办？

将 npm 全局 bin 目录加入 PATH：

export PATH="$(npm prefix -g)/bin:$PATH"

建议写入 ~/.bashrc 或 ~/.zshrc 使其永久生效。

端口 18789 被占用怎么办？

# 查看占用进程
lsof -i :18789

# 使用其他端口
openclaw gateway --port 19000

如何切换默认模型？

openclaw config set agents.defaults.model.primary "anthropic/claude-opus-4-6"
openclaw gateway restart

配置文件在哪里？

主配置文件：~/.openclaw/openclaw.json（JSON5 格式） 环境变量：~/.openclaw/.env

消息渠道

Telegram Bot 不回复消息？

1. 确认 Bot Token 正确
2. 确认 Gateway 正在运行：openclaw gateway status
3. 确认已完成配对：openclaw pairing list telegram
4. 查看日志：openclaw logs --follow

群聊中 Bot 不响应？

• Telegram 需要关闭 Privacy Mode（通过 @BotFather 设置）
• 群聊默认需要 @ 机器人触发，可通过 requireMention: false 关闭

国内网络连接 Telegram 失败？

在配置中添加代理：

{
  channels: {
    telegram: {
      proxy: "socks5://127.0.0.1:7890",
    },
  },
}

功能使用

如何让 Agent 定时执行任务？

使用 Cron 功能：

openclaw cron add --schedule "0 9 * * *" \
  --message "执行每日任务" \
  --channel telegram --target <ChatID>

如何让 Agent 操控浏览器？

在配置中启用浏览器：

{
  browser: {
    enabled: true,
    defaultProfile: "openclaw",
  },
}

然后在聊天中直接让 Agent 执行网页操作。

如何安装社区插件？

openclaw plugin install <插件名>
openclaw plugin enable <插件名>

故障排查

通用排查步骤

# 系统诊断
openclaw doctor

# 自动修复
openclaw doctor --fix

# 实时日志
openclaw logs --follow

# 查看状态
openclaw status

Agent 响应超时

• 检查 LLM API Key 是否有效
• 检查网络连接是否正常
• 尝试切换到响应更快的模型
• 调整超时设置：timeoutSeconds: 600