> ## 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="/zh-hant/integrations/openclaw">
    了解如何將MixRoute API集成到OpenClaw中
  </Card>

  <Card title="API參考" icon="book" href="/zh-hant/api-reference/models">
    查看完整的API文檔和開發者指南
  </Card>

  <Card title="快速開始" icon="rocket" href="/zh-hant/quickstart">
    三步開始使用MixRoute API
  </Card>

  <Card title="錯誤代碼參考" icon="exclamation-triangle" href="/zh-hant/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>