常见问题

关于接入 AI 编程工具#

Claude Code 如何开启深度思考模式？#

1. 编辑 Claude Code 的配置文件~/.claude/settings.json，在env中新增"CLAUDE_CODE_EXTRA_BODY": "{\"thinking\":{\"type\":\"enabled\"}}"。
2. 配置完成后执行命令claude重新启动。

OpenCode 如何开启深度思考模式？#

1. 编辑 OpenCode 的配置文件~/.config/opencode/opencode.json，在<Model_Name>模型配置中新增options配置，内容为 {"thinking": {"type": "enabled"}}。参考示例如下：

   JSON

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23{
   "$schema": "https://opencode.ai/config.json",
   "provider": {
       "volcengine-plan": {
           "npm": "@ai-sdk/openai-compatible",
           "name": "volcengine",
           "options": {
               "baseURL": "https://ark.cn-beijing.volces.com/api/coding/v3",
               "apiKey": "<ARK_API_KEY_FROM_VOLCENGINE_ARK_CONSOLE>"
           },
           "models": {
               "<Model_Name>": {
                   "name": "<Model_Name>",
                   "options": {
                       "thinking": {
                           "type": "enabled"
                       }
                   }
               }
           }
       }
   }
   }
   

2. 配置完成后执行命令opencode重新启动。如果在对话时仍看不到Thinking信息，可以在输入框按ctrl+p，搜索think，选中Show thinking，则可以查看思考的信息。

OpenClaw 如何开启深度思考模式？#

OpenClaw 支持以下几种方式开启深度思考模式：

1. 在当前消息临时开启深度思考模式

在消息前面添加内联指令：/think:<level> 或/t <level>，示例如下：

1
2
3/think:high 你的问题
# 或者使用简写模式
/t high 你的问题

2. 在会话级别开启深度思考模式

单独发送一条指令消息：/think:<level> 或/t <level>，示例如下：

1
2
3/think:high
# 或者使用简写模式
/t high

3. 全局配置开启深度思考模式

使用 config 命令修改全局配置：openclaw config set agents.defaults.thinkingDefault <level>，示例如下：

1
2
3
4
5openclaw config set agents.defaults.thinkingDefault high
# 重启 gateway 才能生效
openclaw gateway restart
# 查看配置是否生效
openclaw config get agents.defaults.thinkingDefault

使用 OpenClaw 时，出现不支持 developer role 的报错，如何解决？#

问题描述
在 OpenClaw Chat 中发送消息后没有响应，错误信息如下：

1
2HTTP 400: The parameter messages.role specified in the request are not valid:
invalid value: developer, supported values are: system, assistant, user, tool.

问题原因
API 兼容性问题：方舟 API 不支持 developer role（OpenAI 新版 API 格式）。
解决方案

1. 在 model 对象内部添加 compat 兼容性配置 "compat": { "supportsDeveloperRole": false }，示例如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37{
  "models": {
    "providers": {
      "volcengine-plan": {
        "baseUrl": "https://ark.cn-beijing.volces.com/api/coding/v3",
        "apiKey": "<ARK_API_KEY>",
        "api": "openai-completions",
        "models": [
          {
            "id": "<Model_Name>",
            "name": "<Model_Name>",
            "reasoning": true,
            "input": ["text"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 200000,
            "maxTokens": 8192,
            "compat": {
              "supportsDeveloperRole": false
            }
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "volcengine-plan/<Model_Name>"
      }
    }
  }
}

2. 配置修改完成后，执行以下命令重启 gateway。

   Bash

   1
   2pkill -f openclaw
   openclaw gateway restart
   

在 OpenClaw 中无法识别图片，如何处理？#

1. 确认模型支持图片输入。

检查配置文件 ~/.openclaw/openclaw.json 中的模型input字段是否包含 image 输入类型。以模型 doubao-seed-2.1-lite 为例，配置信息如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14"models": {
    "providers": {
        "volcengine-plan": {
            "models": [
                  {
                    "id": "doubao-seed-2.1-lite",
                    "name": "doubao-seed-2.1-lite",
                    "input": ["text", "image"],
                    ...
                  }
            ]
        }
    }
}

2. 配置 Image Model，并检查模型别名配置。

在 agents.defaults.imageModel 中显式设置用于图片识别的模型，确保 agents.defaults.models 中包含正确的模型别名。

1
2
3
4
5
6
7
8
9
10
11
12
13"agents": {
    "defaults": {
      "imageModel": {
        "primary": "volcengine-plan/doubao-seed-2.1-lite"
      },
      "models": {
        "volcengine-plan/doubao-seed-2.1-lite": {
          "alias": "volcengine"
        }
      },
      ...
    }
  }

3. 重启 Gateway 使配置生效，然后即可在 OpenClaw 中识别图片。

1openclaw gateway restart

安装 OpenClaw 时报错 “gateway connect failed: Error: pairing required”，如何处理？#

执行以下命令删除设备和身份，然后重新安装网关并重启解决该问题。

1
2
3
4rm -rf ~/.openclaw/devices
rm -rf ~/.openclaw/identity
openclaw gateway install --force
openclaw gateway start

配置 OpenClaw 时报错 “run error: 404 The model or endpoint xxx does not exist or you do not have access to it”，如何处理？#

1. 请检查以下两个配置文件中的baseurl等信息是否一致。

   • ~/.openclaw/openclaw.json：全局配置

   • ~/.openclaw/agents/main/agent/models.json：单个 Agent 本地模型配置，优先级高，会覆盖全局配置。

2. 两个配置文件不一致时，需先删除~/.openclaw/agents/main/agent/models.json。

3. 根据 OpenClaw 配置文档配置~/.openclaw/openclaw.json，配置完成后保存文件并执行命令重启服务。

   Bash

   1openclaw gateway restart
   

关于飞书插件的使用#

如何升级飞书插件版本？#

1. 执行openclaw -v命令查看已安装的 OpenClaw 的版本，新版插件对 OpenClaw 的版本要求如下。若低于该版本，插件运行可能出现异常，可执行 npm install -g openclaw 命令升级。

   • Linux/macOS：2026.2.26 及以上

   • Windows：2026.3.2 及以上

2. 执行以下命令升级飞书官方插件到最新版本。

   Bash

   1npx -y @larksuite/openclaw-lark-tools update
   

   若执行该命令行出错，可在命令行前 增加 sudo 重新执行。

在使用飞书插件时遇到问题，如何操作？#

1. 通过在飞书机器人对话框中输入以下内容排查问题并解决。

   1. /feishu start：确认是否安装成功。

   2. /feishu doctor：检查配置是否正常。

   3. /feishu auth：批量完成用户授权。

   4. 插件中内置了常见问题的解决方案，可在对话框中直接输入问题获取解答。

2. 在终端执行以下命令进行修复。

   Bash

   1
   2
   3
   4# 查看问题，自主修复
   npx @larksuite/openclaw-lark-tools doctor
   # 自动修复
   npx @larksuite/openclaw-lark-tools doctor --fix
   

3. 在终端执行以下命令获取信息，在飞书群里反馈解答。

   Bash

   1
   2
   3
   4# 执行以下命令，查看版本信息，辅助排查
   npx @larksuite/openclaw-lark-tools info
   # 执行以下命令，查看详细配置信息
   npx @larksuite/openclaw-lark-tools info --all
   

如何配置飞书机器人，使其具备流式输出、耗时显示及状态展示能力？#

1. 执行以下命令对飞书机器人进行配置。

   • 开启流式输出
   Bash

   1openclaw config set channels.feishu.streaming true
   

   • 关闭流式输出
   Bash

   1openclaw config set channels.feishu.streaming false
   

   • 开启耗时
   Bash

   1openclaw config set channels.feishu.footer.elapsed true
   

   • 开启状态展示
   Bash

   1openclaw config set channels.feishu.footer.status true
   

2. 配置完成后，需要执行以下命令重启服务。

   Bash

   1
   2openclaw gateway stop
   openclaw gateway run
   

如何修改飞书机器人在群内的回复方式？#

目前插件在群内默认的方式为：只有@机器人才会回复。

• 模式1：只有@机器人才回复。

  在终端执行以下命令配置飞书机器人，配置完成后重启服务。

  Bash

  1
  2# 设置需要 @ 才回复
  openclaw config set channels.feishu.requireMention true --json
  

  完整的配置示例如下：

  JSON

  1{"channels": {"feishu": {"enabled": true,"appId": "你的AppID（登录飞书开放平台，进入应用详情的凭证与基础信息获取）","appSecret": "你的AppSecret（登录飞书开放平台，进入应用详情的凭证与基础信息获取）","requireMention": true,"groupPolicy": "open"}}}
  

• 模式2：不用@机器人，所有消息都回复。

1. 在 [飞书开放平台](https://open.feishu.cn/app?lang=zh-CN)，单击创建的飞书开放应用。

2. 在左侧菜单中选择”开发配置 > 权限管理“，单击”开通权限“按钮，添加权限”获取群组中所有消息（敏感权限）“，然后单击”确认开通权限“。

3. 重新发布应用。

4. 在终端执行以下命令配置飞书机器人，配置完成后重启服务。

    ```Bash
    # 设置不需要 @ 也回复
    openclaw config set channels.feishu.requireMention false --json
    ```

    其中完整的配置示例如下：

    ```JSON
    {"channels": {"feishu": {"enabled": true,"appId": "你的AppID","appSecret": "你的AppSecret","requireMention": false,"groupPolicy": "open"}}}
    ```

• 模式3：只有指定群@机器人才回复，适合不同群不同规则。

  1. 获取群 ID。

     • 在飞书群设置页面中获取群 ID。

     • 在飞书群让机器人回复群 ID。

  2. 配置指定群回复消息规则，配置完成后重启服务。

  Bash

  1
  2
  3
  4# 1. 设置默认所有群都不需要 @
  openclaw config set channels.feishu.requireMention false --json
  # 2. 给特定群设置需要 @（这里群ID只是示例，需要替换成真实的群ID）
  openclaw config set channels.feishu.groups.oc_xxxxxxxx.requireMention true --json
  

关于 Ark Helper 的使用#

如何升级 Ark Helper？#

重新执行以下命令就可以升级到 Ark Helper 最新版本。

1curl -fsSL https://lf3-static.bytednsdoc.com/obj/eden-cn/ylwslo-yrh/ljhwZthlaukjlkulzlp/install.sh | sh

如何卸载 Ark Helper？#

执行以下命令可以卸载 Ark Helper。

1npm uninstall -g @byted-aml/ark-helper

关于方舟 Coding Plan 的使用#

套餐的用量额度限制是多少？#

方舟 Coding Plan 提供 2 种订阅套餐，满足不同开发场景的需求。
资源消耗因请求上下文长度和模型差异巨大，实际可用次数会因此有较大波动。基于 Doubao Seed 2.0 Lite 模型 在 Claude Code 未开启 Agent Team 模式下，套餐的预估用量可参考下表。

注意：实际用量会因开发任务复杂度、代码库大小及 Coding 工具的使用方式等因素有所不同。

如何查看 Coding Plan 套餐的用量？#

您可以在控制台的 Coding Plan 管理页面 上查看套餐的用量统计数据和剩余额度。

套餐额度耗尽后是否会继续消耗其他资源包或账户余额？#

不会，套餐额度在时间周期内耗尽后，您需要等待下一个周期自动恢复额度，不会消耗其他资源包或账户余额。

• 每 5 小时限额：根据首次请求发生时间，以 5 小时为周期定时刷新限额。
• 周限额：每周一 00:00:00 刷新。
• 月限额：每订阅月第1日 00:00:00 刷新。

购买 Coding Plan 后，是否需要到火山方舟控制台单独开通模型，并创建推理接入点？#

不需要，Coding Plan 购买即开通，您成功订阅套餐后，相应的能力即已开通，无需任何额外的模型开通、Endpoint创建等复杂配置。关于如何在您熟悉的编程工具（如Claude Code、Cursor等）开始使用，请参阅 接入AI编程工具。

支持使用哪些模型？#

支持使用的模型以控制台实际展示为准，完整列表参见：支持的模型。

Coding Plan 支持哪些编程工具？#

Coding Plan支持多款主流编程工具，如Claude Code、Cursor、Cline（VSCode）、Kilo Code、Roo Code、OpenCode、TraeCode 等编程工具。

Coding Plan 套餐如何接入编程工具？#

需要使用 Coding Plan 专用 API Base URL 接入，接入步骤可参考接入AI编程工具。

• 配置 Base URL（如Claude Code）：https://ark.cn-beijing.volces.com/api/coding
• 兼容OpenAI API工具Base URL（如Cline、Cursor、OpenCode）：https://ark.cn-beijing.volces.com/api/coding/v3

注意：套餐额度仅在支持的 Coding 工具中生效，不能用于 API 调用，API 调用需要按照方舟现有计费规则进行收费。

我可以同时在多个工具中使用我的套餐吗？#

可以，您可以在所有支持的工具中使用同一套餐，但额度是共享的，所有工具的使用会消耗同一套餐额度。

套餐是否支持团队使用？#

目前方舟 Coding Plan 主要面向个人开发者。团队协作使用，请使用方舟模型 API 按量付费方式接入。

套餐是否仅可用于AI工具中的调用？#

是的，在非 AI 工具中使用方舟 Coding Plan / Agent Plan 权益对应的 Base URL 和 API Key 有可能被识别为滥用/违规，会导致订阅停用或账号封禁。

关于方舟 Coding Plan 的订阅#

如何升级我的套餐？#

您可以通过访问 方舟 Coding Plan 活动 或 方舟控制台-开通管理 进行套餐升级操作。升级后立即生效。

订阅套餐后可以退款吗？#

• 支持非七天无理由退订：会退订已购买的订单，退订说明及退款计算公式可详见 非七天无理由退订说明。
• 支持退订未生效续费订单：退订通过点击续费购买且未生效的订单，不会退订当前生效中的订单。例如，首次购买的订单包含5个月时长，但不是续费订单，所以无法通过退订未生效续费订单的方式退订。

操作步骤如下：

1. 进入火山引擎 费用中心-退订管理。

2. 支持非七天无理由退订、退订未生效续费订单，具体如下：

   • 非七天无理由退订：在退订资源页签，单击非七天无理由退订，在产品列过滤字节跳动大模型服务（豆包大模型），在配置列找到要退订的 Coding Plan 套餐，在对应操作列单击退订，根据界面提示完成套餐退订。

   

   • 退订未生效续费订单：在退订未生效续费周期页签，找到商品名称为字节跳动大模型服务（豆包大模型） 的待生效的续费订单，在操作列单击退订，根据界面提示完成退订。

   

如何续费我的套餐？#

强烈建议您在订阅时开启自动续费，避免后续影响使用。若您在订阅时，没有开启自动续费，可跳转至 方舟控制台-开通管理，点击套餐对应的续费按钮，进行续费操作。

如何取消自动续费？#

您可以在 方舟控制台-开通管理 取消自动续费。请务必在下一个扣费日至少 7 天前取消，避免自动续费。取消自动续费后，当前周期继续有效，但到期后会不再续费。

关于新用户特惠活动#

一个用户只能享受一次 Coding Plan套餐优惠？#

是的，一个用户仅能享受一次优惠价格，再次购买及续订都无法享受该优惠。

订阅Coding Plan套餐，享受优惠有什么限制？#

一个认证主体只能享受一次套餐优惠。如果该认证主体下有多个账号，则只有首次购买的账号能享受该优惠。

我购买时为什么没有优惠？#

如果您没有享受首购优惠，需要您确认：当前账号的认证主体是否有其他账号已经购买过Coding Plan套餐。

关于限时邀请活动#

如何成功建立邀请关系？#

当您的好友（被邀请人）首次点击您的专属邀请链接或通过您的邀请码完成登录/注册时，邀请关系即永久绑定。此关系以系统首次记录为准。

一个用户可以同时是“邀请人”和“被邀请人”吗？#

一旦您创建邀请码，即成为“邀请人”，将无法再作为“被邀请人”享受首单折扣，但“被邀请人”可以作为新的“邀请人”邀请其他人。

代金券可以用于支付“自动续费”的账单吗？#

可以，只要代金券在有效期内，系统在自动续费扣款时，可以使用代金券进行抵扣。

我如何查看我成功邀请的好友与获得的代金券？#

您可以在 我的邀请 页面，查看当前邀请成功的好友与代金券，此外，您还可以在 费用中心-代金券 查看代金券。

邀请奖励的代金券可以怎么用？有效期多久？#

为鼓励开发者探索 AI 的无限可能，您的邀请奖励代金券除了能用于订阅 Coding Plan 外，还能用于抵扣豆包大模型商品的后付费 API 调用费用，具体适用模型以代金券使用规则为准。自发放之日起有效期为 90天，逾期自动作废。

为什么我邀请好友下单后，奖励的代金券金额低于订单金额的10%？#

因为您的奖励是基于好友的 “实际支付金额” 计算的，而非订单原价。实际支付金额”指好友支付的真实现金部分。举例，您邀请好友订阅方舟 Coding Plan，好友订阅了Lite月套餐，好友实际支付了9.9元 × 90% = 8.9元，您将获得 8.9元 × 10% = 0.89元 面值的代金券。