给 OpenClaw 配 Kimi API Key：申请、安全注入与 6 个常见报错处理
AI先给结论：接不上 Kimi，九成不是 OpenClaw 的问题，是 Key 本身——填错、过期、额度用尽、或者模型名写错。正确顺序是：在 Moonshot AI 开放平台创建 Key → 用环境变量注入、不写进代码库 → 先用一条 curl 验证 Key 和模型可用 → 最后才回 OpenClaw 里填配置。把验证放在前面，能省掉大半排查时间。
一、先确认三个前提
- OpenClaw 已经装好并跑通过一次。本地部署步骤见站内《本地免费部署 OpenClaw（龙虾模型）》；完整搭建与工作流配置见旗舰教程《龙虾(OpenClaw)搭建 Kimi 模型智能体保姆教程》。本篇不重复安装部分。
- 有 Moonshot AI 开放平台账号，且已完成实名/绑定（不同时期要求不同，以控制台提示为准）。
- 账户里有可用额度。新账号的赠送额度、有效期、可用模型范围都会变，一律以控制台「账户 / 用量」页面当期显示为准（2026-11 查阅）。
二、创建 API Key
- 登录 Moonshot AI 开放平台控制台，进入「API Key 管理」。
- 点「创建」，给 Key 起个能认出用途的名字（例如
openclaw-local），便于以后单独轮换。 - Key 只在创建时完整显示一次，立刻存进密码管理器。关掉弹窗后再想看全文是不行的，只能删了重建。
- 别把 Key 贴进聊天记录、截图、issue 或代码仓库。一旦泄露，第一动作是删除重建，不是改个名字继续用。
建议按环境分开建 Key：本地开发一个、线上一一个，这样轮换和排查额度时互不干扰。
三、安全注入：环境变量优先
最稳的做法是把 Key 放环境变量，由进程启动时读取，配置文件里只引用变量名：
# macOS / Linux
export MOONSHOT_API_KEY="sk-你的Key"
# Windows PowerShell
$env:MOONSHOT_API_KEY = "sk-你的Key"桌面环境想长期生效，写进 .env 并确认 .env 已加入 .gitignore；服务化部署就写进 systemd / 进程管理器的环境变量配置，别写进 anyone 都能读的启动脚本注释里。
OpenClaw 里具体填哪个配置项、用哪个字段名，请按你所用版本的官方文档或旗舰教程里的配置段填写——不同版本的配置文件位置和 provider 写法不一致，我这里不猜。原则是统一的：引用环境变量名，不贴 Key 明文。
四、启动前先用 curl 验证连通
别急着启动智能体。先单独打一次接口，确认 Key 有效、网络能通、模型名正确：
curl -s https://api.moonshot.cn/v1/models \
-H "Authorization: Bearer $MOONSHOT_API_KEY"能返回模型列表就说明 Key 与网络都正常。接着发一条最小对话请求（把 model 换成控制台里你账号实际可用的模型名）：
curl -s https://api.moonshot.cn/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $MOONSHOT_API_KEY" \
-d '{"model":"在此填控制台实际可用模型名","messages":[{"role":"user","content":"只回复 OK"}],"stream":false}'这一步能提前把「Key 错」「模型名不存在」「余额不足」「被代理挡住」四类问题分开。接口格式参考 Moonshot AI 开放平台官方文档（platform.moonshot.cn/docs，2026-11 查阅）。
五、六个常见报错对照
| 现象 | 原因 | 处理 |
|---|---|---|
| 401 invalid api key / authentication error | Key 复制缺字符、带了空格、已删除或填成别的厂商的 Key | 重新创建 Key，用环境变量注入并 echo 长度核对；确认 Bearer 后有空格且无多余引号 |
| 404 / model not found | 模型名写错，或该账号无此模型权限 | 用 /v1/models 列出可用模型，原样复制名称 |
| 429 rate limit / 请求过于频繁 | 触发分钟级或并发限制 | 降并发、加退避重试；批量任务排队而非同时发。具体阈值以控制台当期说明为准 |
| 余额不足 / quota exceeded | 赠送额度用完或过期 | 控制台查「账户 / 用量」，充值或换 Key；注意赠送额度常有有效期 |
| context length 超限 | 对话历史或系统提示太长 | 缩短历史、开启摘要/裁剪，或换更长上下文的模型 |
| 连接超时 / SSL 错误 | 本机代理、企业网络拦截、DNS 异常 | 先用 curl 直连验证；关掉系统代理重试；确认没走错 base_url |
六、Key 的日常管理
- 定期轮换：给每个环境单独 Key，轮换时只停一个环境。
- 日志脱敏：排查时别把完整 Key 打进日志；需要贴报错时把中间段替换成
***。 - 用量告警：控制台设置用量提醒，避免 Agent 长任务跑一夜把额度耗光。
- 别提交仓库：
.env、*.local、配置备份文件都进.gitignore；一旦误提交，先删 Key 再清历史，顺序别反。
七、FAQ
Q：curl 能通，但 OpenClaw 里还是报 401？ 说明 Key 没问题，是配置没读到——检查进程启动时环境变量是否真的传进去了（服务化部署常见），以及配置里是不是还留着旧的明文 Key 覆盖了变量。
Q：一个 Key 能给多个 Agent 用吗？ 可以，但会共用额度和限流，出问题不好定位。建议按用途拆开。
Q：Key 需要写进数据库吗？ 不需要。环境变量或密钥管理方案都够用，写进数据库反而多一份泄露面。
Q：模型名和价格会不会变？ 会。所有模型名、上下文长度、计费与限流数值都以开放平台控制台当期说明为准，本文不复述具体数值，避免过期信息误导。
小结
接 Kimi 的稳定顺序是：创建 Key → 环境变量注入 → curl 验证 → 再填 Agent 配置 → 最后跑长任务。把「Key 是否有效」和「配置是否读得到」分成两步验证，报错时一眼就能定位。至于 OpenClaw 里的具体配置项和工作流设置，回到那篇保姆教程按版本照做即可。