# 常见问题 > 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。 ## 关于接入 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`，在``模型配置中新增`options`配置，内容为` {"thinking": {"type": "enabled"}}`。参考示例如下： ```JSON { "$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": "" }, "models": { "": { "name": "", "options": { "thinking": { "type": "enabled" } } } } } } } ``` 2. 配置完成后执行命令`opencode`重新启动。如果在对话时仍看不到`Thinking`信息，可以在输入框按`ctrl+p`，搜索`think`，选中`Show thinking`，则可以查看思考的信息。 ![](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/beb557544bfe466bbc41b242c8ecf7cb~tplv-goo7wpa0wc-image.image) ### OpenClaw 如何开启深度思考模式？ OpenClaw 支持以下几种方式开启深度思考模式： > **说明** > > OpenClaw 支持设置的深度思考 level：off、minimal、low、medium、high、xhigh。具体参见 [Thinking Levels](https://docs.openclaw.ai/tools/thinking#thinking-levels)。 1. 在当前消息临时开启深度思考模式 在消息前面添加内联指令：`/think:` 或`/t `，示例如下： ```Bash /think:high 你的问题 # 或者使用简写模式 /t high 你的问题 ``` 2. 在会话级别开启深度思考模式 单独发送一条指令消息：`/think:` 或`/t `，示例如下： ```Bash /think:high # 或者使用简写模式 /t high ``` 3. 全局配置开启深度思考模式 使用 config 命令修改全局配置：`openclaw config set agents.defaults.thinkingDefault `，示例如下： ```Bash openclaw config set agents.defaults.thinkingDefault high # 重启 gateway 才能生效 openclaw gateway restart # 查看配置是否生效 openclaw config get agents.defaults.thinkingDefault ``` ### 使用 OpenClaw 时，出现不支持 developer role 的报错，如何解决？ **问题描述** 在 OpenClaw Chat 中发送消息后没有响应，错误信息如下： ```SQL HTTP 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 }`，示例如下： > **说明** > > **compat** 配置必须放在 model 级别，不能放在 provider 级别，否则会报 `Unrecognized key: "compat"`错误。 ```JSON { "models": { "providers": { "volcengine-plan": { "baseUrl": "https://ark.cn-beijing.volces.com/api/coding/v3", "apiKey": "", "api": "openai-completions", "models": [ { "id": "", "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/" } } } } ``` 2. 配置修改完成后，执行以下命令重启 gateway。 ```Bash pkill -f openclaw openclaw gateway restart ``` ### 在 OpenClaw 中无法识别图片，如何处理？ 1. 确认模型支持图片输入。 检查配置文件 `~/.openclaw/openclaw.json` 中的模型`input`字段是否包含 `image` 输入类型。以模型 doubao-seed-2.1-lite 为例，配置信息如下： ```JSON "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` 中包含正确的模型别名。 ```JSON "agents": { "defaults": { "imageModel": { "primary": "volcengine-plan/doubao-seed-2.1-lite" }, "models": { "volcengine-plan/doubao-seed-2.1-lite": { "alias": "volcengine" } }, ... } } ``` 3. 重启 Gateway 使配置生效，然后即可在 OpenClaw 中识别图片。 ```Bash openclaw gateway restart ``` ### 安装 OpenClaw 时报错 “gateway connect failed: Error: pairing required”，如何处理？ 执行以下命令删除设备和身份，然后重新安装网关并重启解决该问题。 ```Bash rm -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 openclaw gateway restart ``` ## 关于飞书插件的使用 ### 如何升级飞书插件版本？ 1. 执行`openclaw -v`命令查看已安装的 OpenClaw 的版本，新版插件对 OpenClaw 的版本要求如下。若低于该版本，插件运行可能出现异常，可执行 `npm install -g openclaw` 命令升级。 * **Linux**/**macOS：2026.2.26** 及以上 * **Windows：2026.3.2** 及以上 2. 执行以下命令升级飞书官方插件到最新版本。 ```Bash npx -y @larksuite/openclaw-lark-tools update ``` 若执行该命令行出错，可在命令行前 增加 `sudo` 重新执行。 ### 在使用飞书插件时遇到问题，如何操作？ 1. 通过在飞书机器人对话框中输入以下内容排查问题并解决。 1. `/feishu start`：确认是否安装成功。 2. `/feishu doctor`：检查配置是否正常。 3. `/feishu auth`：批量完成用户授权。 4. 插件中内置了常见问题的解决方案，可在对话框中直接输入问题获取解答。 2. 在终端执行以下命令进行修复。 ```Bash # 查看问题，自主修复 npx @larksuite/openclaw-lark-tools doctor # 自动修复 npx @larksuite/openclaw-lark-tools doctor --fix ``` 3. 在终端执行以下命令获取信息，在飞书群里反馈解答。 ```Bash # 执行以下命令，查看版本信息，辅助排查 npx @larksuite/openclaw-lark-tools info # 执行以下命令，查看详细配置信息 npx @larksuite/openclaw-lark-tools info --all ``` ### 如何配置飞书机器人，使其具备流式输出、耗时显示及状态展示能力？ 1. 执行以下命令对飞书机器人进行配置。 * 开启流式输出 ```Bash openclaw config set channels.feishu.streaming true ``` * 关闭流式输出 ```Bash openclaw config set channels.feishu.streaming false ``` * 开启耗时 ```Bash openclaw config set channels.feishu.footer.elapsed true ``` * 开启状态展示 ```Bash openclaw config set channels.feishu.footer.status true ``` 2. 配置完成后，需要执行以下命令重启服务。 ```Bash openclaw gateway stop openclaw gateway run ``` ### 如何修改飞书机器人在群内的回复方式？ 目前插件在群内默认的方式为：只有@机器人才会回复。 * 模式1：只有@机器人才回复。 在终端执行以下命令配置飞书机器人，配置完成后重启服务。 ```Bash # 设置需要 @ 才回复 openclaw config set channels.feishu.requireMention true --json ``` 完整的配置示例如下： ```JSON {"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. 设置默认所有群都不需要 @ 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 最新版本。 ```Bash curl -fsSL https://lf3-static.bytednsdoc.com/obj/eden-cn/ylwslo-yrh/ljhwZthlaukjlkulzlp/install.sh | sh ``` ### 如何卸载 Ark Helper？ 执行以下命令可以卸载 Ark Helper。 ```Bash npm uninstall -g @byted-aml/ark-helper ``` ## 关于方舟 Coding Plan 的使用 ### 套餐的用量额度限制是多少？ > **注意** > > 方舟已推出 Agent Plan 套餐，新增支持全模态模型及专属 Harness，采用精细化 AFP 抵扣规则，用量清晰可查。如需使用，请前往 [方舟 Agent Plan 活动](https://ai.volcengine.com/activity/agentplan?_vtm_=a441938.b656048.0_0.0_0.0.2709_7612576610202109478) 订阅套餐。 方舟 Coding Plan 提供 2 种订阅套餐，满足不同开发场景的需求。 资源消耗因请求上下文长度和模型差异巨大，实际可用次数会因此有较大波动。**基于 Doubao Seed 2.0 Lite 模型 在 Claude Code 未开启 Agent Team 模式下**，**套餐的预估用量可参考下表**。 |套餐 |适用场景 |用量限制 | |---|---|---| |Lite 套餐 |中等强度的开发任务，适合大多数开发者。 |* 每 5 小时：最多约 1,200 次请求。 | \ | | |* 每周：最多约 9,000 次请求。 | \ | | |* 每订阅月：最多约 18,000 次请求。 | |Pro 套餐 |复杂项目开发，适合高强度工作的开发者。 |> Lite 套餐的 5 倍用量。 | \ | | | | \ | | |* 每 5 小时：最多约 6,000 次请求。 | \ | | |* 每周：最多约 45,000 次请求。 | \ | | |* 每订阅月：最多约 90,000 次请求。 | 注意：实际用量会因开发任务复杂度、代码库大小及 Coding 工具的使用方式等因素有所不同。 ### 如何查看 Coding Plan 套餐的用量？ 您可以在控制台的 [Coding Plan 管理页面](https://ark.volcengine.com/region:cn-beijing/openManagement?&advancedActiveKey=subscribe) 上查看套餐的用量统计数据和剩余额度。 ![](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/a9dbd626ff7543698ddfd20a33a73b1f~tplv-goo7wpa0wc-image.image) ### 套餐额度耗尽后是否会继续消耗其他资源包或账户余额？ 不会，套餐额度在时间周期内耗尽后，您需要等待下一个周期自动恢复额度，不会消耗其他资源包或账户余额。 * 每 5 小时限额：根据首次请求发生时间，以 5 小时为周期定时刷新限额。 * 周限额：每周一 00:00:00 刷新。 * 月限额：每订阅月第1日 00:00:00 刷新。 ### 购买 Coding Plan 后，是否需要到火山方舟控制台单独开通模型，并创建推理接入点？ 不需要，Coding Plan 购买即开通，您成功订阅套餐后，相应的能力即已开通，无需任何额外的模型开通、Endpoint创建等复杂配置。关于如何在您熟悉的编程工具（如Claude Code、Cursor等）开始使用，请参阅 [接入AI编程工具](/docs/coding-plan-personal-ai-claude-code)。 ### 支持使用哪些模型？ 支持使用的模型以控制台实际展示为准，完整列表参见：[支持的模型](/docs/coding-plan-personal-plan-overview#51b87c17)。 ### 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 活动](https://www.volcengine.com/activity/codingplan) 或 [方舟控制台-开通管理](https://ark.volcengine.com/region:cn-beijing/openManagement?LLM=%7B%7D&advancedActiveKey=subscribe) 进行套餐升级操作。升级后立即生效。 ### 订阅套餐后可以退款吗？ * 支持**非七天无理由退订**：会退订已购买的订单，退订说明及退款计算公式可详见 [非七天无理由退订说明](https://docs.volcengine.com/docs/6269/81013?lang=zh#.5pSv5oyB6Z2e5LiD5aSp5peg55CG55Sx6YCA5qy-5Lqn5ZOB)。 * 支持**退订未生效续费订单**：退订通过点击续费购买且未生效的订单，不会退订当前生效中的订单。例如，首次购买的订单包含5个月时长，但不是续费订单，所以无法通过退订未生效续费订单的方式退订。 **操作步骤**如下： 1. 进入火山引擎 [费用中心-退订管理](https://console.volcengine.com/finance/unsubscribe)。 2. 支持非七天无理由退订、退订未生效续费订单，具体如下： * **非七天无理由退订**：在**退订资源**页签，单击**非七天无理由退订**，在**产品**列过滤**字节跳动大模型服务（豆包大模型）**，在配置列找到要退订的 Coding Plan 套餐，在对应操作列单击**退订**，根据界面提示完成套餐退订。 ![image-20260923-154049-861.png](https://arkdocs.tos-cn-beijing.volces.com/images/CodingPlan/image-20260923-154049-861.png) * **退订未生效续费订单**：在**退订未生效续费周期**页签，找到商品名称为**字节跳动大模型服务（豆包大模型）** 的待生效的续费订单，在操作列单击**退订**，根据界面提示完成退订。 ![image-20260923-154307-087.png](https://arkdocs.tos-cn-beijing.volces.com/images/CodingPlan/image-20260923-154307-087.png) ### 如何续费我的套餐？ 强烈建议您在订阅时开启自动续费，避免后续影响使用。若您在订阅时，没有开启自动续费，可跳转至 [方舟控制台-开通管理](https://ark.volcengine.com/region:cn-beijing/openManagement?LLM=%7B%7D&advancedActiveKey=subscribe)，点击套餐对应的**续费**按钮，进行续费操作。 ### 如何取消自动续费？ 您可以在 [方舟控制台-开通管理](https://ark.volcengine.com/region:cn-beijing/openManagement?LLM=%7B%7D&advancedActiveKey=subscribe) 取消自动续费。请务必在下一个扣费日至少 7 天前取消，避免自动续费。取消自动续费后，当前周期继续有效，但到期后会不再续费。 ## 关于新用户特惠活动 ### 一个用户只能享受一次 Coding Plan套餐优惠？ 是的，一个用户仅能享受一次优惠价格，再次购买及续订都无法享受该优惠。 ### 订阅Coding Plan套餐，享受优惠有什么限制？ 一个认证主体只能享受一次套餐优惠。如果该认证主体下有多个账号，则只有首次购买的账号能享受该优惠。 ### 我购买时为什么没有优惠？ 如果您没有享受首购优惠，需要您确认：当前账号的认证主体是否有其他账号已经购买过Coding Plan套餐。 ## 关于限时邀请活动 ### 如何成功建立邀请关系？ 当您的好友（被邀请人）首次点击您的专属邀请链接或通过您的邀请码完成登录/注册时，邀请关系即永久绑定。此关系以系统首次记录为准。 ### 一个用户可以同时是“邀请人”和“被邀请人”吗？ 一旦您创建邀请码，即成为“邀请人”，将无法再作为“被邀请人”享受首单折扣，但“被邀请人”可以作为新的“邀请人”邀请其他人。 ### 代金券可以用于支付“自动续费”的账单吗？ 可以，只要代金券在有效期内，系统在自动续费扣款时，可以使用代金券进行抵扣。 ### 我如何查看我成功邀请的好友与获得的代金券？ 您可以在 [我的邀请](https://www.volcengine.com/activity/invitations) 页面，查看当前邀请成功的好友与代金券，此外，您还可以在 [费用中心-代金券](https://console.volcengine.com/finance/coupon) 查看代金券。 ### 邀请奖励的代金券可以怎么用？有效期多久？ 为鼓励开发者探索 AI 的无限可能，您的邀请奖励代金券除了能用于订阅 Coding Plan 外，还能用于抵扣豆包大模型商品的后付费 API 调用费用，具体适用模型以代金券使用规则为准。自发放之日起有效期为 90天，逾期自动作废。 ### 为什么我邀请好友下单后，奖励的代金券金额低于订单金额的10%？ 因为您的奖励是基于好友的 “实际支付金额” 计算的，而非订单原价。实际支付金额”指好友支付的真实现金部分。举例，您邀请好友订阅方舟 Coding Plan，好友订阅了Lite月套餐，好友实际支付了9.9元 × 90% = 8.9元，您将获得 8.9元 × 10% = 0.89元 面值的代金券。