基于实际调试记录问题总结

文档版本: 1.0
调试时间: 2026年3月2日-3日（约14小时）
系统环境: Windows 10/11 + PowerShell
OpenClaw版本: 2026.2.26

---

第一部分：关键错误日志与解决方案

错误 1：MiniMax API Key 未找到

日志信息:

⚠️ Agent failed before reply: No API key found for provider "minimax". 
Auth store: C:\Users\dell\.openclaw\agents\main\agent\auth-profiles.json
Configure auth for this agent (openclaw agents add <id>) 
or copy auth-profiles.json from the main agentDir.

出现场景: 初始配置时使用了 MiniMax，但未配置 API Key

解决方案:

# 方案 A：添加 Moonshot 配置（推荐）
openclaw agents add moonshot

# 方案 B：直接修改配置文件
notepad "C:\Users\dell\.openclaw\agents\main\agent\auth-profiles.json"

交互记录:

用户: 换成 kimi API key 如何配置
助手: 执行 openclaw agents add moonshot，选择 Kimi API key (.ai)，输入 API Key

---

错误 2：OpenRouter 模型 ID 格式错误

日志信息:

⚠️ Agent failed before reply: Unknown model: moonshot/kimi-k2.5:free.

出现场景: 使用了错误的 OpenRouter 模型 ID 格式

正确格式对比:

错误格式	正确格式
moonshot/kimi-k2.5:free	openrouter/moonshotai/kimi-k2.5
moonshot/kimi-k2.5	openrouter/moonshotai/kimi-k2.5

解决方案:

# 修改全局配置
openclaw config set agents.defaults.model.primary "openrouter/moonshotai/kimi-k2.5"

# 修改 agent 配置
openclaw config set agents.list[0].model "openrouter/moonshotai/kimi-k2.5"
openclaw config set agents.list[1].model "openrouter/moonshotai/kimi-k2.5"

交互记录:

用户: 怎么确定调用的是 Kimi 2.5 呢
助手: 必须指定具体模型，不能用 auto。修改 config.json 为 "model": "openrouter/moonshotai/kimi-k2.5"

---

错误 3：OpenRouter 免费额度不足

日志信息:

HTTP 402: This request requires more credits, or fewer max_tokens. 
You requested up to 32000 tokens, but can only afford 6855. 
To increase, visit https://openrouter.ai/settings/credits 
and upgrade to a paid account

出现场景: 免费账户调用 Kimi 2.5，token 需求超过额度

额度对比:

模型	所需 Tokens	免费额度	结果
Kimi 2.5	32000	6855	❌ 不足
Auto 模式	动态	动态	✅ 自动选择可用模型

解决方案:

方案 A：改用 Auto 模式

openclaw config set agents.defaults.model.primary "openrouter/auto"
openclaw config set agents.list[0].model "openrouter/auto"
openclaw config set agents.list[1].model "openrouter/auto"

方案 B：降低 max_tokens（尝试）

notepad "C:\Users\dell\.openclaw\openclaw.json"
# 添加 "maxTokens": 4000 到 model 配置

方案 C：使用 Moonshot 官方 API

openclaw config set agents.defaults.model.primary "moonshot:default"
openclaw config set agents.list[0].model "moonshot/kimi-k2.5"

交互记录:

用户: 我只给了你 Openrouter 的 key
助手: 你的 OpenRouter 免费额度只能支持 6855 tokens，而 Kimi 2.5 需要 32000。建议改用 auto 模式或 Moonshot 官方。

---

错误 4：API Key 自动恢复旧值（关键 Bug）

日志信息:

# 修改前
"key": "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"

# 运行 openclaw dashboard 后
"key": "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"

出现场景: 修改 main/agent/auth-profiles.json 后，运行 openclaw dashboard 自动恢复旧值

根本原因: OpenClaw 从隐藏缓存或同步机制强制覆盖

排查过程:

检查位置	命令	结果
环境变量	echo $env:OPENROUTER_API_KEY	旧值
用户级环境变量	[Environment]::GetEnvironmentVariable("OPENROUTER_API_KEY", "User")	旧值
系统级环境变量	[Environment]::GetEnvironmentVariable("OPENROUTER_API_KEY", "Machine")	空
注册表	Get-ItemProperty -Path "HKCU:\Environment" -Name "OPENROUTER_API_KEY"	空
OpenClaw 代码	Select-String -Path "...\dist\*.js" -Pattern "103c4f"	未找到

最终结论: OpenClaw 内部同步机制 bug，未找到隐藏缓存位置

解决方案:

方案 A：使用环境变量覆盖（部分有效）

# 设置当前会话
$env:OPENROUTER_API_KEY = "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"

# 设置永久
[Environment]::SetEnvironmentVariable("OPENROUTER_API_KEY", "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", "User")

方案 B：使用 openrouter agent（推荐）

# 在 Web UI 中切换到 openrouter agent
# 或在命令行指定
openclaw agents start openrouter

方案 C：删除 main agent

Remove-Item -Recurse -Force "C:\Users\dell\.openclaw\agents\main"

交互记录:

用户: 一运行 openclaw dashboard，main agent 的文件 API value 就恢复到原来的 value 数值？这个太诡异了
助手: 这是 OpenClaw 的内部同步机制 bug。建议设置环境变量覆盖，或改用 openrouter agent。

---

错误 5：飞书配对授权失败

日志信息:

OpenClaw: access not configured.
Your Feishu user id: ou_d2b852b3761db02f534badfbb99823e9
Pairing code: AQSVTFZA
Ask the bot owner to approve with:
openclaw pairing approve feishu AQSVTFZA

出现场景: 用户首次使用飞书 bot，未授权

解决方案:

# 批准配对
openclaw pairing approve feishu AQSVTFZA

# 如果配对码变化，使用新的
openclaw pairing approve feishu 8N4WGPFE

交互记录:

系统: OpenClaw: access not configured. Pairing code: AQSVTFZA
助手: 执行 openclaw pairing approve feishu AQSVTFZA 批准配对

---

错误 6：飞书插件重复

日志信息:

Config warnings:
- plugins.entries.feishu: plugin feishu: duplicate plugin id detected; 
  later plugin may be overridden 
  (C:\Users\dell\AppData\Roaming\npm\node_modules\openclaw\extensions\feishu\index.ts)

出现场景: 系统级插件和用户级插件同时存在

插件位置:

位置	路径	优先级
系统级	AppData\Roaming\npm\node_modules\openclaw\extensions\feishu	官方维护
用户级	C:\Users\dell\.openclaw\extensions\feishu	可能过时

解决方案:

# 删除用户级重复插件（推荐）
Remove-Item -Recurse -Force "C:\Users\dell\.openclaw\extensions\feishu"

交互记录:

用户: 先把飞书这两个 plug-in，有重复的 plug-in 先解决一下
助手: 删除用户级插件，保留系统级官方插件

---

第二部分：关键配置命令速查

2.1 查看配置

# 查看全局配置
Get-Content "C:\Users\dell\.openclaw\openclaw.json" | ConvertFrom-Json | ConvertTo-Json -Depth 10

# 查看 agent 配置
Get-Content "C:\Users\dell\.openclaw\agents\main\agent\config.json"

# 查看 auth 配置
Get-Content "C:\Users\dell\.openclaw\agents\main\agent\auth-profiles.json"

# 查看环境变量
echo $env:OPENROUTER_API_KEY
[Environment]::GetEnvironmentVariable("OPENROUTER_API_KEY", "User")

2.2 修改配置

# 设置全局模型
openclaw config set agents.defaults.model.primary "openrouter/moonshotai/kimi-k2.5"

# 设置特定 agent 模型
openclaw config set agents.list[0].model "openrouter/moonshotai/kimi-k2.5"
openclaw config set agents.list[1].model "openrouter/moonshotai/kimi-k2.5"

# 设置环境变量（当前会话）
$env:OPENROUTER_API_KEY = "sk-or-v1-..."

# 设置环境变量（永久）
[Environment]::SetEnvironmentVariable("OPENROUTER_API_KEY", "sk-or-v1-...", "User")

2.3 文件替换

# 替换 API Key
$file = "C:\Users\dell\.openclaw\agents\main\agent\auth-profiles.json"
$content = Get-Content $file -Raw
$content = $content -replace '旧key', '新key'
Set-Content $file $content -NoNewline

2.4 启动命令

# 初始化
openclaw onboard

# 启动 Web UI
openclaw dashboard

# 启动终端 UI
openclaw tui

# 查看 agents
openclaw agents list

# 查看日志
openclaw logs --follow

---

第三部分：自己测试的配置流程图（根据自己实际情况）

开始
  │
  ▼
选择 Provider
  ├──► Moonshot 官方 ──► 输入 API Key ──► 成功 ✅
  │
  ├──► OpenRouter ──► 选择模式
  │       ├──► Auto 模式 ──► 自动选择模型 ──► 成功 ✅（推荐免费用户）
  │       │
  │       └──► 指定 Kimi 2.5 ──► 检查额度
  │               ├──► 额度充足 ──► 成功 ✅
  │               └──► 额度不足 ──► 402 错误 ❌
  │
  └──► 飞书配置 ──► 输入 App ID/Secret ──► 用户配对 ──► 批准配对 ──► 成功 ✅

---

第四部分：关键经验总结

4.1 模型选择建议

用户类型	推荐配置	原因
免费用户	openrouter/auto	自动选择可用模型，无额度问题
稳定需求	moonshot:default	官方 API，无额度限制
指定模型	openrouter/moonshotai/kimi-k2.5	需要付费，免费额度不足

4.2 配置优先级（从高到低）

1. 环境变量: OPENROUTER_API_KEY（最高优先级）
2. 全局配置: openclaw.json 中的 agents.defaults
3. Agent 列表: openclaw.json 中的 agents.list（会覆盖 defaults）
4. 文件配置: auth-profiles.json（会被 dashboard 覆盖）

4.3 已知 Bug

Bug	影响	Workaround
Dashboard 覆盖 main agent 配置	API Key 恢复旧值	使用环境变量或改用 openrouter agent
auth.profiles 不支持 key 字段	无法全局设置 key	使用 agent 级配置文件
模型 ID 格式严格	错误格式导致 Unknown model	使用 openrouter/<provider>/<model> 格式

---

第五部分：完整配置示例

5.1 测试：OpenRouter Auto

# 设置模型
openclaw config set agents.defaults.model.primary "openrouter/auto"
openclaw config set agents.list[0].model "openrouter/auto"
openclaw config set agents.list[1].model "openrouter/auto"

# 设置 API Key（环境变量）
[Environment]::SetEnvironmentVariable("OPENROUTER_API_KEY", "sk-or-v1-...", "User")

# 启动
openclaw dashboard

5.2 测试：Moonshot 官方

# 设置模型
openclaw config set agents.defaults.model.primary "moonshot:default"
openclaw config set agents.list[0].model "moonshot/kimi-k2.5"
openclaw config set agents.list[1].model "moonshot/kimi-k2.5"

# 启动
openclaw dashboard

5.3 飞书完整配置

# 添加飞书 agent
openclaw agents add feishu
# 按提示输入 App ID 和 App Secret

# 批准用户配对（用户发送消息后执行）
openclaw pairing approve feishu <配对码>

# 启动
openclaw dashboard

---

附录：关键日志速查表

关键词	含义	解决方案
No API key found	未配置 API Key	添加 key 到 auth-profiles.json 或环境变量
Unknown model	模型 ID 格式错误	使用正确的 OpenRouter 格式
402 This request requires more credits	免费额度不足	改用 auto 模式或降低 max_tokens
access not configured	飞书未授权	执行 pairing approve
duplicate plugin id	插件重复	删除用户级插件
key 自动恢复	Dashboard 同步 bug	使用环境变量或改用 openrouter agent

---

文档结束

---