火山引擎API Key绑定后模型不可用，常见原因包括模型ID拼写错误、Endpoint ID区域不匹配、未在火山方舟开通模型实例；需确认模型状态为“已开通”，严格核对api_key、endpoint_id、model_name三要素，并强制刷新OpenClaw配置。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
火山引擎API Key绑定后模型不可用，说明凭证已录入但服务链路未通，常见于模型ID拼写错误、Endpoint ID区域不匹配、或未在火山方舟后台开通对应模型实例。
确认模型是否已在火山方舟真实开通
登录火山引擎控制台 → 进入「火山方舟」→「模型列表」，检查目标模型（如doubao-lite-32k）状态是否为「已开通」且右侧显示绿色对勾。若为灰色「未开通」，点击「开通」按钮并等待状态变更——【未开通的模型即使填对Key和Endpoint也会返回404】。
注意：部分模型（如doubao-pro系列）需单独申请配额，开通按钮旁会提示“配额不足”，此时需提交工单或联系商务。
核对Endpoint ID与模型名称的严格一致性
方法一：从火山方舟模型详情页直接复制
打开已开通模型的详情页 → 滚动至「推理接入点」区域 → 找到「Endpoint ID」字段 → 点击复制按钮（格式必须为ep-xxxxxxxxxxxxxxxxxxxx）。不要手动输入，避免字母o/0、l/1混淆。
方法二：用模型列表接口反向验证
在终端执行curl命令测试：curl -H "Authorization: Bearer " https://ark.cn-beijing.volces.com/api/v1/models。若返回JSON中包含目标模型ID，则说明Key有效且模型已发布；若返回空数组或报错，则模型未部署到该区域。
检查OpenClaw配置文件中的三要素是否全部生效
第一步：执行openclaw config show，确认输出中volcengine区块下同时存在api_key、endpoint_id、model_name三项值。
第二步：逐项比对原始输入
• api_key：必须是apikey-开头的字符串，不含Bearer前缀，无多余空格；
• endpoint_id：必须是ep-开头，且与火山方舟页面复制的完全一致；
• model_name：必须与火山方舟后台「模型ID」字段值一字不差，包括大小写和连字符（例如doubao-lite-32k不能写成doubao_lite_32k）。
【model_name拼写错误会导致404而非401，极易误判为Key问题】
强制刷新OpenClaw网关并重载配置
① 在终端执行openclaw gateway stop，等待进程退出；
② 删除~/.openclaw/openclaw.json中volcengine节点下的全部字段；
③ 重新运行openclaw onboard --auth-choice volcengine-api-key，严格按提示顺序粘贴三项值；
④ 执行openclaw gateway start，观察日志中是否出现“volcengine: connected”字样。
这一步操作起来很简单，直接把文件拖进去就行。但若跳过②清空旧配置，OpenClaw会沿用残留字段导致绑定失败。
