企业官网建设流程全解析

Duel-Agents 是一款 IDE 原生的多模型路由层，支持把 Claude Code、Cursor、Codex CLI、OpenClaw 等工具的 LLM 请求统一转发到 Duel 代理，并挑选最省钱且合格的回答。安装过程中如果遇到401、Invalid API key format、OpenClaw 无法启动等问题，本文提供一份完整的故障排查清单，每个问题都附带成因分析和修复步骤。🔍

第一步：先运行 doctor 命令定位问题

在逐条排查之前，建议先运行官方自带的体检命令，它会验证密钥格式并探测线上连通性：

export DUEL_API_KEY=duel_yourprefix_yoursecret npx @duel-agents/install doctor

doctor 的输出有四种状态：格式合法但连不通、密钥被拒绝（401/403）、格式非法、以及完全正常。具体判定逻辑见 packages/cli/src/install.ts 中的runDoctor，联网探测逻辑在 packages/core/src/config.ts 的checkConnectivity。

💡 小技巧：如果 doctor 提示"Key format is valid but live check failed"，说明你的密钥没问题，只是代理暂时不可用，稍后重试即可。

7 个常见问题速查表

下面逐一展开讲解。

1. Invalid API key format：密钥格式不对怎么办？

这是新手最常碰到的错误。Duel-Agents不接受原始的 Anthropic 或 OpenAI 密钥，所有工具都必须使用专门的 Duel API 密钥，其格式被严格校验：

duel_<8位前缀>_<32位字母数字密钥>

校验规则是 packages/core/src/config.ts 中的正则API_KEY_PATTERN，任何一项不符（前缀拼错、少了下划线、密钥位数不对）都会直接报Invalid API key format，并提示你去 dashboard 创建密钥。

修复步骤：

1. 登录 Duel Agents dashboard（duelagents.com/dashboard/settings），先订阅再创建 API key；
2. 完整复制密钥（含duel_前缀，注意别丢字符、别带多余空格）；
3. 重新export DUEL_API_KEY=duel_...后再次运行 doctor 验证。

⚠️ 常见坑：从终端复制密钥时把换行或空格也带了进来。validateApiKey会先trim，但如果中间被截断成两段，校验依然会失败。

2. 401 错误：密钥被吊销或订阅失效

doctor 或 SDK 请求返回401（或403）时，说明密钥格式是对的，但服务端拒绝了它。典型输出是：

✗ API rejected your key (401). Create or renew a key at https://duelagents.com/dashboard/settings

在 SDK 中这类错误会被封装为DuelAuthError（定义见 packages/sdk/src/errors.ts），携带status字段，方便程序化判断。

常见原因与修复：

• 密钥已被吊销：到 dashboard 的 billing/settings 页面新建一个密钥，替换本地DUEL_API_KEY；
• 订阅已过期：先续费，密钥才能继续被代理接受；
• 多环境串了密钥：检查~/.claude/.env、项目.env、~/.openclaw/.env里是否残留旧密钥，把新密钥重新写入后重启对应工具。

3. Could not reach Duel API：代理不可达怎么排查？

这个提示的含义是：密钥格式可能完全合法，只是连不上代理。checkConnectivity会依次尝试/models、/health和根路径 HEAD 请求（每次 15 秒超时），全部失败后才报"Could not reach Duel API at https://duelagents.com/v1"。

按顺序排查：

1. 稍后重试——代理端偶发故障时，等待几分钟通常自愈；
2. 检查本地网络——代理地址是https://duelagents.com/v1，确认公司网络/代理没有拦截该域名；
3. 检查DUEL_PROXY_URL——如果你设置了自定义代理地址，确保它是合法http(s)URL（校验逻辑在getProxyUrl）。配置错误的完整提示是Invalid DUEL_PROXY_URL "..."，此时把变量删掉恢复默认值即可。

unset DUEL_PROXY_URL npx @duel-agents/install doctor # 重新验证

4. OpenClaw 无法启动：验证配置并恢复备份

安装 OpenClaw 集成会改写~/.openclaw/openclaw.json（合并duelprovider 并把默认模型设为duel/duel-auto）。如果安装时中断或原文件本身有语法问题，OpenClaw 可能直接拒绝启动。

修复步骤：

1. 先跑官方校验命令，它会直接指出配置错误：

   openclaw config validate

2. 如果确认是安装造成的损坏，安装器在改写前会自动生成备份openclaw.json.bak，把它复制回openclaw.json即可恢复；

3. 对照参考配置 templates/openclaw.duel.json5 核对providers.duel块是否完整。

💡 注意：Duel 密钥存放在~/.openclaw/.env中，通过${DUEL_API_KEY}引用，不会明文写进openclaw.json。

5. OPENCLAW_CONFIG_PATH must be inside：自定义路径越界

当你设置了OPENCLAW_CONFIG_PATH环境变量指向自定义配置文件时，安装器要求该路径必须位于~/.openclaw目录内部，否则直接抛出：

OPENCLAW_CONFIG_PATH must be inside /home/you/.openclaw. Got: /somewhere/else.json

这个限制（实现在 packages/core/src/index.ts 的resolveOpenClawConfigPath）是为了防止密钥和环境变量被写进不受控的位置。

修复方式：

• 如果只是测试时随手设的变量，直接取消设置：unset OPENCLAW_CONFIG_PATH，安装器会自动使用默认的~/.openclaw/openclaw.json；
• 如果确实需要自定义配置，把文件移动到~/.openclaw/下再指向它。

6. Cursor 仍在使用 OpenAI：检查模型覆盖设置

Cursor 集成和其他工具不同——安装器只会把DUEL_API_KEY写入项目.env并拷贝 skill，必须手动完成 UI 设置，否则 Cursor 依然走原来的 OpenAI 通道。

手动配置清单（参考 templates/cursor-models.override.md）：

1. 打开Cursor → Settings → Models；
2. 启用Override OpenAI Base URL；
3. Base URL 填写https://duelagents.com/v1（注意结尾的/v1别漏）；
4. API key 一栏填你的duel_*密钥，而不是OpenAI 密钥；
5. 重新加载窗口（Reload Window），选择走覆盖通道的模型。

仍不生效时检查：Base URL 是否拼错、密钥字段是否误填了sk-开头的 OpenAI key、项目.env里的DUEL_API_KEY是否与 UI 中填写的一致（模板见 templates/env.cursor.example）。

7. Skill 拷贝失败：重新构建安装器包

运行安装后如果提示找不到集成资产（如Integration assets not found ... Reinstall @duel-agents/install），说明安装包里的 skill 文件缺失——skill 是随 npm 包一起分发的（位于integrations/目录），但某些场景下包内容不完整。

两种修复路径：

• 发布包场景：卸载后重新安装@duel-agents/install，再运行一次安装命令；
• 源码开发场景：在仓库根目录重新执行npm run build，构建脚本 packages/cli/scripts/copy-integrations.mjs 会把 integrations/ 下的 Claude 插件、Cursor skill、OpenClaw skill 复制进 CLI 包。

预防性自查：环境变量与配置文件速查

大多数故障其实源于环境配置，养成习惯先核对下表：

各目标工具的环境变量写法可直接参考 templates/ 目录下的示例文件，例如 templates/env.codex.example（Codex 需要OPENAI_BASE_URL+OPENAI_API_KEY双变量）。安装后别忘了重启对应工具让新配置生效。✅

总结

Duel-Agents 的故障排查可以归纳为一句话：先跑 doctor 定状态，再按症状对号入座。

• 密钥类问题（格式错误、401）→ 回 dashboard 重建密钥；
• 网络类问题（代理不可达）→ 检查网络与DUEL_PROXY_URL，稍后重试；
• 集成类问题（OpenClaw 不启动、Cursor 不生效、skill 缺失）→ 校验配置、恢复备份、重建安装包。

完整症状对照表也可以随时查阅 README.md 末尾的 Troubleshooting 章节，配合本文的详细步骤使用效率最高。