1 安装问题
Q1：npm install -g openclaw 报错 EACCES 权限不足
bash
运行
# 方法一：使用sudo（不推荐）
sudo npm install -g openclaw
# 方法二（推荐）：修改npm全局目录
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g openclaw
Docker 启动后访问localhost:8080无响应
bash
运行
# 检查容器是否正在运行
docker ps | grep openclaw
# 检查容器日志是否有错误
docker logs openclaw 2>&1 | tail -50
# 检查端口映射
docker inspect openclaw | grep -i port
# 检查本机防火墙
ufw status # Ubuntu
# 确保8080端口已开放
Q3：Windows 上中文显示乱码
powershell
# PowerShell设置UTF-8
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$env:PYTHONIOENCODING = "UTF-8"
chcp 65001
2 配置问题
Q4：API Key 配置后提示 Invalid API Key
bash
运行
# 检查API Key格式
# Anthropic: sk-ant-api03-xxxx（注意是api03不是api01）
# OpenAI: sk-proj-xxxx 或 sk-xxxx
# 检查是否有多余空格
echo $ANTHROPIC_API_KEY | cat -A # 不应有^M或多余空格
# 测试API Key是否有效
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model":"claude-3-5-haiku-20241022","max_tokens":10,"messages":[{"role":"user","content":"test"}]}'
Q5：openclaw.json 修改后没有生效
bash
运行
# 重载配置
openclaw config reload
# 如果还是不生效，检查是否有语法错误
python3 -m json.tool openclaw.json
# 确认修改的是正确的文件
openclaw config show --path # 显示配置文件路径
Q6：SOUL.md 不生效 检查清单：
* 文件名：`SOUL.md`（大写，不是`soul.md`）
* 位置：在项目根目录，不是子目录
* 编码：UTF-8（用 VSCode 检查右下角）
* 格式：纯文本，没有 BOM 头
* 重启：修改后需要重启 Agent
3 运行问题
Q7：Agent 回复非常慢（超过 10 秒）
可能原因：
模型响应慢 → 换用更快的模型（Haiku 比 Sonnet 快 3 倍）
工具调用链太长 → 优化SOUL.md，减少不必要的工具调用
对话历史太长 → 设置 maxHistoryTokens: 2000
网络问题 → 检查与 API 服务器的延迟
快速诊断：
bash
运行
openclaw benchmark --model claude-3-5-haiku-20241022
# 查看API延迟是否正常（<2秒）
Q8：Agent 经常说 “我无法访问网络”
json
// OpenClaw需要明确配置工具才能访问网络
// 在openclaw.json中启用浏览器工具
{
"tools": {
"browser": {
"enabled": true,
"headless": true
},
"webSearch": {
"enabled": true,
"provider": "bing", // 或 google/duckduckgo
"apiKey": "${BING_SEARCH_KEY}"
}
}
}
4 集成问题
Q9：Telegram Bot 收不到消息
排查步骤与命令
bash
运行
# 1. 检查Token是否正确（校验Bot身份）
curl https://api.telegram.org/bot${TELEGRAM_TOKEN}/getMe
# 2. 检查Webhook是否设置
curl https://api.telegram.org/bot${TELEGRAM_TOKEN}/getWebhookInfo
# 3. 确认配置正确
# 确认：openclaw.json 中 Telegram 配置已设置
# 或：环境变量 TELEGRAM_BOT_TOKEN 已设置
# 4. 网络/防火墙：确认服务器能访问Telegram API
curl https://api.telegram.org
Q10: Agent 忘记之前的对话（记忆丢失）
json
// openclaw.json - 记忆与压缩配置
memory:
enabled: true
provider: "file" # 文件存储
path: "./.openclaw/memory"
persistence: true # 重启后保留记忆
maxSize: 100000 # 最多10万字
compressionEnabled: true
Q11：账单突然暴涨，如何紧急处理
bash
运行
# 步骤1：立即暂停OpenClaw
docker stop openclaw
# 步骤2：登录API控制台查看用量
# Anthropic: console.anthropic.com
# OpenAI: platform.openai.com/usage
# 步骤3：临时禁用API Key（防止继续产生费用）
# 在控制台操作
# 步骤4：分析原因
openclaw logs --export emergency-log.txt
# 查找大量调用的时间点
# 步骤5：修复问题后，添加成本上限再重启
# openclaw.json中添加 costControl 配置
Q12：如何精确计算每次对话的成本
bash
运行
# 1. 开启成本日志（核心开关）
openclaw config set LOG_COSTS true
# 2. 查看今日详细成本日志
openclaw cost detail --date today
# 3. 按Agent维度拆分成本统计
openclaw cost breakdown --by agent
# 4. 导出成本报表（CSV格式）
openclaw cost export --format csv --output costs-march.csv
5 安全问题
Q13：如何防止用户访问系统级别的工具
json
// openclaw.json - 工具权限控制（使用 tools.allow / tools.deny）
{
"tools": {
"profile": "coding",
"deny": ["exec", "bash", "process"],
"allow": ["group:fs", "group:web", "browser"],
"elevated": {
"enabled": true,
"allowFrom": {
"whatsapp": ["+你的手机号"]
}
}
}
}
Q14: 如何审计 Agent 的所有操作
json
// openclaw.json - 审计日志配置
audit:
enabled: true
level: "all" # all/actions/errors
storage:
provider: "file"
path: "./audit-logs"
retentionDays: 90
includePrompts: false # 不记录完整提示（保护隐私）
includeResponses: false # 不记录完整响应
includeToolCalls: true # 记录所有工具调用
includeMetadata: true # 记录时间戳、用户ID等