> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixroute.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenClaw Invalid Beta Flag 错误修复指南

> 解决使用OpenClaw访问Claude模型时出现的invalid beta flag错误

## 问题概述

### 错误表现

"invalid beta flag"错误可能以多种方式出现，但关键证据始终在Gateway日志和解析后的provider route中。您的OpenClaw助手可能会返回：

* **空白响应**：没有内容返回
* **通用上游400错误**：HTTP 400状态码
* **提供者特定验证消息**：来自provider的详细错误信息

### 错误格式

<CodeGroup>
  ```json Error Response theme={null}
  {
    "type": "error",
    "error": {
      "type": "invalid_request_error",
      "message": "invalid beta flag"
    }
  }
  ```

  ```bash AWS Bedrock Error theme={null}
  ValidationException: invalid beta flag
  ```

  ```bash Google Vertex Error theme={null}
  400 Bad Request: invalid beta flag
  ```
</CodeGroup>

<Info>
  这个错误意味着上游Claude兼容路由拒绝了Anthropic beta header。当前修复方案不是盲目添加 `"beta_features": []`。
</Info>

## 诊断方法

### 快速诊断命令

运行以下命令序列来诊断问题：

```bash theme={null}
openclaw logs --follow
openclaw models status
openclaw config validate
openclaw gateway status
openclaw doctor
```

<Warning>
  不要仅从聊天界面分类问题。请使用 `openclaw logs --follow`、`openclaw models status` 和活跃的model ref来分类。
</Warning>

### 错误分类

<Tabs>
  <Tab title="按路由类型">
    | 路由类型                          | 错误表现     | 检查项                             |
    | ----------------------------- | -------- | ------------------------------- |
    | Direct Anthropic + 1M context | 长上下文请求失败 | `params.context1m` 配置           |
    | Amazon Bedrock                | AWS验证错误  | provider shape, region, 凭证      |
    | Custom proxy                  | header拒绝 | `models.providers.<id>.headers` |
    | Stale OpenClaw build          | 兼容性问题    | `openclaw --version`            |
    | Invalid config                | 配置损坏     | `openclaw config validate`      |
  </Tab>

  <Tab title="按错误原因">
    **失败分支分析：**

    | 分支                                     | 失败原因                                                        | 检查项                                              | 最佳修复                               |
    | -------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------ | ---------------------------------- |
    | Direct Anthropic + 1M context          | `params.context1m: true` 映射到 Anthropic beta header          | `agents.defaults.models["anthropic/..."].params` | 禁用 `context1m` 或使用合格凭证             |
    | Bedrock route shaped like Anthropic    | Bedrock使用AWS auth和Converse streaming，不使用直接Anthropic headers | `models.providers`, region, AWS env/profile      | 使用 `amazon-bedrock` provider shape |
    | Custom proxy with explicit beta header | Proxy拒绝不支持的 `anthropic-beta`                                | `models.providers.<id>.headers`                  | 移除或收窄header                        |
    | Stale OpenClaw build                   | 旧provider行为转发了当前build抑制的headers                             | `openclaw --version`, `openclaw doctor`          | 更新并重新运行doctor                      |
    | Invalid config after manual edit       | Gateway加载了部分或损坏的provider entry                              | `openclaw config validate`, `.rejected.*` files  | 使用 `doctor --fix` 修复               |
  </Tab>
</Tabs>

## 修复方案

### 方案选择指南

<CardGroup cols={2}>
  <Card title="Custom Proxy" icon="server">
    使用自定义代理或中继服务
  </Card>

  <Card title="Direct Anthropic" icon="bolt">
    直接使用Anthropic API
  </Card>

  <Card title="Amazon Bedrock" icon="aws">
    使用AWS Bedrock服务
  </Card>

  <Card title="Google Vertex" icon="google">
    使用Google Vertex AI
  </Card>
</CardGroup>

<Info>
  选择合适的修复方案取决于您实际需要使用的provider route。不要为了消除错误而切换到不同的provider，除非该route也能满足您的访问、合规或成本需求。
</Info>

### 详细修复步骤

#### 方案1：Custom Proxy或Relay修复

保留代理，但不要假装它是原生Anthropic（除非它确实是）。使用显式provider id，设置正确的API shape，并移除不支持的beta headers。

<Accordion title="Custom Proxy 配置示例">
  ```json theme={null}
  {
    "models": {
      "providers": {
        "relay": {
          "baseUrl": "https://relay.example.com",
          "api": "anthropic-messages",
          "apiKey": "${RELAY_API_KEY}",
          "models": [
            {
              "id": "claude-opus-4-6",
              "name": "Claude Opus 4.6 via relay",
              "contextWindow": 200000,
              "maxTokens": 8192
            }
          ]
        }
      }
    },
    "agents": {
      "defaults": {
        "model": { "primary": "relay/claude-opus-4-6" }
      }
    }
  }
  ```
</Accordion>

**检查清单：**

* 确认proxy支持的API shape
* 移除不支持的 `anthropic-beta` header
* 验证model id和provider配置匹配

#### 方案2：Direct Anthropic Long-context修复

如果您确实需要1M context，使用direct Anthropic并确认凭证合格。如果只是因为旧指南建议而启用，请禁用它。

<Accordion title="Direct Anthropic 配置示例">
  ```json theme={null}
  {
    "agents": {
      "defaults": {
        "models": {
          "anthropic/claude-opus-4-6": {
            "params": { "context1m": false }
          }
        }
      }
    }
  }
  ```
</Accordion>

**检查清单：**

* 确认是否真的需要1M context
* 检查凭证是否支持long-context beta
* 验证model eligibility

#### 方案3：Amazon Bedrock修复

使用Bedrock provider，不要将AWS凭证粘贴到错误的位置。

<Accordion title="Bedrock 配置检查项">
  **关键检查项：**

  * `AWS_REGION` 或 `AWS_DEFAULT_REGION` 环境变量
  * AWS凭证链可用性
  * 目标region的model访问权限
  * Discovery权限：`bedrock:ListFoundationModels`、`bedrock:ListInferenceProfiles`

  <Warning>
    不要在model provider config中使用Anthropic API key。Bedrock auth使用AWS凭证、region和权限（如model invoke/list access）。
  </Warning>
</Accordion>

#### 方案4：Google Vertex或Gemini-style Routes修复

保持Google拥有的auth flow和model route，与direct Anthropic假设分离。

<Accordion title="Vertex AI 修复步骤">
  1. 保持Google认证流程
  2. 移除显式beta header
  3. 验证活跃provider route：
     ```bash theme={null}
     openclaw models status
     ```
  4. 确认model id与provider route匹配
</Accordion>

#### 方案5：配置损坏或旧安装修复

当错误在更新或手动编辑后出现时，假设配置可能已过时或部分损坏。

<Accordion title="配置诊断命令">
  ```bash theme={null}
  openclaw --version
  openclaw config validate
  openclaw doctor
  openclaw gateway status --deep
  ```

  <Warning>
    如果验证失败，不要将小型替换JSON对象复制到整个配置中。使用 `openclaw config set`、`config.patch` 或 `openclaw doctor --fix`，以便活动文件保留所需的元数据、Gateway模式、auth和provider shape。
  </Warning>
</Accordion>

### 快速修复步骤

<Steps>
  <Step title="Custom Anthropic-compatible proxy">
    检查您的 `models.providers` 条目，移除任何硬编码的beta header（除非您的proxy明确支持它）：

    ```json theme={null}
    {
      "models": {
        "providers": {
          "my-proxy": {
            "api": "anthropic-messages",
            "baseUrl": "https://proxy.example.com",
            "headers": {
              "anthropic-beta": "REMOVE_THIS_UNLESS_SUPPORTED"
            }
          }
        }
      }
    }
    ```
  </Step>

  <Step title="Direct Anthropic 1M context">
    除非您知道凭证合格，否则禁用beta：

    ```json theme={null}
    {
      "agents": {
        "defaults": {
          "models": {
            "anthropic/claude-opus-4-6": {
              "params": {
                "context1m": false
              }
            }
          }
        }
      }
    }
    ```
  </Step>

  <Step title="Bedrock">
    移动到专用provider shape，而不是Anthropic兼容header调整。Bedrock auth使用AWS凭证、region和权限（如model invoke/list access）；它不需要在model provider config中使用Anthropic API key。
  </Step>
</Steps>

**每次更改后运行：**

```bash theme={null}
openclaw config validate
openclaw gateway restart
openclaw logs --follow
```

## 预防措施

### 最佳实践

<Steps>
  <Step title="规划provider route">
    安装前决定：direct Anthropic行为、AWS/GCP控制、区域代理还是本地模型。不要只复制model id而不复制使其工作的route假设。
  </Step>

  <Step title="使用内置provider">
    使用 `openclaw onboard` 和provider docs。内置provider拥有自己的auth和model picker行为。自定义 `models.providers` 条目用于覆盖、本地runtime和代理，而不是替代每个支持的provider。
  </Step>

  <Step title="上线前验证">
    配置后运行：

    ```bash theme={null}
    openclaw config validate
    openclaw doctor
    openclaw gateway status
    ```

    在测试每个连接的channel之前，通过Control UI发送一条测试消息。
  </Step>

  <Step title="记录route owner">
    记录哪个provider拥有auth、rate limits、region、model discovery和beta行为。这防止未来队友将direct Anthropic header添加到Bedrock或proxy route。
  </Step>

  <Step title="保持更新">
    OpenClaw provider行为、Bedrock model discovery、Vertex支持和Anthropic beta资格可能会变化。在重新启用headers或long-context选项之前，重新检查provider docs。
  </Step>
</Steps>

<Info>
  对于大规模部署OpenClaw的团队，在配置管理中编码provider route和允许的headers。强制执行的目标不再是"总是添加beta feature禁用标志"；而是"不要让不支持的beta headers到达非原生routes"。
</Info>

### 验证清单

<Check>
  确认使用的 provider route类型（direct Anthropic、Bedrock、Vertex或custom proxy）
</Check>

<Check>
  运行 `openclaw config validate` 确认配置有效
</Check>

<Check>
  检查 `openclaw gateway status` 确认Gateway正常运行
</Check>

<Check>
  检查 `models.providers.<id>.headers` 中是否有不支持的beta headers
</Check>

<Check>
  确认 `openclaw --version` 是最新版本
</Check>

## 常见问题

<Accordion title="应用修复后仍然看到错误？">
  首先检查active model ref和provider route。应用于 `anthropic/...` 的修复不会影响 `relay/...` 或 `amazon-bedrock/...` route。然后运行 `openclaw config validate` 并检查 `models.providers.<id>.headers` 中是否有显式 `anthropic-beta`。
</Accordion>

<Accordion title="更新后出现错误？">
  更新可能会收紧provider安全行为或拒绝旧版本容忍的配置。检查 `openclaw --version`，运行 `openclaw doctor`，并将您的活跃provider entry与当前provider docs进行比较。
</Accordion>

<Accordion title="可以使用部分beta features吗？">
  只能在支持对应header的routes上。在当前OpenClaw中，最清晰的已发布示例是Anthropic 1M context：仅当凭证合格时，在支持的Anthropic Opus/Sonnet模型上设置 `params.context1m: true`。对于proxy或managed routes，不要添加beta headers（除非该route的docs明确支持它们）。
</Accordion>

<Accordion title="为什么别人的设置不需要这些更改？">
  他们可能使用不同的provider route、更新的OpenClaw build，或在转发前剥离不支持headers的proxy。比较active model ref和provider config，而不仅仅是model name。
</Accordion>

<Accordion title="这是OpenClaw或SDK的bug吗？">
  通常是配置对齐问题，而不是一个普遍的bug。OpenClaw可以路由到原生provider、托管云provider和自定义proxy。同一可见错误可能由不支持的headers、旧builds、损坏的配置或不合格的long-context凭证引起。
</Accordion>

<Accordion title="未来版本会修复吗？">
  部分已经改变：当前OpenClaw抑制非直接Anthropic兼容endpoints的隐式beta headers。剩余的失败通常来自显式headers、旧安装或provider特定资格。保持OpenClaw更新，但仍需自己验证custom headers。
</Accordion>

<Accordion title="如何知道是否无意中使用了beta feature？">
  搜索您的config中的 `anthropic-beta`、`context1m` 和 `agents.defaults.models` 下的provider特定params。然后使用 `openclaw models status` 检查解析后的model route。Beta feature只有在附加到实际处理请求的route时才重要。
</Accordion>

## 相关资源

### MixRoute文档

<CardGroup cols={2}>
  <Card title="OpenClaw集成指南" icon="plug" href="/cn/integrations/openclaw">
    了解如何将MixRoute API集成到OpenClaw中
  </Card>

  <Card title="API参考" icon="book" href="/cn/api-reference/models">
    查看完整的API文档和开发者指南
  </Card>

  <Card title="快速开始" icon="rocket" href="/cn/quickstart">
    三步开始使用MixRoute API
  </Card>

  <Card title="错误代码参考" icon="exclamation-triangle" href="/cn/faq/error-code">
    查看所有API错误代码和解决方案
  </Card>
</CardGroup>

### OpenClaw资源

<CardGroup cols={2}>
  <Card title="OpenClaw文档" icon="book" href="https://docs.openclaw.ai">
    OpenClaw官方文档
  </Card>

  <Card title="GitHub仓库" icon="github" href="https://github.com/openclaw/openclaw">
    OpenClaw源代码和issue跟踪
  </Card>

  <Card title="社区讨论" icon="comments" href="https://github.com/openclaw/openclaw/discussions">
    获取社区支持和分享经验
  </Card>

  <Card title="更新日志" icon="history" href="https://github.com/openclaw/openclaw/releases">
    查看最新版本更新
  </Card>
</CardGroup>

***

<Tip>
  如果您在使用MixRoute API时遇到其他问题，请查看我们的[错误代码参考](/en/faq/error-code)或[联系我们](/en/contact)获取技术支持。
</Tip>