DevEco Code

DevEco Code 是一款面向 HarmonyOS 开发场景的 AI Agent 工具。它提供终端界面（TUI），支持代码编写、编译构建、设备运行、运行时调试及 ArkTS 问题修复等能力。

让我们开始吧。

前提条件

要在终端中使用 DevEco Code，你需要：

1. Node.js 22 及以上版本。

2. 一款现代终端：

   • Windows：PowerShell 7+（推荐）、Windows PowerShell 5.1+
   • macOS：Zsh（推荐）、Bash

3. （可选）安装 DevEco Studio 6.1 及以上版本，并配置 DEVECO_HOME 环境变量。若不安装，HarmonyOS 应用构建、推包等工具将无法使用。

安装

安装 DevEco Code：

bashnpm install -g @deveco/deveco-code

登录

使用 DevEco Code 需先通过华为账号登录。首次执行 deveco 时会在终端内引导完成登录；也可单独执行登录命令：

bashdeveco auth login

登录后可使用 DevEco Code 提供的免费模型通道。当前免费提供 GLM-5.1 模型，单账号默认每分钟 50 次请求。

你也可以配置其他第三方模型提供商。了解更多。

初始化

登录后，导航到你想要处理的项目目录。

bashcd /path/to/project

然后运行 DevEco Code。

bashdeveco

接下来，运行以下命令为项目初始化 DevEco Code。

bash/init

DevEco Code 会分析你的项目并在项目根目录创建一个 AGENTS.md 文件。

这有助于 DevEco Code 理解项目结构和编码规范。

使用

现在你已经准备好使用 DevEco Code 来处理项目了，尽管提问吧！

如果你是第一次使用 AI 编码代理，以下示例可能会对你有所帮助。

提问

你可以让 DevEco Code 为你讲解代码库。

txtHow is authentication handled in @packages/functions/src/api/index.ts

当你遇到不熟悉的代码时，这个功能非常有用。

添加功能

你可以让 DevEco Code 为项目添加新功能。不过我们建议先让它制定一个计划。

1. 制定计划

DevEco Code 有一个计划模式（按 Tab 键切换），该模式下它不会进行任何修改，而是建议如何实现该功能。

使用 Tab 键切换到计划模式。你会在右下角看到模式指示器。

bash<TAB>

接下来描述你希望它做什么。

txtWhen a user deletes a note, we'd like to flag it as deleted in the database.
Then create a screen that shows all the recently deleted notes.
From this screen, the user can undelete a note or permanently delete it.

你需要提供足够的细节，让 DevEco Code 理解你的需求。可以把它当作团队中的一名初级开发者来沟通。

1. 迭代计划

当它给出计划后，你可以提供反馈或补充更多细节。

txtWe'd like to design this new screen using a design I've used before.
[Image #1] Take a look at this image and use it as a reference.

DevEco Code 可以扫描你提供的图片并将其添加到提示词中。只需将图片拖放到终端窗口即可。

1. 构建功能

当你对计划满意后，再次按 Tab 键切换回构建模式。

bash<TAB>

然后让它开始实施。

bashSounds good! Go ahead and make the changes.

直接修改

对于比较简单的修改，你可以直接让 DevEco Code 实施，无需先审查计划。

txtWe need to add authentication to the /settings route. Take a look at how this is
handled in the /notes route in @packages/functions/src/notes.ts and implement
the same logic in @packages/functions/src/settings.ts

请确保提供足够的细节，以便 DevEco Code 做出正确的修改。

撤销修改

假设你让 DevEco Code 做了一些修改。

txtCan you refactor the function in @packages/functions/src/api/index.ts?

但你发现结果不是你想要的。你可以使用 /undo 命令来撤销修改。

bash/undo

DevEco Code 会还原所做的修改，并重新显示你之前的消息。

txtCan you refactor the function in @packages/functions/src/api/index.ts?

你可以调整提示词，让 DevEco Code 重新尝试。

你也可以使用 /redo 命令来重做修改。

bash/redo

个性化

以上就是全部内容！你现在已经是 DevEco Code 的使用高手了。

要让它更符合你的习惯，我们推荐选择一个主题、自定义快捷键、创建自定义命令，或者探索 DevEco Code 配置。

DevEco Code CLI 在不带任何参数运行时，默认启动 TUI。

bashdeveco

但它也接受本页面中记录的命令，使您可以通过编程方式与 DevEco Code 进行交互。

bashdeveco run "Explain how closures work in JavaScript"

tui

启动 DevEco Code 终端用户界面。

bashdeveco [project]

标志

命令

DevEco Code CLI 还提供以下命令。

agent

管理 DevEco Code 的代理。

bashdeveco agent [command]

attach

将终端连接到已通过 serve 命令启动的 DevEco Code 后端服务器。

bashdeveco attach [url]

这允许将 TUI 与远程 DevEco Code 后端配合使用。例如：

bash# Start the backend server
deveco serve --port 4096 --hostname 0.0.0.0

# In another terminal, attach the TUI to the running backend
deveco attach http://10.20.30.40:4096

标志

create

使用自定义配置创建新的代理。

bashdeveco agent create

此命令将引导您使用自定义系统提示词和工具配置来创建新的代理。

list

列出所有可用的代理。

bashdeveco agent list

auth

管理提供商的凭据和登录信息的命令。

bashdeveco auth [command]

login

使用 DevEco Code 需先通过华为账号登录。执行 deveco auth login 会在终端内引导完成登录。

bashdeveco auth login

登录后可使用 DevEco Code 提供的免费模型通道，也可以配置第三方模型提供商。

list

列出凭据文件中存储的所有已认证提供商。

bashdeveco auth list

或使用简写版本。

bashdeveco auth ls

logout

从凭据文件中清除提供商信息以完成登出。

bashdeveco auth logout

github

管理用于仓库自动化的 GitHub 代理。

bashdeveco github [command]

install

在您的仓库中安装 GitHub 代理。

bashdeveco github install

此命令会设置必要的 GitHub Actions 工作流并引导您完成配置过程。

run

运行 GitHub 代理。通常在 GitHub Actions 中使用。

bashdeveco github run

标志

mcp

管理 Model Context Protocol 服务器。

bashdeveco mcp [command]

add

将 MCP 服务器添加到您的配置中。

bashdeveco mcp add

此命令将引导您添加本地或远程 MCP 服务器。

list

列出所有已配置的 MCP 服务器及其连接状态。

bashdeveco mcp list

或使用简写版本。

bashdeveco mcp ls

auth

对支持 OAuth 的 MCP 服务器进行认证。

bashdeveco mcp auth [name]

如果您不提供服务器名称，系统将提示您从可用的支持 OAuth 的服务器中进行选择。

您还可以列出支持 OAuth 的服务器及其认证状态。

bashdeveco mcp auth list

或使用简写版本。

bashdeveco mcp auth ls

logout

移除 MCP 服务器的 OAuth 凭据。

bashdeveco mcp logout [name]

debug

调试 MCP 服务器的 OAuth 连接问题。

bashdeveco mcp debug <name>

models

列出已配置提供商的所有可用模型。

bashdeveco models [provider]

此命令以 provider/model 的格式显示所有已配置提供商中可用的模型。

这对于确定在配置文件中使用的确切模型名称非常有用。

您可以选择传入提供商 ID 来按提供商筛选模型。

bashdeveco models anthropic

标志

使用 --refresh 标志可以更新缓存的模型列表。当提供商新增了模型并且您希望在 DevEco Code 中看到它们时，此功能非常有用。

bashdeveco models --refresh

run

以非交互模式运行 DevEco Code，直接传入提示词。

bashdeveco run [message..]

这对于脚本编写、自动化或无需启动完整 TUI 即可快速获取答案的场景非常有用。例如：

bashdeveco run Explain the use of context in Go

您还可以连接到正在运行的 deveco serve 实例，以避免每次运行时 MCP 服务器的冷启动时间：

bash# Start a headless server in one terminal
deveco serve

# In another terminal, run commands that attach to it
deveco run --attach http://localhost:4096 "Explain async/await in JavaScript"

标志

serve

启动无界面的 DevEco Code 服务器以提供 API 访问。

bashdeveco serve

此命令启动一个 HTTP 服务器，提供对 DevEco Code 功能的 API 访问，无需 TUI 界面。设置 DEVECO_SERVER_PASSWORD 可启用 HTTP 基本认证（用户名默认为 deveco）。

标志

session

管理 DevEco Code 会话。

bashdeveco session [command]

list

列出所有 DevEco Code 会话。

bashdeveco session list

标志

stats

显示 DevEco Code 会话的 Token 用量和费用统计信息。

bashdeveco stats

标志

export

将会话数据导出为 JSON。

bashdeveco export [sessionID]

如果您不提供会话 ID，系统将提示您从可用的会话中进行选择。

import

从 JSON 文件或 DevEco Code 分享链接导入会话数据。

bashdeveco import <file>

您可以从本地文件或 DevEco Code 分享链接导入。

bashdeveco import session.json

acp

启动 ACP（Agent Client Protocol）服务器。

bashdeveco acp

此命令启动一个通过 stdin/stdout 使用 nd-JSON 进行通信的 ACP 服务器。

标志

uninstall

卸载 DevEco Code 并删除所有相关文件。

bashdeveco uninstall

标志

upgrade

将 DevEco Code 更新到最新版本或指定版本。

bashdeveco upgrade [target]

更新到最新版本。

bashdeveco upgrade

更新到指定版本。

bashdeveco upgrade v0.1.48

标志

全局标志

DevEco Code CLI 接受以下全局标志。

环境变量

DevEco Code 可以通过环境变量进行配置。

实验性功能

这些环境变量用于启用可能会更改或移除的实验性功能。

DevEco Code 提供了一个交互式终端界面（TUI），用于配合 LLM 处理您的项目。

运行 DevEco Code 即可启动当前目录的 TUI。

bashdeveco

或者您可以为指定的工作目录启动它。

bashdeveco /path/to/project

进入 TUI 后，您可以输入消息进行提示。

textGive me a quick summary of the codebase.

文件引用

您可以使用 @ 在消息中引用文件。这会在当前工作目录中进行模糊文件搜索。

textHow is auth handled in @packages/functions/src/api/index.ts?

文件的内容会自动添加到对话中。

Bash 命令

以 ! 开头的消息会作为 shell 命令执行。

bash!ls -la

命令的输出会作为工具结果添加到对话中。

命令

使用 DevEco Code TUI 时，您可以输入 / 后跟命令名称来快速执行操作。例如：

bash/help

大多数命令还支持以 ctrl+x 作为前导键的快捷键，其中 ctrl+x 是默认前导键。了解更多。

以下是所有可用的斜杠命令：

connect

将提供商添加到 DevEco Code。允许您从可用的提供商中选择并添加其 API 密钥，或通过华为账号登录。

bash/connect

compact

压缩当前会话。别名：/summarize

bash/compact

快捷键： ctrl+x c

details

切换工具执行详情的显示。

bash/details

快捷键： ctrl+x d

editor

打开外部编辑器来编写消息。使用 EDITOR 环境变量中设置的编辑器。了解更多。

bash/editor

快捷键： ctrl+x e

exit

退出 DevEco Code。别名：/quit、/q

bash/exit

快捷键： ctrl+x q

export

将当前对话导出为 Markdown 并在默认编辑器中打开。使用 EDITOR 环境变量中设置的编辑器。了解更多。

bash/export

快捷键： ctrl+x x

help

显示帮助对话框。

bash/help

快捷键： ctrl+x h

init

创建或更新 AGENTS.md 文件。了解更多。

bash/init

快捷键： ctrl+x i

models

列出可用模型。

bash/models

快捷键： ctrl+x m

new

开始新的会话。别名：/clear

bash/new

快捷键： ctrl+x n

redo

重做之前撤销的消息。仅在使用 /undo 后可用。

在内部，这使用 Git 来管理文件更改。因此您的项目需要是一个 Git 仓库。

bash/redo

快捷键： ctrl+x r

sessions

列出会话并在会话之间切换。别名：/resume、/continue

bash/sessions

快捷键： ctrl+x l

themes

列出可用主题。

bash/themes

快捷键： ctrl+x t

thinking

切换对话中思考/推理块的可见性。启用后，您可以看到支持扩展思考的模型的推理过程。

bash/thinking

undo

撤销对话中的最后一条消息。移除最近的用户消息、所有后续响应以及所有文件更改。

在内部，这使用 Git 来管理文件更改。因此您的项目需要是一个 Git 仓库。

bash/undo

快捷键： ctrl+x u

编辑器设置

/editor 和 /export 命令都使用 EDITOR 环境变量中指定的编辑器。

# Example for nano or vim
export EDITOR=nano
export EDITOR=vim

# For GUI editors, VS Code, Cursor, VSCodium, Windsurf, Zed, etc.
# include --wait
export EDITOR="code --wait"

set EDITOR=notepad

# For GUI editors, VS Code, Cursor, VSCodium, Windsurf, Zed, etc.
# include --wait
set EDITOR=code --wait

$env:EDITOR = "notepad"

# For GUI editors, VS Code, Cursor, VSCodium, Windsurf, Zed, etc.
# include --wait
$env:EDITOR = "code --wait"

常用的编辑器选项包括：

• code - Visual Studio Code
• cursor - Cursor
• windsurf - Windsurf
• nvim - Neovim 编辑器
• vim - Vim 编辑器
• nano - Nano 编辑器
• notepad - Notepad（Windows 记事本）
• subl - Sublime Text

某些编辑器需要命令行参数才能以阻塞模式运行。--wait 标志使编辑器进程阻塞直到关闭。

配置

您可以通过 tui.json（或 tui.jsonc）自定义 TUI 行为。

json{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "deveco",
  "leader_timeout": 2000,
  "keybinds": {
    "leader": "ctrl+x",
    "command_list": "ctrl+p"
  },
  "scroll_speed": 3,
  "scroll_acceleration": {
    "enabled": false
  },
  "diff_style": "auto",
  "mouse": true,
  "attention": {
    "enabled": true,
    "notifications": true,
    "sound": true,
    "volume": 0.4,
    "sound_pack": "deveco.default",
    "sounds": {
      "error": "./sounds/error.mp3"
    }
  }
}

这与 deveco.json 是分开的；deveco.json 用于配置服务器和运行时行为。

keybinds 会与内置默认值合并，因此你只需要配置想要修改的快捷键。

选项

• theme - 设置 UI 主题。了解更多。
• keybinds - 自定义键盘快捷键。了解更多。
• leader_timeout - 控制按下 leader key 后 DevEco Code 等待后续按键的时间。默认为 2000。
• scroll_acceleration.enabled - 启用 macOS 风格的滚动加速，让滚动更平滑自然。启用后，快速滚动时速度会增加，慢速移动时仍保持精确。此设置优先于 scroll_speed，启用时会覆盖它。
• scroll_speed - 控制使用滚动命令时 TUI 的滚动速度（最小值：0.001，支持小数）。默认为 3。注意：如果 scroll_acceleration.enabled 设置为 true，则此设置会被忽略。
• diff_style - 控制 diff 的显示方式。"auto" 会根据终端宽度自适应，"stacked" 始终显示单列布局。
• mouse - 在 TUI 中启用或禁用鼠标捕获（默认：true）。禁用后，终端原生的鼠标选择和滚动行为会保留下来。
• attention - 配置 TUI 桌面通知和声音。默认禁用。

使用 DEVECO_TUI_CONFIG 可以加载自定义的 TUI 配置文件路径。

Attention

当 DevEco Code 需要你处理问题、批准权限请求、查看会话错误，或想告知会话已完成时，TUI 可以通过声音和桌面通知提醒你。设置 attention.enabled 后会启用这些提醒；内置事件触发时会播放声音。桌面通知只会在终端窗口未聚焦时发送，并且不会用于 subagent 事件。

• enabled - 开启 Attention 的所有通知和声音。默认为 false。
• notifications - 启用 Attention 后，允许 TUI 通过终端发送桌面通知。默认为 true。
• sound - 启用 Attention 后，允许播放提示音。默认为 true。
• volume - 默认提示音音量，范围从 0 到 1。默认为 0.4。
• sound_pack - 要使用的 sound pack ID。默认为 deveco.default。
• sounds - 为 default、question、permission、error、done 或 subagent_done 指定自定义声音文件。路径可以是绝对路径、file:// URL，或相对于 tui.json 的路径。

自定义

您可以使用命令面板（ctrl+x h 或 /help）自定义 TUI 视图的各个方面。这些设置在重启后仍会保留。

用户名显示

切换您的用户名是否显示在聊天消息中。通过以下方式访问：

• 命令面板：搜索 "username" 或 "hide username"
• 该设置会自动保存，并在各个 TUI 会话中保持记忆

自定义命令允许你指定一个提示词，当在 TUI 中执行该命令时会运行这个提示词。

bash/my-command

自定义命令是 /init、/undo、/redo、/help 等内置命令之外的补充。了解更多。

创建命令文件

在 commands/ 目录中创建 markdown 文件来定义自定义命令。

创建 .deveco/commands/test.md：

md---
description: Run tests with coverage
agent: build
model: deveco/glm-5.1
---

Run the full test suite with coverage report and show any failures.
Focus on the failing tests and suggest fixes.

frontmatter 定义命令属性，内容则成为模板。

通过输入 / 后跟命令名称来使用该命令。

bash"/test"

配置

你可以通过 DevEco Code 配置或在 commands/ 目录中创建 markdown 文件来添加自定义命令。

JSON

在 DevEco Code 配置中使用 command 选项：

json{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    // This becomes the name of the command
    "test": {
      // This is the prompt that will be sent to the LLM
      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
      // This is shown as the description in the TUI
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "deveco/glm-5.1"
    }
  }
}

现在你可以在 TUI 中运行这个命令：

bash/test

Markdown

你还可以使用 markdown 文件定义命令。将它们放在：

• 全局：~/.config/deveco/commands/
• 项目级：.deveco/commands/

markdown---
description: Run tests with coverage
agent: build
model: deveco/glm-5.1
---

Run the full test suite with coverage report and show any failures.
Focus on the failing tests and suggest fixes.

markdown 文件名即为命令名。例如，test.md 允许你运行：

bash/test

提示词配置

自定义命令的提示词支持多种特殊占位符和语法。

参数

使用 $ARGUMENTS 占位符向命令传递参数。

md---
description: Create a new component
---

Create a new React component named $ARGUMENTS with TypeScript support.
Include proper typing and basic structure.

带参数运行命令：

bash/component Button

$ARGUMENTS 将被替换为 Button。

你还可以使用位置参数访问各个参数：

• $1 - 第一个参数
• $2 - 第二个参数
• $3 - 第三个参数
• 以此类推...

例如：

md---
description: Create a new file with content
---

Create a file named $1 in the directory $2
with the following content: $3

运行命令：

bash/create-file config.json src "{ \"key\": \"value\" }"

替换结果为：

• $1 替换为 config.json
• $2 替换为 src
• $3 替换为 ``

Shell 输出

使用 !command 将 bash 命令输出注入到提示词中。

例如，创建一个分析测试覆盖率的自定义命令：

md---
description: Analyze test coverage
---

Here are the current test results:
!`npm test`

Based on these results, suggest improvements to increase coverage.

或者查看最近的更改：

md---
description: Review recent changes
---

Recent git commits:
!`git log --oneline -10`

Review these changes and suggest any improvements.

命令在项目的根目录中运行，其输出会成为提示词的一部分。

文件引用

使用 @ 后跟文件名在命令中引用文件。

md---
description: Review component
---

Review the component in @src/components/Button.tsx.
Check for performance issues and suggest improvements.

文件内容会自动包含在提示词中。

选项

让我们详细了解各配置选项。

Template

template 选项定义执行命令时发送给 LLM 的提示词。

json{
  "command": {
    "test": {
      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes."
    }
  }
}

这是一个必需的配置选项。

Description

使用 description 选项提供命令功能的简要描述。

json{
  "command": {
    "test": {
      "description": "Run tests with coverage"
    }
  }
}

当你输入命令时，这将在 TUI 中显示为描述。

Agent

使用 agent 配置可选地指定由哪个代理执行此命令。
如果这是一个子代理，该命令默认会触发子代理调用。
要禁用此行为，请将 subtask 设置为 false。

json{
  "command": {
    "review": {
      "agent": "plan"
    }
  }
}

这是一个可选的配置选项。如果未指定，默认使用你当前的代理。

Subtask

使用 subtask 布尔值强制命令触发子代理调用。
如果你希望命令不污染主要上下文，这会很有用，它会强制代理作为子代理运行，
即使代理配置中的 mode 设置为 primary。

json{
  "command": {
    "analyze": {
      "subtask": true
    }
  }
}

这是一个可选的配置选项。

Model

使用 model 配置覆盖此命令的默认模型。

json{
  "command": {
    "analyze": {
      "model": "deveco/glm-5.1"
    }
  }
}

这是一个可选的配置选项。

内置命令

deveco 包含多个内置命令，如 /init、/undo、/redo、/help；了解更多。

如果你定义了同名的自定义命令，它将覆盖内置命令。

您可以使用 JSON 配置文件来配置 DevEco Code。

格式

DevEco Code 支持 JSON 和 JSONC（带注释的 JSON）格式。

jsonc{
  "$schema": "https://opencode.ai/config.json",
  "model": "deveco/glm-5.1",
  "autoupdate": true,
  "server": {
    "port": 4096,
  },
}

位置

您可以将配置放置在不同的位置，它们具有不同的优先级顺序。

配置文件是合并在一起的，而不是被替换。来自以下配置位置的设置会被合并。后面的配置仅在键冲突时覆盖前面的配置。所有配置中的非冲突设置都会被保留。

例如，如果您的全局配置设置了 autoupdate: true，而您的项目配置设置了 model: "deveco/glm-5.1"，则最终配置将包含这两个设置。

优先级顺序

配置源按以下顺序加载（后面的源覆盖前面的源）：

1. 远程配置（来自 .well-known/deveco）- 组织默认值
2. 全局配置（~/.config/deveco/deveco.json）- 用户偏好
3. 自定义配置（DEVECO_CONFIG 环境变量）- 自定义覆盖
4. 项目配置（项目中的 deveco.json）- 项目特定设置
5. .deveco 目录 - 代理、命令、插件
6. 内联配置（DEVECO_CONFIG_CONTENT 环境变量）- 运行时覆盖

这意味着项目配置可以覆盖全局默认值，全局配置可以覆盖远程组织默认值。

远程

组织可以通过 .well-known/deveco 端点提供默认配置。当您使用支持该功能的提供商进行身份验证时，会自动获取此配置。

远程配置最先加载，作为基础层。所有其他配置源（全局、项目）都可以覆盖这些默认值。

例如，如果您的组织提供了默认禁用的 MCP 服务器：

json{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": false
    }
  }
}

您可以在本地配置中启用特定服务器：

json{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true
    }
  }
}

全局

将全局 DevEco Code 配置放在 ~/.config/deveco/deveco.json 中。使用全局配置来设置用户级别的偏好，例如主题、提供商或快捷键。

全局配置覆盖远程组织默认值。

项目级

在项目根目录中添加 deveco.json。项目配置在标准配置文件中具有最高优先级——它会覆盖全局配置和远程配置。

当 DevEco Code 启动时，它会在当前目录中查找配置文件，或向上遍历到最近的 Git 目录。

该配置文件也可以安全地提交到 Git 中，并使用与全局配置相同的 Schema。

自定义路径

使用 DEVECO_CONFIG 环境变量指定自定义配置文件路径。

bashexport DEVECO_CONFIG=/path/to/my/custom-config.json
deveco run "Hello world"

自定义配置在优先级顺序中位于全局配置和项目配置之间加载。

自定义目录

使用 DEVECO_CONFIG_DIR 环境变量指定自定义配置目录。该目录会像标准 .deveco 目录一样被搜索代理、命令、模式和插件，并且应遵循相同的结构。

bashexport DEVECO_CONFIG_DIR=/path/to/my/config-directory
deveco run "Hello world"

自定义目录在全局配置和 .deveco 目录之后加载，因此可以覆盖它们的设置。

Schema

配置文件具有在 opencode.ai/config.json 中定义的 Schema。

您的编辑器应该能够基于该 Schema 进行验证和自动补全。

TUI

您可以通过 tui 选项配置 TUI 相关设置。

json{
  "$schema": "https://opencode.ai/config.json",
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": {
      "enabled": true
    },
    "diff_style": "auto"
  }
}

可用选项：

• scroll_acceleration.enabled - 启用 macOS 风格的滚动加速。优先于 scroll_speed。
• scroll_speed - 自定义滚动速度倍率（默认值：3，最小值：1）。如果 scroll_acceleration.enabled 为 true，则忽略此选项。
• diff_style - 控制差异渲染方式。"auto" 根据终端宽度自适应，"stacked" 始终显示单列。

在此了解更多关于 TUI 的信息。

服务器

您可以通过 server 选项为 deveco serve 命令配置服务器设置。

json{
  "$schema": "https://opencode.ai/config.json",
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true,
    "mdnsDomain": "myproject.local",
    "cors": ["http://localhost:5173"]
  }
}

可用选项：

• port - 监听端口。
• hostname - 监听主机名。当 mdns 启用且未设置主机名时，默认为 0.0.0.0。
• mdns - 启用 mDNS 服务发现。这允许网络上的其他设备发现您的 DevEco Code 服务器。
• mdnsDomain - mDNS 服务的自定义域名。默认为 deveco.local。适用于在同一网络上运行多个实例的场景。
• cors - 从基于浏览器的客户端使用 HTTP 服务器时允许 CORS 的额外来源。值必须是完整的来源（协议 + 主机 + 可选端口），例如 https://app.example.com。

工具

您可以通过 tools 选项管理 LLM 可以使用的工具。

json{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": false,
    "bash": false
  }
}

在此了解更多关于工具的信息。

模型

您可以通过 provider、model 和 small_model 选项在 DevEco Code 配置中设置要使用的提供商和模型。

json{
  "$schema": "https://opencode.ai/config.json",
  "provider": {},
  "model": "deveco/glm-5.1",
  "small_model": "deveco/glm-5.1"
}

small_model 选项为标题生成等轻量级任务配置单独的模型。默认情况下，如果您的提供商有更便宜的模型可用，DevEco Code 会尝试使用该模型，否则会回退到您的主模型。

提供商选项可以包括 timeout 和 setCacheKey：

json{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,
        "setCacheKey": true
      }
    }
  }
}

• timeout - 请求超时时间，单位为毫秒（默认值：300000）。设置为 false 可禁用超时。
• setCacheKey - 确保始终为指定提供商设置缓存键。

您还可以配置本地模型。了解更多。

提供商特定选项

一些提供商支持除通用 timeout 和 apiKey 设置之外的额外配置选项。

Amazon Bedrock

Amazon Bedrock 支持 AWS 特定配置：

json{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "amazon-bedrock": {
      "options": {
        "region": "us-east-1",
        "profile": "my-aws-profile",
        "endpoint": "https://bedrock-runtime.us-east-1.vpce-xxxxx.amazonaws.com"
      }
    }
  }
}

• region - Bedrock 的 AWS 区域（默认为 AWS_REGION 环境变量或 us-east-1）
• profile - 来自 ~/.aws/credentials 的 AWS 命名配置文件（默认为 AWS_PROFILE 环境变量）
• endpoint - VPC 端点的自定义端点 URL。这是通用 baseURL 选项使用 AWS 特定术语的别名。如果两者都指定，endpoint 优先。

了解更多关于 Amazon Bedrock 配置的信息。

主题

您可以通过 DevEco Code 配置中的 theme 选项设置要使用的主题。

json{
  "$schema": "https://opencode.ai/config.json",
  "theme": ""
}

在此了解更多。

代理

您可以通过 agent 选项为特定任务配置专用代理。

jsonc{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "model": "deveco/glm-5.1",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        // Disable file modification tools for review-only agent
        "write": false,
        "edit": false,
      },
    },
  },
}

您还可以使用 ~/.config/deveco/agents/ 或 .deveco/agents/ 中的 Markdown 文件定义代理。在此了解更多。

默认代理

您可以使用 default_agent 选项设置默认代理。当未明确指定代理时，将使用该默认代理。

json{
  "$schema": "https://opencode.ai/config.json",
  "default_agent": "plan"
}

默认代理必须是主代理（不能是子代理）。可以是内置代理（如 "build" 或 "plan"），也可以是您定义的自定义代理。如果指定的代理不存在或是子代理，DevEco Code 将回退到 "build" 并发出警告。

此设置适用于所有界面：TUI 和 CLI（deveco run）。

命令

您可以通过 command 选项为重复任务配置自定义命令。

jsonc{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "deveco/glm-5.1",
    },
    "component": {
      "template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.",
      "description": "Create a new component",
    },
  },
}

您还可以使用 ~/.config/deveco/commands/ 或 .deveco/commands/ 中的 Markdown 文件定义命令。在此了解更多。

快捷键

您可以通过 keybinds 选项自定义快捷键。

json{
  "$schema": "https://opencode.ai/config.json",
  "keybinds": {}
}

在此了解更多。

自动更新

DevEco Code 启动时会自动下载新版本。您可以使用 autoupdate 选项禁用此功能。

json{
  "$schema": "https://opencode.ai/config.json",
  "autoupdate": false
}

如果您不想自动更新但希望在新版本可用时收到通知，可将 autoupdate 设置为 "notify"。
请注意，此功能仅在未通过 Homebrew 等包管理器安装时有效。

格式化程序

您可以通过 formatter 选项配置代码格式化程序。

json{
  "$schema": "https://opencode.ai/config.json",
  "formatter": {
    "prettier": {
      "disabled": true
    },
    "custom-prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "environment": {
        "NODE_ENV": "development"
      },
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
    }
  }
}

权限

默认情况下，DevEco Code 允许所有操作，无需明确批准。您可以使用 permission 选项更改此行为。

例如，要让 edit 和 bash 工具需要用户确认：

json{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

在此了解更多关于权限的信息。

压缩

您可以通过 compaction 选项控制上下文压缩行为。

json{
  "$schema": "https://opencode.ai/config.json",
  "compaction": {
    "auto": true,
    "prune": false,
    "reserved": 10000
  }
}

• auto - 当上下文已满时自动压缩会话（默认值：true）。
• prune - 删除旧的工具输出以节省 Token（默认值：false）。
• reserved - 压缩时的 Token 缓冲区。保留足够的窗口以避免压缩过程中溢出。

文件监视器

您可以通过 watcher 选项配置文件监视器的忽略模式。

json{
  "$schema": "https://opencode.ai/config.json",
  "watcher": {
    "ignore": ["node_modules/**", "dist/**", ".git/**"]
  }
}

模式遵循 glob 语法。使用此选项可以从文件监视中排除频繁变动的目录。

MCP 服务器

您可以通过 mcp 选项配置要使用的 MCP 服务器。

json{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {}
}

在此了解更多。

插件

插件通过自定义工具、钩子和集成来扩展 DevEco Code。

将插件文件放置在 .deveco/plugins/ 或 ~/.config/deveco/plugins/ 中。您还可以通过 plugin 选项从 npm 加载插件。

json{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-helicone-session", "@my-org/custom-plugin"]
}

在此了解更多。

指令

您可以通过 instructions 选项为所使用的模型配置指令。

json{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}

该选项接受指令文件路径和 glob 模式的数组。在此了解更多关于规则的信息。

禁用提供商

您可以通过 disabled_providers 选项禁用自动加载的提供商。当您希望阻止某些提供商被加载（即使其凭据可用）时，此选项非常有用。

json{
  "$schema": "https://opencode.ai/config.json",
  "disabled_providers": ["openai", "gemini"]
}

disabled_providers 选项接受提供商 ID 的数组。当某个提供商被禁用时：

• 即使设置了环境变量，也不会被加载。
• 即使通过 /connect 命令配置了 API 密钥，也不会被加载。
• 该提供商的模型不会出现在模型选择列表中。

启用提供商

您可以通过 enabled_providers 选项指定允许使用的提供商白名单。设置后，仅启用指定的提供商，所有其他提供商将被忽略。

json{
  "$schema": "https://opencode.ai/config.json",
  "enabled_providers": ["anthropic", "openai"]
}

当您希望限制 DevEco Code 仅使用特定提供商，而不是逐一禁用其他提供商时，此选项非常有用。

如果某个提供商同时出现在 enabled_providers 和 disabled_providers 中，为了向后兼容，disabled_providers 优先。

实验性功能

experimental 键包含正在积极开发中的选项。

json{
  "$schema": "https://opencode.ai/config.json",
  "experimental": {}
}

变量

您可以在配置文件中使用变量替换来引用环境变量和文件内容。

环境变量

使用 `` 来替换环境变量：

json{
  "$schema": "https://opencode.ai/config.json",
  "model": "{env:DEVECO_MODEL}",
  "provider": {
    "anthropic": {
      "models": {},
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

如果环境变量未设置，它将被替换为空字符串。

文件

使用 `` 来替换文件内容：

json{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["./custom-instructions.md"],
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

文件路径可以是：

• 相对于配置文件所在目录的路径
• 以 / 或 ~ 开头的绝对路径

这些功能适用于：

• 将 API 密钥等敏感数据保存在单独的文件中。
• 引入大型指令文件而不会使配置变得杂乱。
• 在多个配置文件之间共享通用配置片段。

DevEco Code 使用 AI SDK 和 Models.dev 支持 75+ LLM 提供商，并支持运行本地模型。

提供商

大多数热门提供商已默认预加载。如果你通过 /connect 命令添加了提供商的凭据，它们将在你启动 DevEco Code 时自动可用。

了解更多关于提供商的信息。

选择模型

配置好提供商后，你可以通过输入以下命令来选择想要使用的模型：

bash/models

设置默认模型

要将某个模型设为默认模型，可以在 DevEco Code 配置中设置 model 字段。

json{
  "$schema": "https://opencode.ai/config.json",
  "model": "deveco/glm-5.1"
}

这里完整的 ID 格式为 provider_id/model_id。例如，deveco/glm-5.1。

如果你配置了自定义提供商，provider_id 是配置中 provider 部分的键名，model_id 是 provider.models 中的键名。

配置模型

你可以通过配置文件全局配置模型的选项。

jsonc{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openai": {
      "models": {
        "gpt-5": {
          "options": {
            "reasoningEffort": "high",
            "textVerbosity": "low",
            "reasoningSummary": "auto",
            "include": ["reasoning.encrypted_content"],
          },
        },
      },
    },
    "anthropic": {
      "models": {
        "claude-sonnet-4-5-20250929": {
          "options": {
            "thinking": {
              "type": "enabled",
              "budgetTokens": 16000,
            },
          },
        },
      },
    },
  },
}

这里我们为两个内置模型配置了全局设置：通过 openai 提供商访问的 gpt-5，以及通过 anthropic 提供商访问的 claude-sonnet-4-5-20250929。
内置的提供商和模型名称可以在 Models.dev 上查阅。

你还可以为使用中的任何代理配置这些选项。代理配置会覆盖此处的全局选项。了解更多。

你也可以定义扩展内置变体的自定义变体。变体允许你为同一个模型配置不同的设置，而无需创建重复的条目：

jsonc{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "deveco": {
      "models": {
        "gpt-5": {
          "variants": {
            "high": {
              "reasoningEffort": "high",
              "textVerbosity": "low",
              "reasoningSummary": "auto",
            },
            "low": {
              "reasoningEffort": "low",
              "textVerbosity": "low",
              "reasoningSummary": "auto",
            },
          },
        },
      },
    },
  },
}

变体

许多模型支持具有不同配置的多种变体。DevEco Code 为热门提供商内置了默认变体。

内置变体

DevEco Code 为许多提供商提供了默认变体：

Anthropic：

• high - 高思考预算（默认）
• max - 最大思考预算

OpenAI：

因模型而异，但大致如下：

• none - 无推理
• minimal - 极少推理
• low - 低推理
• medium - 中等推理
• high - 高推理
• xhigh - 超高推理

Google：

• low - 较低推理/Token 预算
• high - 较高推理/Token 预算

自定义变体

你可以覆盖现有变体或添加自己的变体：

jsonc{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openai": {
      "models": {
        "gpt-5": {
          "variants": {
            "thinking": {
              "reasoningEffort": "high",
              "textVerbosity": "low",
            },
            "fast": {
              "disabled": true,
            },
          },
        },
      },
    },
  },
}

切换变体

使用快捷键 variant_cycle 可以快速在变体之间切换。了解更多。

加载模型

DevEco Code 启动时，会按以下优先顺序加载模型：

1. --model 或 -m 命令行标志。格式与配置文件中相同：provider_id/model_id。

2. DevEco Code 配置中的 model 字段。

json{
  "$schema": "https://opencode.ai/config.json",
  "model": "deveco/glm-5.1"
}

格式为 provider/model。

1. 上次使用的模型。

2. 按内部优先级排列的第一个可用模型。

DevEco Code 使用 AI SDK 和 Models.dev，支持 75+ LLM 提供商，同时也支持运行本地模型。

要添加提供商，你需要：

1. 使用 /connect 命令添加提供商的 API 密钥。
2. 在 DevEco Code 配置中设置该提供商。

凭据

使用 /connect 命令添加提供商的 API 密钥后，凭据会存储在
~/.local/share/deveco/auth.json 中。

配置

你可以通过 DevEco Code 配置中的 provider 部分来自定义提供商。

自定义 Base URL

你可以通过设置 baseURL 选项来自定义任何提供商的 Base URL。这在使用代理服务或自定义端点时非常有用。

json{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://api.anthropic.com/v1"
      }
    }
  }
}

目录

下面我们来详细了解一些提供商。如果你想将某个提供商添加到列表中，欢迎提交 PR。

302.AI

1. 前往 302.AI 控制台，创建账户并生成 API 密钥。

2. 执行 /connect 命令并搜索 302.AI。

txt/connect

1. 输入你的 302.AI API 密钥。

txt┌ API key
│
│
└ enter

1. 执行 /models 命令选择模型。

txt/models

Amazon Bedrock

要在 DevEco Code 中使用 Amazon Bedrock：

1. 前往 Amazon Bedrock 控制台中的模型目录，申请访问你想要使用的模型。

1. 使用以下方法之一配置身份验证：

环境变量（快速上手）

运行 deveco 时设置以下环境变量之一：

bash# Option 1: Using AWS access keys
AWS_ACCESS_KEY_ID=XXX AWS_SECRET_ACCESS_KEY=YYY deveco

# Option 2: Using named AWS profile
AWS_PROFILE=my-profile deveco

# Option 3: Using Bedrock bearer token
AWS_BEARER_TOKEN_BEDROCK=XXX deveco

或者将它们添加到你的 bash 配置文件中：

bashexport AWS_PROFILE=my-dev-profile
export AWS_REGION=us-east-1

配置文件（推荐）

如需项目级别或持久化的配置，请使用 deveco.json：

json{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "amazon-bedrock": {
      "options": {
        "region": "us-east-1",
        "profile": "my-aws-profile"
      }
    }
  }
}

可用选项：
- region - AWS 区域（例如 us-east-1、eu-west-1）
- profile - ~/.aws/credentials 中的 AWS 命名配置文件
- endpoint - VPC 端点的自定义端点 URL（通用 baseURL 选项的别名）

进阶：VPC 端点

如果你使用 Bedrock 的 VPC 端点：

json{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "amazon-bedrock": {
      "options": {
        "region": "us-east-1",
        "profile": "production",
        "endpoint": "https://bedrock-runtime.us-east-1.vpce-xxxxx.amazonaws.com"
      }
    }
  }
}

认证方式

• AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY：在 AWS 控制台中创建 IAM 用户并生成访问密钥
• AWS_PROFILE：使用 ~/.aws/credentials 中的命名配置文件。需要先通过 aws configure --profile my-profile 或 aws sso login 进行配置
• AWS_BEARER_TOKEN_BEDROCK：从 Amazon Bedrock 控制台生成长期 API 密钥
• AWS_WEB_IDENTITY_TOKEN_FILE / AWS_ROLE_ARN：适用于 EKS IRSA（服务账户的 IAM 角色）或其他支持 OIDC 联合的 Kubernetes 环境。使用服务账户注解时，Kubernetes 会自动注入这些环境变量。

认证优先级

Amazon Bedrock 使用以下认证优先级：

1. Bearer Token - AWS_BEARER_TOKEN_BEDROCK 环境变量或通过 /connect 命令获取的 Token
2. AWS 凭证链 - 配置文件、访问密钥、共享凭证、IAM 角色、Web Identity Token（EKS IRSA）、实例元数据

1. 执行 /models 命令选择你想要的模型。

txt/models

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "amazon-bedrock": {
      // ...
      "models": {
        "anthropic-claude-sonnet-4.5": {
          "id": "arn:aws:bedrock:us-east-1:xxx:application-inference-profile/yyy"
        }
      }
    }
  }
}

Anthropic

1. 注册完成后，执行 /connect 命令并选择 Anthropic。

txt/connect

1. 你可以选择 Claude Pro/Max 选项，浏览器会自动打开并要求你进行身份验证。

txt┌ Select auth method
│
│ Claude Pro/Max
│ Create an API Key
│ Manually enter API Key
└

1. 现在使用 /models 命令即可看到所有 Anthropic 模型。

txt/models

使用 API 密钥

如果你没有 Pro/Max 订阅，也可以选择 Create an API Key。浏览器会自动打开并要求你登录 Anthropic，然后会提供一个代码供你粘贴到终端中。

如果你已经有 API 密钥，可以选择 Manually enter API Key 并将其粘贴到终端中。

Atomic Chat

你可以通过 Atomic Chat 配置 deveco 以使用本地模型。Atomic Chat 是一款桌面应用程序，它在 OpenAI 兼容的 API 服务器后面运行本地 LLM（默认端点 http://127.0.0.1:1337/v1）。

json{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "atomic-chat": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Atomic Chat (local)",
      "options": {
        "baseURL": "http://127.0.0.1:1337/v1"
      },
      "models": {
        "<your-model-id>": {
          "name": "<your-model-name>"
        }
      }
    }
  }
}

在此示例中：

• atomic-chat 是自定义的提供商 ID。可以是任何你想要的字符串。
• npm 指定此提供商使用的包。这里使用 @ai-sdk/openai-compatible 来连接任何 OpenAI 兼容的 API。
• name 是提供商在界面中显示的名称。
• options.baseURL 是本地服务器的端点。根据你的 Atomic Chat 设置修改主机和端口。
• models 是模型 ID 到其显示名称的映射。每个 ID 必须与 GET /v1/models 返回的 id 匹配——运行 curl http://127.0.0.1:1337/v1/models 可列出 Atomic Chat 当前已加载的 ID。

Azure OpenAI

1. 前往 Azure 门户并创建 Azure OpenAI 资源。你需要：
2. 资源名称：这会成为你的 API 端点的一部分（https://RESOURCE_NAME.openai.azure.com/）

3. API 密钥：资源中的 KEY 1 或 KEY 2

4. 前往 Azure AI Foundry 并部署一个模型。

1. 执行 /connect 命令并搜索 Azure。

txt/connect

1. 输入你的 API 密钥。

txt┌ API key
│
│
└ enter

1. 将资源名称设置为环境变量：

bashAZURE_RESOURCE_NAME=XXX deveco

或者添加到你的 bash 配置文件中：

bashexport AZURE_RESOURCE_NAME=XXX

1. 执行 /models 命令选择你已部署的模型。

txt/models

Azure Cognitive Services

1. 前往 Azure 门户并创建 Azure OpenAI 资源。你需要：
2. 资源名称：这会成为你的 API 端点的一部分（https://AZURE_COGNITIVE_SERVICES_RESOURCE_NAME.cognitiveservices.azure.com/）

3. API 密钥：资源中的 KEY 1 或 KEY 2

4. 前往 Azure AI Foundry 并部署一个模型。

1. 执行 /connect 命令并搜索 Azure Cognitive Services。

txt/connect

1. 输入你的 API 密钥。

txt┌ API key
│
│
└ enter

1. 将资源名称设置为环境变量：

bashAZURE_COGNITIVE_SERVICES_RESOURCE_NAME=XXX deveco

或者添加到你的 bash 配置文件中：

bashexport AZURE_COGNITIVE_SERVICES_RESOURCE_NAME=XXX

1. 执行 /models 命令选择你已部署的模型。

txt/models

Baseten

1. 前往 Baseten，创建账户并生成 API 密钥。

2. 执行 /connect 命令并搜索 Baseten。

txt/connect

1. 输入你的 Baseten API 密钥。

txt┌ API key
│
│
└ enter

1. 执行 /models 命令选择模型。

txt/models

Cerebras

1. 前往 Cerebras 控制台，创建账户并生成 API 密钥。

2. 执行 /connect 命令并搜索 Cerebras。

txt/connect

1. 输入你的 Cerebras API 密钥。

txt┌ API key
│
│
└ enter

1. 执行 /models 命令选择模型，例如 Qwen 3 Coder 480B。

txt/models

Cloudflare AI Gateway

Cloudflare AI Gateway 允许你通过统一端点访问来自 OpenAI、Anthropic、Workers AI 等提供商的模型。通过 Unified Billing，你无需为每个提供商单独准备 API 密钥。

1. 前往 Cloudflare 仪表盘，导航到 AI > AI Gateway，创建一个新的网关。

2. 将你的 Account ID 和 Gateway ID 设置为环境变量。

bashexport CLOUDFLARE_ACCOUNT_ID=your-32-character-account-id
export CLOUDFLARE_GATEWAY_ID=your-gateway-id

1. 执行 /connect 命令并搜索 Cloudflare AI Gateway。

txt/connect

1. 输入你的 Cloudflare API Token。

txt┌ API key
│
│
└ enter

或者将其设置为环境变量。

bashexport CLOUDFLARE_API_TOKEN=your-api-token

1. 执行 /models 命令选择模型。

txt/models

你也可以通过 DevEco Code 配置添加模型。

json{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "cloudflare-ai-gateway": {
      "models": {
        "openai/gpt-4o": {},
        "anthropic/claude-sonnet-4": {}
      }
    }
  }
}

Cortecs

1. 前往 Cortecs 控制台，创建账户并生成 API 密钥。

2. 执行 /connect 命令并搜索 Cortecs。

txt/connect

1. 输入你的 Cortecs API 密钥。

txt┌ API key
│
│
└ enter

1. 执行 /models 命令选择模型，例如 Kimi K2 Instruct。

txt/models

DeepSeek

1. 前往 DeepSeek 控制台，创建账户并点击 Create new API key。

2. 执行 /connect 命令并搜索 DeepSeek。

txt/connect

1. 输入你的 DeepSeek API 密钥。

txt┌ API key
│
│
└ enter

1. 执行 /models 命令选择 DeepSeek 模型，例如 DeepSeek V4 Pro。

txt/models

Deep Infra

1. 前往 Deep Infra 仪表盘，创建账户并生成 API 密钥。

2. 执行 /connect 命令并搜索 Deep Infra。

txt/connect

1. 输入你的 Deep Infra API 密钥。

txt┌ API key
│
│
└ enter

1. 执行 /models 命令选择模型。

txt/models

FrogBot

1. 前往 FrogBot 仪表盘，创建账户并生成 API 密钥。

2. 执行 /connect 命令并搜索 FrogBot。

txt/connect

1. 输入你的 FrogBot API 密钥。

txt┌ API key
│
│
└ enter

1. 执行 /models 命令选择模型。

txt/models

Fireworks AI

1. 前往 Fireworks AI 控制台，创建账户并点击 Create API Key。

2. 执行 /connect 命令并搜索 Fireworks AI。

txt/connect

1. 输入你的 Fireworks AI API 密钥。

txt┌ API key
│
│
└ enter

1. 执行 /models 命令选择模型，例如 Kimi K2 Instruct。

txt/models

GitLab Duo

GitLab Duo 通过 GitLab 的 Anthropic 代理提供具有原生工具调用能力的 AI 驱动的代理聊天。

1. 执行 /connect 命令并选择 GitLab。

txt/connect

1. 选择你的身份验证方式：

txt┌ Select auth method
│
│ OAuth (Recommended)
│ Personal Access Token
└

使用 OAuth（推荐）

选择 OAuth，浏览器会自动打开进行授权。

使用个人访问令牌

1. 前往 GitLab 用户设置 > Access Tokens
2. 点击 Add new token
3. 名称填写 DevEco Code，范围选择 api
4. 复制令牌（以 glpat- 开头）
5. 在终端中输入该令牌

1. 执行 /models 命令查看可用模型。

txt/models

提供三个基于 Claude 的模型：
- duo-chat-haiku-4-5（默认）- 快速响应，适合简单任务
- duo-chat-sonnet-4-5 - 性能均衡，适合大多数工作流
- duo-chat-opus-4-5 - 最强大，适合复杂分析

自托管 GitLab

{
  "$schema": "https://opencode.ai/config.json",
  "small_model": "gitlab/duo-chat-haiku-4-5",
  "share": "disabled"
}

对于自托管 GitLab 实例：

bashexport GITLAB_INSTANCE_URL=https://gitlab.company.com
export GITLAB_TOKEN=glpat-...

如果你的实例运行了自定义 AI Gateway：

bashGITLAB_AI_GATEWAY_URL=https://ai-gateway.company.com

或者添加到你的 bash 配置文件中：

bashexport GITLAB_INSTANCE_URL=https://gitlab.company.com
export GITLAB_AI_GATEWAY_URL=https://ai-gateway.company.com
export GITLAB_TOKEN=glpat-...

自托管实例的 OAuth

要在自托管实例上使用 OAuth，你需要创建一个新应用（设置 → 应用），回调 URL 设置为 http://127.0.0.1:8080/callback，并选择以下范围：

• api（代表你访问 API）
• read_user（读取你的个人信息）
• read_repository（允许对仓库进行只读访问）

然后将应用 ID 导出为环境变量：

bashexport GITLAB_OAUTH_CLIENT_ID=your_application_id_here

更多文档请参阅 @deveco/deveco-code-gitlab-auth 主页。

配置

通过 deveco.json 进行自定义配置：

json{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "gitlab": {
      "options": {
        "instanceUrl": "https://gitlab.com"
      }
    }
  }
}

GitLab API 工具（可选，但强烈推荐）

要访问 GitLab 工具（合并请求、Issue、流水线、CI/CD 等）：

json{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@deveco/deveco-code-gitlab-plugin"]
}

该插件提供全面的 GitLab 仓库管理功能，包括 MR 审查、Issue 跟踪、流水线监控等。

GitHub Copilot

要在 DevEco Code 中使用你的 GitHub Copilot 订阅：

1. 执行 /connect 命令并搜索 GitHub Copilot。

txt/connect

1. 前往 github.com/login/device 并输入验证码。

txt┌ Login with GitHub Copilot
│
│ https://github.com/login/device
│
│ Enter code: 8F43-6FCF
│
└ Waiting for authorization...

1. 现在执行 /models 命令选择你想要的模型。

txt/models

Google Vertex AI

要在 DevEco Code 中使用 Google Vertex AI：

1. 前往 Google Cloud Console 中的模型花园，查看你所在区域可用的模型。

1. 设置所需的环境变量：
2. GOOGLE_CLOUD_PROJECT：你的 Google Cloud 项目 ID
3. VERTEX_LOCATION（可选）：Vertex AI 的区域（默认为 global）
4. 身份验证（选择其一）：
   • GOOGLE_APPLICATION_CREDENTIALS：服务账户 JSON 密钥文件的路径
   • 使用 gcloud CLI 进行身份验证：gcloud auth application-default login

在运行 deveco 时设置：

bashGOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json GOOGLE_CLOUD_PROJECT=your-project-id deveco

或者添加到你的 bash 配置文件中：

bashexport GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
export GOOGLE_CLOUD_PROJECT=your-project-id
export VERTEX_LOCATION=global

1. 执行 /models 命令选择你想要的模型。

txt/models

Groq

1. 前往 Groq 控制台，点击 Create API Key 并复制密钥。

2. 执行 /connect 命令并搜索 Groq。

txt/connect

1. 输入该提供商的 API 密钥。

txt┌ API key
│
│
└ enter

1. 执行 /models 命令选择你想要的模型。

txt/models

Hugging Face

Hugging Face Inference Providers 提供对由 17+ 提供商支持的开放模型的访问。

1. 前往 Hugging Face 设置，创建一个具有调用 Inference Providers 权限的令牌。

2. 执行 /connect 命令并搜索 Hugging Face。

txt/connect

1. 输入你的 Hugging Face 令牌。

txt┌ API key
│
│
└ enter

1. 执行 /models 命令选择模型，例如 Kimi-K2-Instruct 或 GLM-4.6。

txt/models

Helicone

Helicone 是一个 LLM 可观测性平台，为你的 AI 应用提供日志记录、监控和分析功能。Helicone AI Gateway 会根据模型自动将请求路由到对应的提供商。

1. 前往 Helicone，创建账户并在仪表盘中生成 API 密钥。

2. 执行 /connect 命令并搜索 Helicone。

txt/connect

1. 输入你的 Helicone API 密钥。

txt┌ API key
│
│
└ enter

1. 执行 /models 命令选择模型。

txt/models

如需了解更多提供商以及缓存、速率限制等高级功能，请查阅 Helicone 文档。

可选配置

如果 Helicone 的某些功能或模型未通过 DevEco Code 自动配置，你随时可以手动配置。

Helicone 模型目录中可以找到你需要添加的模型 ID。

jsonc{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "helicone": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Helicone",
      "options": {
        "baseURL": "https://ai-gateway.helicone.ai",
      },
      "models": {
        "gpt-4o": {
          // Model ID (from Helicone's model directory page)
          "name": "GPT-4o", // Your own custom name for the model
        },
        "claude-sonnet-4-20250514": {
          "name": "Claude Sonnet 4",
        },
      },
    },
  },
}

自定义请求头

Helicone 支持用于缓存、用户跟踪和会话管理等功能的自定义请求头。使用 options.headers 将它们添加到提供商配置中：

jsonc{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "helicone": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Helicone",
      "options": {
        "baseURL": "https://ai-gateway.helicone.ai",
        "headers": {
          "Helicone-Cache-Enabled": "true",
          "Helicone-User-Id": "deveco",
        },
      },
    },
  },
}

会话跟踪

Helicone 的 Sessions 功能允许你将相关的 LLM 请求归为一组。使用 opencode-helicone-session 插件可以自动将每个 OpenCode 对话记录为 Helicone 中的一个会话。

bashnpm install -g opencode-helicone-session

将其添加到配置中。

json{
  "plugin": ["opencode-helicone-session"]
}

该插件会在你的请求中注入 Helicone-Session-Id 和 Helicone-Session-Name 请求头。在 Helicone 的 Sessions 页面中，你可以看到每个 DevEco Code 对话都作为独立的会话列出。

常用 Helicone 请求头

有关所有可用请求头，请参阅 Helicone Header Directory。

llama.cpp

你可以通过 llama.cpp 的 llama-server 工具配置 DevEco Code 使用本地模型。

json{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "llama.cpp": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "llama-server (local)",
      "options": {
        "baseURL": "http://127.0.0.1:8080/v1"
      },
      "models": {
        "qwen3-coder:a3b": {
          "name": "Qwen3-Coder: a3b-30b (local)",
          "limit": {
            "context": 128000,
            "output": 65536
          }
        }
      }
    }
  }
}

在这个示例中：

• llama.cpp 是自定义的提供商 ID，可以是任意字符串。
• npm 指定该提供商使用的包。这里使用 @ai-sdk/openai-compatible 来兼容任何 OpenAI 兼容的 API。
• name 是该提供商在 UI 中显示的名称。
• options.baseURL 是本地服务器的端点地址。
• models 是模型 ID 到其配置的映射。模型名称会显示在模型选择列表中。

IO.NET

IO.NET 提供 17 个针对不同用例优化的模型：

1. 前往 IO.NET 控制台，创建账户并生成 API 密钥。

2. 执行 /connect 命令并搜索 IO.NET。

txt/connect

1. 输入你的 IO.NET API 密钥。

txt┌ API key
│
│
└ enter

1. 执行 /models 命令选择模型。

txt/models

LM Studio

你可以通过 LM Studio 配置 DevEco Code 使用本地模型。

json{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "lmstudio": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LM Studio (local)",
      "options": {
        "baseURL": "http://127.0.0.1:1234/v1"
      },
      "models": {
        "google/gemma-3n-e4b": {
          "name": "Gemma 3n-e4b (local)"
        }
      }
    }
  }
}

在这个示例中：

• lmstudio 是自定义的提供商 ID，可以是任意字符串。
• npm 指定该提供商使用的包。这里使用 @ai-sdk/openai-compatible 来兼容任何 OpenAI 兼容的 API。
• name 是该提供商在 UI 中显示的名称。
• options.baseURL 是本地服务器的端点地址。
• models 是模型 ID 到其配置的映射。模型名称会显示在模型选择列表中。

Moonshot AI

要使用 Moonshot AI 的 Kimi K2：

1. 前往 Moonshot AI 控制台，创建账户并点击 Create API key。

2. 执行 /connect 命令并搜索 Moonshot AI。

txt/connect

1. 输入你的 Moonshot API 密钥。

txt┌ API key
│
│
└ enter

1. 执行 /models 命令选择 Kimi K2。

txt/models

MiniMax

1. 前往 MiniMax API 控制台，创建账户并生成 API 密钥。

2. 执行 /connect 命令并搜索 MiniMax。

txt/connect

1. 输入你的 MiniMax API 密钥。

txt┌ API key
│
│
└ enter

1. 执行 /models 命令选择模型，例如 M2.1。

txt/models

Nebius Token Factory

1. 前往 Nebius Token Factory 控制台，创建账户并点击 Add Key。

2. 执行 /connect 命令并搜索 Nebius Token Factory。

txt/connect

1. 输入你的 Nebius Token Factory API 密钥。

txt┌ API key
│
│
└ enter

1. 执行 /models 命令选择模型，例如 Kimi K2 Instruct。

txt/models

Ollama

你可以通过 Ollama 配置 DevEco Code 使用本地模型。

json{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "llama2": {
          "name": "Llama 2"
        }
      }
    }
  }
}

在这个示例中：

• ollama 是自定义的提供商 ID，可以是任意字符串。
• npm 指定该提供商使用的包。这里使用 @ai-sdk/openai-compatible 来兼容任何 OpenAI 兼容的 API。
• name 是该提供商在 UI 中显示的名称。
• options.baseURL 是本地服务器的端点地址。
• models 是模型 ID 到其配置的映射。模型名称会显示在模型选择列表中。

Ollama Cloud

要在 DevEco Code 中使用 Ollama Cloud：

1. 前往 https://ollama.com/ 登录或创建账户。

2. 导航到 Settings > Keys，点击 Add API Key 生成新的 API 密钥。

3. 复制 API 密钥以便在 DevEco Code 中使用。

4. 执行 /connect 命令并搜索 Ollama Cloud。

txt/connect

1. 输入你的 Ollama Cloud API 密钥。

txt┌ API key
│
│
└ enter

1. 重要：在 DevEco Code 中使用云端模型之前，必须先将模型信息拉取到本地：

bashollama pull gpt-oss:20b-cloud

1. 执行 /models 命令选择你的 Ollama Cloud 模型。

txt/models

OpenAI

我们建议注册 ChatGPT Plus 或 Pro。

1. 注册完成后，执行 /connect 命令并选择 OpenAI。

txt/connect

1. 你可以选择 ChatGPT Plus/Pro 选项，浏览器会自动打开并要求你进行身份验证。

txt┌ Select auth method
│
│ ChatGPT Plus/Pro
│ Manually enter API Key
└

1. 现在使用 /models 命令即可看到所有 OpenAI 模型。

txt/models

使用 API 密钥

如果你已经有 API 密钥，可以选择 Manually enter API Key 并将其粘贴到终端中。

OpenRouter

1. 前往 OpenRouter 仪表盘，点击 Create API Key 并复制密钥。

2. 执行 /connect 命令并搜索 OpenRouter。

txt/connect

1. 输入该提供商的 API 密钥。

txt┌ API key
│
│
└ enter

1. 默认已预加载了许多 OpenRouter 模型，执行 /models 命令选择你想要的模型。

txt/models

你也可以通过 DevEco Code 配置添加更多模型。

json{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openrouter": {
      "models": {
        "somecoolnewmodel": {}
      }
    }
  }
}

1. 你还可以通过 DevEco Code 配置自定义模型。以下是指定提供商的示例：

json{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openrouter": {
      "models": {
        "moonshotai/kimi-k2": {
          "options": {
            "provider": {
              "order": ["baseten"],
              "allow_fallbacks": false
            }
          }
        }
      }
    }
  }
}

SAP AI Core

SAP AI Core 通过统一平台提供对来自 OpenAI、Anthropic、Google、Amazon、Meta、Mistral 和 AI21 的 40+ 模型的访问。

1. 前往 SAP BTP Cockpit，导航到你的 SAP AI Core 服务实例，并创建服务密钥。

1. 执行 /connect 命令并搜索 SAP AI Core。

txt/connect

1. 输入你的服务密钥 JSON。

txt┌ Service key
│
│
└ enter

或者设置 AICORE_SERVICE_KEY 环境变量：

bashAICORE_SERVICE_KEY='{"clientid":"...","clientsecret":"...","url":"...","serviceurls":{"AI_API_URL":"..."}' deveco

或者添加到你的 bash 配置文件中：

bashexport AICORE_SERVICE_KEY='{"clientid":"...","clientsecret":"...","url":"...","serviceurls":{"AI_API_URL":"..."}'

1. 可选：设置部署 ID 和资源组：

bashAICORE_DEPLOYMENT_ID=your-deployment-id AICORE_RESOURCE_GROUP=your-resource-group deveco

1. 执行 /models 命令从 40+ 个可用模型中进行选择。

txt/models

STACKIT

STACKIT AI Model Serving 提供完全托管的主权托管环境，专注于 Llama、Mistral 和 Qwen 等大语言模型，在欧洲基础设施上实现最大程度的数据主权。

1. 前往 STACKIT Portal，导航到 AI Model Serving，为你的项目创建认证令牌。

1. 执行 /connect 命令并搜索 STACKIT。

txt/connect

1. 输入你的 STACKIT AI Model Serving 认证令牌。

txt┌ API key
│
│
└ enter

1. 执行 /models 命令选择模型，例如 Qwen3-VL 235B 或 Llama 3.3 70B。

txt/models

OVHcloud AI Endpoints

1. 前往 OVHcloud 管理面板。导航到 Public Cloud 部分，AI & Machine Learning > AI Endpoints，在 API Keys 标签页中点击 Create a new API key。

2. 执行 /connect 命令并搜索 OVHcloud AI Endpoints。

txt/connect

1. 输入你的 OVHcloud AI Endpoints API 密钥。

txt┌ API key
│
│
└ enter

1. 执行 /models 命令选择模型，例如 gpt-oss-120b。

txt/models

Scaleway

要在 DevEco Code 中使用 Scaleway Generative APIs：

1. 前往 Scaleway Console IAM 设置生成新的 API 密钥。

2. 执行 /connect 命令并搜索 Scaleway。

txt/connect

1. 输入你的 Scaleway API 密钥。

txt┌ API key
│
│
└ enter

1. 执行 /models 命令选择模型，例如 devstral-2-123b-instruct-2512 或 gpt-oss-120b。

txt/models

Together AI

1. 前往 Together AI 控制台，创建账户并点击 Add Key。

2. 执行 /connect 命令并搜索 Together AI。

txt/connect

1. 输入你的 Together AI API 密钥。

txt┌ API key
│
│
└ enter

1. 执行 /models 命令选择模型，例如 Kimi K2 Instruct。

txt/models

Venice AI

1. 前往 Venice AI 控制台，创建账户并生成 API 密钥。

2. 执行 /connect 命令并搜索 Venice AI。

txt/connect

1. 输入你的 Venice AI API 密钥。

txt┌ API key
│
│
└ enter

1. 执行 /models 命令选择模型，例如 Llama 3.3 70B。

txt/models

Vercel AI Gateway

Vercel AI Gateway 允许你通过统一端点访问来自 OpenAI、Anthropic、Google、xAI 等提供商的模型。模型按原价提供，不额外加价。

1. 前往 Vercel 仪表盘，导航到 AI Gateway 标签页，点击 API keys 创建新的 API 密钥。

2. 执行 /connect 命令并搜索 Vercel AI Gateway。

txt/connect

1. 输入你的 Vercel AI Gateway API 密钥。

txt┌ API key
│
│
└ enter

1. 执行 /models 命令选择模型。

txt/models

你也可以通过 DevEco Code 配置自定义模型。以下是指定提供商路由顺序的示例。

json{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "vercel": {
      "models": {
        "anthropic/claude-sonnet-4": {
          "options": {
            "order": ["anthropic", "vertex"]
          }
        }
      }
    }
  }
}

一些常用的路由选项：

xAI

1. 前往 xAI 控制台，创建账户并生成 API 密钥。

2. 执行 /connect 命令并搜索 xAI。

txt/connect

1. 输入你的 xAI API 密钥。

txt┌ API key
│
│
└ enter

1. 执行 /models 命令选择模型，例如 Grok Beta。

txt/models

Z.AI

1. 前往 Z.AI API 控制台，创建账户并点击 Create a new API key。

2. 执行 /connect 命令并搜索 Z.AI。

txt/connect

如果你订阅了 GLM Coding Plan，请选择 Z.AI Coding Plan。

1. 输入你的 Z.AI API 密钥。

txt┌ API key
│
│
└ enter

1. 执行 /models 命令选择模型，例如 GLM-4.7。

txt/models

ZenMux

1. 前往 ZenMux 仪表盘，点击 Create API Key 并复制密钥。

2. 执行 /connect 命令并搜索 ZenMux。

txt/connect

1. 输入该提供商的 API 密钥。

txt┌ API key
│
│
└ enter

1. 默认已预加载了许多 ZenMux 模型，执行 /models 命令选择你想要的模型。

txt/models

你也可以通过 DevEco Code 配置添加更多模型。

json{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "zenmux": {
      "models": {
        "somecoolnewmodel": {}
      }
    }
  }
}

自定义提供商

要添加 /connect 命令中未列出的任何 OpenAI 兼容提供商：

1. 执行 /connect 命令，向下滚动到 Other。

bash$ /connect

┌  Add credential
│
◆  Select provider
│  ...
│  ● Other
└

1. 输入该提供商的唯一 ID。

bash$ /connect

┌  Add credential
│
◇  Enter provider id
│  myprovider
└

1. 输入该提供商的 API 密钥。

bash$ /connect

┌  Add credential
│
▲  This only stores a credential for myprovider - you will need to configure it in deveco.json, check the docs for examples.
│
◇  Enter your API key
│  sk-...
└

1. 在项目目录中创建或更新 deveco.json 文件：

jsonmyprovider{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "myprovider": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "My AI ProviderDisplay Name",
      "options": {
        "baseURL": "https://api.myprovider.com/v1"
      },
      "models": {
        "my-model-name": {
          "name": "My Model Display Name"
        }
      }
    }
  }
}

以下是配置选项说明：
- npm：要使用的 AI SDK 包，对于 OpenAI 兼容的提供商使用 @ai-sdk/openai-compatible（适用于 /v1/chat/completions）。如果你的提供商/模型走 /v1/responses，请使用 @ai-sdk/openai。
- name：在 UI 中显示的名称。
- models：可用模型。
- options.baseURL：API 端点 URL。
- options.apiKey：可选，如果不使用 auth 认证，可直接设置 API 密钥。
- options.headers：可选，设置自定义请求头。

更多高级选项请参见下面的示例。

1. 执行 /models 命令，你自定义的提供商和模型将出现在选择列表中。

示例

以下是设置 apiKey、headers 和模型 limit 选项的示例。

json{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "myprovider": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "My AI ProviderDisplay Name",
      "options": {
        "baseURL": "https://api.myprovider.com/v1",
        "apiKey": "{env:ANTHROPIC_API_KEY}",
        "headers": {
          "Authorization": "Bearer custom-token"
        }
      },
      "models": {
        "my-model-name": {
          "name": "My Model Display Name",
          "limit": {
            "context": 200000,
            "output": 65536
          }
        }
      }
    }
  }
}

配置详情：

• apiKey：使用 env 变量语法设置，了解更多。
• headers：随每个请求发送的自定义请求头。
• limit.context：模型接受的最大输入 Token 数。
• limit.output：模型可生成的最大 Token 数。

limit 字段让 DevEco Code 了解你还剩余多少上下文空间。标准提供商会自动从 models.dev 拉取这些信息。

故障排除

如果你在配置提供商时遇到问题，请检查以下几点：

1. 检查认证设置：运行 deveco auth list 查看该提供商的凭据是否已添加到配置中。

这不适用于 Amazon Bedrock 等依赖环境变量进行认证的提供商。

1. 对于自定义提供商，请检查 DevEco Code 配置并确认：
2. /connect 命令中使用的提供商 ID 与 DevEco Code 配置中的 ID 一致。
3. 使用了正确的 npm 包。例如，Cerebras 应使用 @ai-sdk/cerebras。对于其他所有 OpenAI 兼容的提供商，使用 @ai-sdk/openai-compatible（/v1/chat/completions）；如果模型走 /v1/responses，请使用 @ai-sdk/openai。同一 provider 混用时，可在模型下设置 provider.npm 覆盖默认值。
4. options.baseURL 字段中的 API 端点地址正确。

DevEco Code 使用 permission 配置来决定某个操作是否应自动运行、提示你审批，还是被阻止。

操作

每条权限规则解析为以下之一：

• "allow" — 无需审批直接运行
• "ask" — 提示审批
• "deny" — 阻止该操作

配置

你可以全局设置权限（使用 *），并覆盖特定工具的权限。

json{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "*": "ask",
    "bash": "allow",
    "edit": "deny"
  }
}

你还可以一次性设置所有权限：

json{
  "$schema": "https://opencode.ai/config.json",
  "permission": "allow"
}

细粒度规则（对象语法）

对于大多数权限，你可以使用对象来根据工具输入应用不同的操作。

json{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "bash": {
      "*": "ask",
      "git *": "allow",
      "npm *": "allow",
      "rm *": "deny",
      "grep *": "allow"
    },
    "edit": {
      "*": "deny",
      "packages/web/src/content/docs/*.mdx": "allow"
    }
  }
}

规则通过模式匹配进行评估，最后匹配的规则优先。常见做法是将通配的 "*" 规则放在最前面，更具体的规则放在后面。

通配符

权限模式使用简单的通配符匹配：

• * 匹配零个或多个任意字符
• ? 精确匹配一个字符
• 所有其他字符按字面值匹配

主目录展开

你可以在模式开头使用 ~ 或 $HOME 来引用你的主目录。这对于 external_directory 规则特别有用。

• ~/projects/* -> /Users/username/projects/*
• $HOME/projects/* -> /Users/username/projects/*
• ~ -> /Users/username

外部目录

使用 external_directory 允许工具调用访问 DevEco Code 启动时工作目录之外的路径。这适用于任何接受路径作为输入的工具（例如 read、edit、glob、grep 以及许多 bash 命令）。

主目录展开（如 ~/...）仅影响模式的书写方式。它不会将外部路径纳入当前工作空间，因此工作目录之外的路径仍然必须通过 external_directory 来允许。

例如，以下配置允许访问 ~/projects/personal/ 下的所有内容：

json{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "external_directory": {
      "~/projects/personal/**": "allow"
    }
  }
}

此处允许的任何目录都会继承与当前工作空间相同的默认值。由于 read 默认为 allow，external_directory 下的条目也允许读取，除非另行覆盖。当需要在这些路径中限制某个工具时，请添加显式规则，例如在保留读取的同时阻止编辑：

json{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "external_directory": {
      "~/projects/personal/**": "allow"
    },
    "edit": {
      "~/projects/personal/**": "deny"
    }
  }
}

请将列表限定在受信任的路径上，并根据需要为其他工具（例如 bash）叠加额外的允许或拒绝规则。

可用权限

DevEco Code 的权限以工具名称为键，外加几个安全防护项：

• read — 读取文件（匹配文件路径）
• edit — 所有文件修改（涵盖 edit、write、patch）
• glob — 文件通配（匹配通配模式）
• grep — 内容搜索（匹配正则表达式模式）
• bash — 运行 shell 命令（匹配解析后的命令，如 git status --porcelain）
• task — 启动子代理（匹配子代理类型）
• skill — 加载技能（匹配技能名称）
• lsp — 运行 LSP 查询（当前不支持细粒度配置）
• webfetch — 获取 URL（匹配 URL）
• websearch — 网页搜索（匹配查询内容）
• external_directory — 当工具访问项目工作目录之外的路径时触发
• doom_loop — 当同一工具调用以相同输入重复 3 次时触发

默认值

如果你未指定任何配置，DevEco Code 将使用宽松的默认值：

• 大多数权限默认为 "allow"。
• doom_loop 和 external_directory 默认为 "ask"。
• read 为 "allow"，但 .env 文件默认被拒绝：

json{
  "permission": {
    "read": {
      "*": "allow",
      "*.env": "deny",
      "*.env.*": "deny",
      "*.env.example": "allow"
    }
  }
}

"Ask"的作用

当 DevEco Code 提示审批时，界面提供三种选择：

• once — 仅批准本次请求
• always — 批准与建议模式匹配的后续请求（在当前 DevEco Code 会话的剩余时间内有效）
• reject — 拒绝请求

always 所批准的模式集合由工具提供（例如，bash 审批通常会将安全的命令前缀如 git status* 加入白名单）。

代理

你可以为每个代理单独覆盖权限。代理权限会与全局配置合并，且代理规则优先。了解更多关于代理权限的内容。

json{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "bash": {
      "*": "ask",
      "git *": "allow",
      "git commit *": "deny",
      "git push *": "deny",
      "grep *": "allow"
    }
  },
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "ask",
          "git *": "allow",
          "git commit *": "ask",
          "git push *": "deny",
          "grep *": "allow"
        }
      }
    }
  }
}

你还可以在 Markdown 中配置代理权限：

markdown---
description: Code review without edits
mode: subagent
permission:
  edit: deny
  bash: ask
  webfetch: deny
---

Only analyze code and suggest changes.

通过 DevEco Code，您可以从多个内置主题中进行选择，使用能自动适配终端主题的主题，或者定义您自己的自定义主题。

默认情况下，DevEco Code 使用我们自己的 deveco 主题。

终端要求

为了使主题能够正确显示完整的调色板，您的终端必须支持真彩色（24 位色）。大多数现代终端默认支持此功能，但您可能需要手动启用：

• 检查支持情况：运行 echo $COLORTERM — 输出应为 truecolor 或 24bit
• 启用真彩色：在您的 shell 配置文件中设置环境变量 COLORTERM=truecolor
• 终端兼容性：确保您的终端模拟器支持 24 位色（大多数现代终端如 iTerm2、Alacritty、Kitty、Windows Terminal 以及较新版本的 GNOME Terminal 均已支持）

如果没有真彩色支持，主题可能会出现色彩精度下降的情况，或者回退到最接近的 256 色近似值。

内置主题

DevEco Code 自带多个内置主题。

我们还在不断添加更多主题。

系统主题

system 主题旨在自动适配您终端的配色方案。与使用固定颜色的传统主题不同，system 主题具有以下特点：

• 生成灰度色阶：根据终端的背景颜色创建自定义灰度色阶，确保最佳对比度。
• 使用 ANSI 颜色：利用标准 ANSI 颜色（0-15）进行语法高亮和 UI 元素渲染，遵循终端的调色板设置。
• 保留终端默认值：将文本和背景颜色设为 none，以保持终端的原生外观。

系统主题适合以下用户：

• 希望 DevEco Code 与终端的外观保持一致
• 使用了自定义终端配色方案
• 偏好所有终端应用程序拥有统一的视觉风格

使用主题

您可以通过 /theme 命令调出主题选择界面来选择主题，也可以在 tui.json 文件中直接指定。

json{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "tokyonight"
}

自定义主题

DevEco Code 支持灵活的基于 JSON 的主题系统，让用户可以轻松创建和自定义主题。

层级优先级

主题按以下顺序从多个目录加载，后面的目录会覆盖前面的目录：

1. 内置主题 — 嵌入在二进制文件中
2. 用户配置目录 — 定义在 ~/.config/deveco/themes/*.json 或 $XDG_CONFIG_HOME/deveco/themes/*.json
3. 项目根目录 — 定义在 <project-root>/.deveco/themes/*.json
4. 当前工作目录 — 定义在 ./.deveco/themes/*.json

如果多个目录包含同名主题，将使用优先级较高的目录中的主题。

创建主题

要创建自定义主题，请在上述任一主题目录中创建一个 JSON 文件。

创建用户级主题：

bashmkdir -p ~/.config/deveco/themes
vim ~/.config/deveco/themes/my-theme.json

创建项目级主题：

bashmkdir -p .deveco/themes
vim .deveco/themes/my-theme.json

JSON 格式

主题使用灵活的 JSON 格式，支持以下特性：

• 十六进制颜色："#ffffff"
• ANSI 颜色：3（0-255）
• 颜色引用："primary" 或自定义定义的颜色名
• 深色/浅色变体：``
• 无颜色："none" — 使用终端的默认颜色或透明背景

颜色定义

defs 部分是可选的，它允许您定义可在主题中重复引用的可复用颜色。

终端默认值

特殊值 "none" 可用于任何颜色属性，以继承终端的默认颜色。这在创建需要与终端配色方案无缝融合的主题时特别有用：

• "text": "none" — 使用终端的默认前景色
• "background": "none" — 使用终端的默认背景色

示例

以下是一个自定义主题的完整示例：

json{
  "$schema": "https://opencode.ai/theme.json",
  "defs": {
    "nord0": "#2E3440",
    "nord1": "#3B4252",
    "nord2": "#434C5E",
    "nord3": "#4C566A",
    "nord4": "#D8DEE9",
    "nord5": "#E5E9F0",
    "nord6": "#ECEFF4",
    "nord7": "#8FBCBB",
    "nord8": "#88C0D0",
    "nord9": "#81A1C1",
    "nord10": "#5E81AC",
    "nord11": "#BF616A",
    "nord12": "#D08770",
    "nord13": "#EBCB8B",
    "nord14": "#A3BE8C",
    "nord15": "#B48EAD"
  },
  "theme": {
    "primary": {
      "dark": "nord8",
      "light": "nord10"
    },
    "secondary": {
      "dark": "nord9",
      "light": "nord9"
    },
    "accent": {
      "dark": "nord7",
      "light": "nord7"
    },
    "error": {
      "dark": "nord11",
      "light": "nord11"
    },
    "warning": {
      "dark": "nord12",
      "light": "nord12"
    },
    "success": {
      "dark": "nord14",
      "light": "nord14"
    },
    "info": {
      "dark": "nord8",
      "light": "nord10"
    },
    "text": {
      "dark": "nord4",
      "light": "nord0"
    },
    "textMuted": {
      "dark": "nord3",
      "light": "nord1"
    },
    "background": {
      "dark": "nord0",
      "light": "nord6"
    },
    "backgroundPanel": {
      "dark": "nord1",
      "light": "nord5"
    },
    "backgroundElement": {
      "dark": "nord1",
      "light": "nord4"
    },
    "border": {
      "dark": "nord2",
      "light": "nord3"
    },
    "borderActive": {
      "dark": "nord3",
      "light": "nord2"
    },
    "borderSubtle": {
      "dark": "nord2",
      "light": "nord3"
    },
    "diffAdded": {
      "dark": "nord14",
      "light": "nord14"
    },
    "diffRemoved": {
      "dark": "nord11",
      "light": "nord11"
    },
    "diffContext": {
      "dark": "nord3",
      "light": "nord3"
    },
    "diffHunkHeader": {
      "dark": "nord3",
      "light": "nord3"
    },
    "diffHighlightAdded": {
      "dark": "nord14",
      "light": "nord14"
    },
    "diffHighlightRemoved": {
      "dark": "nord11",
      "light": "nord11"
    },
    "diffAddedBg": {
      "dark": "#3B4252",
      "light": "#E5E9F0"
    },
    "diffRemovedBg": {
      "dark": "#3B4252",
      "light": "#E5E9F0"
    },
    "diffContextBg": {
      "dark": "nord1",
      "light": "nord5"
    },
    "diffLineNumber": {
      "dark": "nord2",
      "light": "nord4"
    },
    "diffAddedLineNumberBg": {
      "dark": "#3B4252",
      "light": "#E5E9F0"
    },
    "diffRemovedLineNumberBg": {
      "dark": "#3B4252",
      "light": "#E5E9F0"
    },
    "markdownText": {
      "dark": "nord4",
      "light": "nord0"
    },
    "markdownHeading": {
      "dark": "nord8",
      "light": "nord10"
    },
    "markdownLink": {
      "dark": "nord9",
      "light": "nord9"
    },
    "markdownLinkText": {
      "dark": "nord7",
      "light": "nord7"
    },
    "markdownCode": {
      "dark": "nord14",
      "light": "nord14"
    },
    "markdownBlockQuote": {
      "dark": "nord3",
      "light": "nord3"
    },
    "markdownEmph": {
      "dark": "nord12",
      "light": "nord12"
    },
    "markdownStrong": {
      "dark": "nord13",
      "light": "nord13"
    },
    "markdownHorizontalRule": {
      "dark": "nord3",
      "light": "nord3"
    },
    "markdownListItem": {
      "dark": "nord8",
      "light": "nord10"
    },
    "markdownListEnumeration": {
      "dark": "nord7",
      "light": "nord7"
    },
    "markdownImage": {
      "dark": "nord9",
      "light": "nord9"
    },
    "markdownImageText": {
      "dark": "nord7",
      "light": "nord7"
    },
    "markdownCodeBlock": {
      "dark": "nord4",
      "light": "nord0"
    },
    "syntaxComment": {
      "dark": "nord3",
      "light": "nord3"
    },
    "syntaxKeyword": {
      "dark": "nord9",
      "light": "nord9"
    },
    "syntaxFunction": {
      "dark": "nord8",
      "light": "nord8"
    },
    "syntaxVariable": {
      "dark": "nord7",
      "light": "nord7"
    },
    "syntaxString": {
      "dark": "nord14",
      "light": "nord14"
    },
    "syntaxNumber": {
      "dark": "nord15",
      "light": "nord15"
    },
    "syntaxType": {
      "dark": "nord7",
      "light": "nord7"
    },
    "syntaxOperator": {
      "dark": "nord9",
      "light": "nord9"
    },
    "syntaxPunctuation": {
      "dark": "nord4",
      "light": "nord0"
    }
  }
}

DevEco Code 提供了一系列快捷键，您可以通过 tui.json 进行自定义。

json{
  "$schema": "https://opencode.ai/tui.json",
  "keybinds": {
    "leader": "ctrl+x",
    "app_exit": "ctrl+c,ctrl+d,<leader>q",
    "editor_open": "<leader>e",
    "theme_list": "<leader>t",
    "sidebar_toggle": "<leader>b",
    "scrollbar_toggle": "none",
    "username_toggle": "none",
    "status_view": "<leader>s",
    "tool_details": "none",
    "session_export": "<leader>x",
    "session_new": "<leader>n",
    "session_list": "<leader>l",
    "session_timeline": "<leader>g",
    "session_fork": "none",
    "session_rename": "none",
    "session_interrupt": "escape",
    "session_compact": "<leader>c",
    "session_child_first": "<leader>down",
    "session_child_cycle": "<leader>right",
    "session_child_cycle_reverse": "<leader>left",
    "session_parent": "<leader>up",
    "messages_page_up": "pageup,ctrl+alt+b",
    "messages_page_down": "pagedown,ctrl+alt+f",
    "messages_line_up": "ctrl+alt+y",
    "messages_line_down": "ctrl+alt+e",
    "messages_half_page_up": "ctrl+alt+u",
    "messages_half_page_down": "ctrl+alt+d",
    "messages_first": "ctrl+g,home",
    "messages_last": "ctrl+alt+g,end",
    "messages_next": "none",
    "messages_previous": "none",
    "messages_copy": "<leader>y",
    "messages_undo": "<leader>u",
    "messages_redo": "<leader>r",
    "messages_last_user": "none",
    "messages_toggle_conceal": "<leader>h",
    "model_list": "<leader>m",
    "model_cycle_recent": "f2",
    "model_cycle_recent_reverse": "shift+f2",
    "model_cycle_favorite": "none",
    "model_cycle_favorite_reverse": "none",
    "variant_cycle": "ctrl+t",
    "variant_list": "none",
    "command_list": "ctrl+p",
    "agent_list": "<leader>a",
    "agent_cycle": "tab",
    "agent_cycle_reverse": "shift+tab",
    "input_clear": "ctrl+c",
    "input_paste": "ctrl+v",
    "input_submit": "return",
    "input_newline": "shift+return,ctrl+return,alt+return,ctrl+j",
    "input_move_left": "left,ctrl+b",
    "input_move_right": "right,ctrl+f",
    "input_move_up": "up",
    "input_move_down": "down",
    "input_select_left": "shift+left",
    "input_select_right": "shift+right",
    "input_select_up": "shift+up",
    "input_select_down": "shift+down",
    "input_line_home": "ctrl+a",
    "input_line_end": "ctrl+e",
    "input_select_line_home": "ctrl+shift+a",
    "input_select_line_end": "ctrl+shift+e",
    "input_visual_line_home": "alt+a",
    "input_visual_line_end": "alt+e",
    "input_select_visual_line_home": "alt+shift+a",
    "input_select_visual_line_end": "alt+shift+e",
    "input_buffer_home": "home",
    "input_buffer_end": "end",
    "input_select_buffer_home": "shift+home",
    "input_select_buffer_end": "shift+end",
    "input_delete_line": "ctrl+shift+d",
    "input_delete_to_line_end": "ctrl+k",
    "input_delete_to_line_start": "ctrl+u",
    "input_backspace": "backspace,shift+backspace",
    "input_delete": "ctrl+d,delete,shift+delete",
    "input_undo": "ctrl+-,super+z",
    "input_redo": "ctrl+.,super+shift+z",
    "input_word_forward": "alt+f,alt+right,ctrl+right",
    "input_word_backward": "alt+b,alt+left,ctrl+left",
    "input_select_word_forward": "alt+shift+f,alt+shift+right",
    "input_select_word_backward": "alt+shift+b,alt+shift+left",
    "input_delete_word_forward": "alt+d,alt+delete,ctrl+delete",
    "input_delete_word_backward": "ctrl+w,ctrl+backspace,alt+backspace",
    "history_previous": "up",
    "history_next": "down",
    "terminal_suspend": "ctrl+z",
    "terminal_title_toggle": "none",
    "tips_toggle": "<leader>h",
    "display_thinking": "none"
  }
}

前导键

DevEco Code 的大多数快捷键使用 leader（前导键）。这可以避免与终端中的其他快捷键冲突。

默认情况下，ctrl+x 是前导键，大多数操作需要您先按下前导键，然后再按对应的快捷键。例如，要新建一个会话，请先按 ctrl+x，然后按 n。

您不一定需要使用前导键来设置快捷键，但我们建议您这样做。

禁用快捷键

您可以通过将键值添加到 tui.json 并设置为 "none" 来禁用某个快捷键。

json{
  "$schema": "https://opencode.ai/tui.json",
  "keybinds": {
    "session_compact": "none"
  }
}

Shift+Enter

某些终端默认不会发送带修饰键的 Enter 键。您可能需要配置终端将 Shift+Enter 作为转义序列发送。

Windows Terminal

打开您的 settings.json 文件，路径为：

%LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\settings.json

将以下内容添加到根级 actions 数组中：

json"actions": [
  {
    "command": {
      "action": "sendInput",
      "input": "\u001b[13;2u"
    },
    "id": "User.sendInput.ShiftEnterCustom"
  }
]

将以下内容添加到根级 keybindings 数组中：

json"keybindings": [
  {
    "keys": "shift+enter",
    "id": "User.sendInput.ShiftEnterCustom"
  }
]

保存文件并重启 Windows Terminal，或打开一个新标签页。

代理技能让 DevEco Code 能够从你的仓库或主目录中发现可复用的指令。
技能通过原生的 skill 工具按需加载——代理可以查看可用技能，并在需要时加载完整内容。

放置文件

为每个技能名称创建一个文件夹，并在其中放入 SKILL.md。
DevEco Code 会搜索以下位置：

• 项目配置：.deveco/skills/<name>/SKILL.md
• 全局配置：~/.config/deveco/skills/<name>/SKILL.md
• 项目 Claude 兼容：.claude/skills/<name>/SKILL.md
• 全局 Claude 兼容：~/.claude/skills/<name>/SKILL.md
• 项目代理兼容：.agents/skills/<name>/SKILL.md
• 全局代理兼容：~/.agents/skills/<name>/SKILL.md

了解发现机制

对于项目本地路径，DevEco Code 会从当前工作目录向上遍历，直到到达 git 工作树根目录。
在此过程中，它会加载 .deveco/ 中所有匹配的 skills/*/SKILL.md，以及匹配的 .claude/skills/*/SKILL.md 或 .agents/skills/*/SKILL.md。

全局定义也会从 ~/.config/deveco/skills/*/SKILL.md、~/.claude/skills/*/SKILL.md 和 ~/.agents/skills/*/SKILL.md 中加载。

编写 frontmatter

每个 SKILL.md 必须以 YAML frontmatter 开头。
仅识别以下字段：

• name（必填）
• description（必填）
• license（可选）
• compatibility（可选）
• metadata（可选，字符串到字符串的映射）

未知的 frontmatter 字段会被忽略。

验证名称

name 必须满足：

• 长度为 1–64 个字符
• 仅包含小写字母和数字，可用单个连字符分隔
• 不以 - 开头或结尾
• 不包含连续的 --
• 与包含 SKILL.md 的目录名称一致

等效的正则表达式：

text^[a-z0-9]+(-[a-z0-9]+)*$

遵循长度规则

description 必须为 1-1024 个字符。
请保持描述足够具体，以便代理能够正确选择。

使用示例

创建 .deveco/skills/git-release/SKILL.md，内容如下：

markdown---
name: git-release
description: Create consistent releases and changelogs
license: MIT
compatibility: deveco
metadata:
  audience: maintainers
  workflow: github
---

## What I do

- Draft release notes from merged PRs
- Propose a version bump
- Provide a copy-pasteable `gh release create` command

## When to use me

Use this when you are preparing a tagged release.
Ask clarifying questions if the target versioning scheme is unclear.

识别工具描述

DevEco Code 会在 skill 工具描述中列出可用技能。
每个条目包含技能名称和描述：

xml<available_skills>
  <skill>
    <name>git-release</name>
    <description>Create consistent releases and changelogs</description>
  </skill>
</available_skills>

代理通过调用工具来加载技能：

skill({ name: "git-release" })

配置权限

在 deveco.json 中使用基于模式的权限来控制代理可以访问哪些技能：

json{
  "permission": {
    "skill": {
      "*": "allow",
      "pr-review": "allow",
      "internal-*": "deny",
      "experimental-*": "ask"
    }
  }
}

模式支持通配符：internal-* 可匹配 internal-docs、internal-tools 等。

按代理覆盖权限

为特定代理授予与全局默认值不同的权限。

自定义代理（在代理 frontmatter 中）：

yaml---
permission:
  skill:
    "documents-*": "allow"
---

内置代理（在 deveco.json 中）：

json{
  "agent": {
    "plan": {
      "permission": {
        "skill": {
          "internal-*": "allow"
        }
      }
    }
  }
}

禁用技能工具

为不需要使用技能的代理完全禁用技能功能：

自定义代理：

yaml---
tools:
  skill: false
---

内置代理：

json{
  "agent": {
    "plan": {
      "tools": {
        "skill": false
      }
    }
  }
}

禁用后，<available_skills> 部分将被完全省略。

排查加载问题

如果某个技能没有显示：

1. 确认 SKILL.md 文件名全部为大写字母
2. 检查 frontmatter 是否包含 name 和 description
3. 确保技能名称在所有位置中唯一
4. 检查权限设置——设为 deny 的技能会对代理隐藏

你可以通过 Model Context Protocol（MCP）为 DevEco Code 添加外部工具。DevEco Code 同时支持本地和远程服务器。

添加后，MCP 工具会自动与内置工具一起提供给 LLM 使用。

注意事项

使用 MCP 服务器时，它会占用上下文空间。如果你启用了大量工具，上下文消耗会迅速增加。因此，我们建议谨慎选择要使用的 MCP 服务器。

某些 MCP 服务器（例如 GitHub MCP 服务器）往往会消耗大量 Token，很容易超出上下文限制。

启用

你可以在 DevEco Code 配置的 mcp 字段下定义 MCP 服务器。为每个 MCP 指定一个唯一的名称，在提示词中可以通过该名称来引用对应的 MCP。

jsonc{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "name-of-mcp-server": {
      // ...
      "enabled": true,
    },
    "name-of-other-mcp-server": {
      // ...
    },
  },
}

你也可以将 enabled 设置为 false 来禁用某个服务器。当你想临时禁用某个服务器而不将其从配置中移除时，这个选项非常有用。

覆盖远程默认值

组织可以通过其 .well-known/deveco 端点提供默认的 MCP 服务器。这些服务器可能默认处于禁用状态，允许用户按需启用。

要启用组织远程配置中的某个服务器，请在本地配置中添加该服务器并设置 enabled: true：

json{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true
    }
  }
}

本地配置值会覆盖远程默认值。详情请参阅配置优先级。

本地

通过在 MCP 对象中将 type 设置为 "local" 来添加本地 MCP 服务器。

jsonc{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-local-mcp-server": {
      "type": "local",
      // Or ["bun", "x", "my-mcp-command"]
      "command": ["npx", "-y", "my-mcp-command"],
      "enabled": true,
      "environment": {
        "MY_ENV_VAR": "my_env_var_value",
      },
    },
  },
}

command 用于指定本地 MCP 服务器的启动命令。你还可以传入一组环境变量。

例如，以下是添加测试用的 @modelcontextprotocol/server-everything MCP 服务器的方法。

jsonc{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp_everything": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
    },
  },
}

要使用它，可以在提示词中添加 use the mcp_everything tool。

txtuse the mcp_everything tool to add the number 3 and 4

选项

以下是配置本地 MCP 服务器的所有选项。

远程

通过将 type 设置为 "remote" 来添加远程 MCP 服务器。

json{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-remote-mcp": {
      "type": "remote",
      "url": "https://my-mcp-server.com",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer MY_API_KEY"
      }
    }
  }
}

url 是远程 MCP 服务器的地址，通过 headers 选项可以传入一组请求头。

选项

OAuth

DevEco Code 会自动处理远程 MCP 服务器的 OAuth 身份验证。当服务器需要身份验证时，DevEco Code 将：

1. 检测 401 响应并启动 OAuth 流程
2. 在服务器支持的情况下使用动态客户端注册（RFC 7591）
3. 安全地存储 Token 以供后续请求使用

自动认证

对于大多数支持 OAuth 的 MCP 服务器，无需特殊配置。只需配置远程服务器即可：

json{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-oauth-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp"
    }
  }
}

如果服务器需要身份验证，DevEco Code 会在你首次使用时提示你进行认证。你也可以使用 deveco mcp auth <server-name> 手动触发认证流程。

预注册

如果你已经从 MCP 服务器提供商处获得了客户端凭据，可以直接配置：

json{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-oauth-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "clientId": "{env:MY_MCP_CLIENT_ID}",
        "clientSecret": "{env:MY_MCP_CLIENT_SECRET}",
        "scope": "tools:read tools:execute"
      }
    }
  }
}

身份验证

你可以手动触发身份验证或管理凭据。

对特定 MCP 服务器进行身份验证：

bashdeveco mcp auth my-oauth-server

列出所有 MCP 服务器及其认证状态：

bashdeveco mcp list

删除已存储的凭据：

bashdeveco mcp logout my-oauth-server

mcp auth 命令会打开浏览器进行授权。授权完成后，DevEco Code 会将 Token 安全地存储在 ~/.local/share/deveco/mcp-auth.json 中。

禁用 OAuth

如果你想为某个服务器禁用自动 OAuth（例如，该服务器使用 API 密钥而非 OAuth），可以将 oauth 设置为 false：

json{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-api-key-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:MY_API_KEY}"
      }
    }
  }
}

OAuth 选项

调试

如果远程 MCP 服务器身份验证失败，你可以通过以下方式诊断问题：

bash# 查看所有支持 OAuth 的服务器的认证状态
deveco mcp auth list

# 调试特定服务器的连接和 OAuth 流程
deveco mcp debug my-oauth-server

mcp debug 命令会显示当前认证状态、测试 HTTP 连接，并尝试执行 OAuth 发现流程。

管理

你的 MCP 在 DevEco Code 中作为工具使用，与内置工具并列。因此，你可以像管理其他工具一样，通过 DevEco Code 配置来管理它们。

全局

你可以全局启用或禁用 MCP 工具。

json{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp-foo": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command-foo"]
    },
    "my-mcp-bar": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command-bar"]
    }
  },
  "tools": {
    "my-mcp-foo": false
  }
}

也可以使用 glob 模式来禁用所有匹配的 MCP。

json{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp-foo": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command-foo"]
    },
    "my-mcp-bar": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command-bar"]
    }
  },
  "tools": {
    "my-mcp*": false
  }
}

这里使用 glob 模式 my-mcp* 来禁用所有 MCP。

按代理配置

如果你有大量 MCP 服务器，可以选择全局禁用它们，然后仅在特定代理中启用。具体做法：

1. 全局禁用该工具。
2. 在代理配置中，将 MCP 服务器作为工具启用。

json{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command"],
      "enabled": true
    }
  },
  "tools": {
    "my-mcp*": false
  },
  "agent": {
    "my-agent": {
      "tools": {
        "my-mcp*": true
      }
    }
  }
}

Glob 模式

glob 模式使用简单的正则通配符规则：

• * 匹配零个或多个任意字符（例如，"my-mcp*" 匹配 my-mcp_search、my-mcp_list 等）
• ? 匹配恰好一个字符
• 其他字符按字面值匹配

"mymcpservername_*": false

示例

以下是一些常见 MCP 服务器的配置示例。如果你想记录其他服务器的用法，欢迎提交 PR。

Sentry

添加 Sentry MCP 服务器 以与你的 Sentry 项目和问题进行交互。

json{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sentry": {
      "type": "remote",
      "url": "https://mcp.sentry.dev/mcp",
      "oauth": {}
    }
  }
}

添加配置后，使用 Sentry 进行身份验证：

bashdeveco mcp auth sentry

这会打开浏览器窗口完成 OAuth 流程，将 DevEco Code 连接到你的 Sentry 账户。

认证完成后，你可以在提示词中使用 Sentry 工具来查询问题、项目和错误数据。

txtShow me the latest unresolved issues in my project. use sentry

Context7

添加 Context7 MCP 服务器 以搜索文档。

json{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

如果你注册了免费账户，可以使用 API 密钥来获得更高的速率限制。

json{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"
      }
    }
  }
}

这里假设你已经设置了 CONTEXT7_API_KEY 环境变量。

在提示词中添加 use context7 即可使用 Context7 MCP 服务器。

txtConfigure a Cloudflare Worker script to cache JSON API responses for five minutes. use context7

你也可以在 AGENTS.md 中添加类似的规则。

mdWhen you need to search docs, use `context7` tools.

Grep by Vercel

添加 Grep by Vercel MCP 服务器以搜索 GitHub 上的代码片段。

json{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gh_grep": {
      "type": "remote",
      "url": "https://mcp.grep.app"
    }
  }
}

由于我们将 MCP 服务器命名为 gh_grep，你可以在提示词中添加 use the gh_grep tool 来让代理使用它。

txtWhat's the right way to set a custom domain in an SST Astro component? use the gh_grep tool

你也可以在 AGENTS.md 中添加类似的规则。

mdIf you are unsure how to do something, use `gh_grep` to search code examples from GitHub.

插件允许你通过挂钩各种事件和自定义行为来扩展 DevEco Code。你可以创建插件来添加新功能、集成外部服务，或修改 DevEco Code 的默认行为。

使用插件

有两种方式加载插件。

从本地文件加载

将 JavaScript 或 TypeScript 文件放置在插件目录中。

• .deveco/plugins/ - 项目级插件
• ~/.config/deveco/plugins/ - 全局插件

这些目录中的文件会在启动时自动加载。

从 npm 加载

在配置文件中指定 npm 包。

json{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-helicone-session", "opencode-wakatime", "@my-org/custom-plugin"]
}

支持常规和带作用域的 npm 包。

插件的安装方式

npm 插件在启动时使用 Bun 自动安装。包及其依赖项会缓存在 ~/.cache/deveco/node_modules/ 中。

本地插件直接从插件目录加载。如果需要使用外部包，你必须在配置目录中创建 package.json（参见依赖项），或者将插件发布到 npm 并将其添加到配置中。

加载顺序

插件从所有来源加载，所有钩子按顺序执行。加载顺序为：

1. 全局配置 (~/.config/deveco/deveco.json)
2. 项目配置 (deveco.json)
3. 全局插件目录 (~/.config/deveco/plugins/)
4. 项目插件目录 (.deveco/plugins/)

名称和版本相同的重复 npm 包只会加载一次。但本地插件和名称相似的 npm 插件会分别独立加载。

创建插件

插件是一个 JavaScript/TypeScript 模块，它导出一个或多个插件函数。每个函数接收一个上下文对象，并返回一个钩子对象。

依赖项

本地插件和自定义工具可以使用外部 npm 包。在配置目录中添加一个 package.json，列出所需的依赖项。

json{
  "dependencies": {
    "shescape": "^2.1.0"
  }
}

DevEco Code 会在启动时运行 bun install 来安装这些依赖项。之后你的插件和工具就可以导入它们了。

tsimport { escape } from "shescape"

export const MyPlugin = async (ctx) => {
  return {
    "tool.execute.before": async (input, output) => {
      if (input.tool === "bash") {
        output.args.command = escape(output.args.command)
      }
    },
  }
}

基本结构

jsexport const MyPlugin = async ({ project, client, $, directory, worktree }) => {
  console.log("Plugin initialized!")

  return {
    // Hook implementations go here
  }
}

插件函数接收以下参数：

• project：当前项目信息。
• directory：当前工作目录。
• worktree：git 工作树路径。
• client：用于与 AI 交互的 DevEco Code SDK 客户端。
• $：Bun 的 Shell API，用于执行命令。

TypeScript 支持

对于 TypeScript 插件，你可以从插件包中导入类型：

tsimport type { Plugin } from "@deveco/deveco-code-plugin"

export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree }) => {
  return {
    // Type-safe hook implementations
  }
}

事件

插件可以订阅事件，如下方示例部分所示。以下是所有可用事件的列表。

命令事件

• command.executed

文件事件

• file.edited
• file.watcher.updated

安装事件

• installation.updated

LSP 事件

• lsp.client.diagnostics
• lsp.updated

消息事件

• message.part.removed
• message.part.updated
• message.removed
• message.updated

权限事件

• permission.asked
• permission.replied

服务器事件

• server.connected

会话事件

• session.created
• session.compacted
• session.deleted
• session.diff
• session.error
• session.idle
• session.status
• session.updated

待办事项事件

• todo.updated

Shell 事件

• shell.env

工具事件

• tool.execute.after
• tool.execute.before

TUI 事件

• tui.prompt.append
• tui.command.execute
• tui.toast.show

示例

以下是一些可用于扩展 DevEco Code 的插件示例。

发送通知

在特定事件发生时发送通知：

jsexport const NotificationPlugin = async ({ project, client, $, directory, worktree }) => {
  return {
    event: async ({ event }) => {
      // Send notification on session completion
      if (event.type === "session.idle") {
        await $`osascript -e 'display notification "Session completed!" with title "deveco"'`
      }
    },
  }
}

这里使用 osascript 在 macOS 上运行 AppleScript 来发送通知。

.env 保护

阻止 DevEco Code 读取 .env 文件：

javascriptexport const EnvProtection = async ({ project, client, $, directory, worktree }) => {
  return {
    "tool.execute.before": async (input, output) => {
      if (input.tool === "read" && output.args.filePath.includes(".env")) {
        throw new Error("Do not read .env files")
      }
    },
  }
}

注入环境变量

将环境变量注入所有 Shell 执行（AI 工具和用户终端）：

javascriptexport const InjectEnvPlugin = async () => {
  return {
    "shell.env": async (input, output) => {
      output.env.MY_API_KEY = "secret"
      output.env.PROJECT_ROOT = input.cwd
    },
  }
}

自定义工具

插件还可以为 DevEco Code 添加自定义工具：

tsimport { type Plugin, tool } from "@deveco/deveco-code-plugin"

export const CustomToolsPlugin: Plugin = async (ctx) => {
  return {
    tool: {
      mytool: tool({
        description: "This is a custom tool",
        args: {
          foo: tool.schema.string(),
        },
        async execute(args, context) {
          const { directory, worktree } = context
          return `Hello ${args.foo} from ${directory} (worktree: ${worktree})`
        },
      }),
    },
  }
}

tool 辅助函数用于创建 DevEco Code 可调用的自定义工具。它接受一个 Zod schema 函数，并返回一个工具定义，包含：

• description：工具的功能描述
• args：工具参数的 Zod schema
• execute：工具被调用时执行的函数

你的自定义工具将与内置工具一起在 DevEco Code 中可用。

日志记录

使用 client.app.log() 代替 console.log 进行结构化日志记录：

tsexport const MyPlugin = async ({ client }) => {
  await client.app.log({
    body: {
      service: "my-plugin",
      level: "info",
      message: "Plugin initialized",
      extra: { foo: "bar" },
    },
  })
}

日志级别：debug、info、warn、error。详情请参阅 SDK 文档。

压缩钩子

自定义会话压缩时包含的上下文：

tsimport type { Plugin } from "@deveco/deveco-code-plugin"

export const CompactionPlugin: Plugin = async (ctx) => {
  return {
    "experimental.session.compacting": async (input, output) => {
      // Inject additional context into the compaction prompt
      output.context.push(`
## Custom Context

Include any state that should persist across compaction:
- Current task status
- Important decisions made
- Files being actively worked on
`)
    },
  }
}

experimental.session.compacting 钩子在 LLM 生成续接摘要之前触发。使用它来注入默认压缩提示词可能遗漏的领域特定上下文。

你还可以通过设置 output.prompt 来完全替换压缩提示词：

tsimport type { Plugin } from "@deveco/deveco-code-plugin"

export const CustomCompactionPlugin: Plugin = async (ctx) => {
  return {
    "experimental.session.compacting": async (input, output) => {
      // Replace the entire compaction prompt
      output.prompt = `
You are generating a continuation prompt for a multi-agent swarm session.

Summarize:
1. The current task and its status
2. Which files are being modified and by whom
3. Any blockers or dependencies between agents
4. The next steps to complete the work

Format as a structured prompt that a new agent can use to resume work.
`
    },
  }
}

当设置了 output.prompt 时，它会完全替换默认的压缩提示词。在这种情况下，output.context 数组将被忽略。

自定义工具是你创建的函数，LLM 可以在对话过程中调用它们。它们与 deveco 的内置工具（如 read、write 和 bash）协同工作。

创建工具

工具以 TypeScript 或 JavaScript 文件的形式定义。不过，工具定义可以调用任何语言编写的脚本——TypeScript 或 JavaScript 仅用于工具定义本身。

位置

工具可以在以下位置定义：

• 本地定义：将工具文件放在项目的 .deveco/tools/ 目录中。
• 全局定义：将工具文件放在 ~/.config/deveco/tools/ 中。

结构

创建工具最简单的方式是使用 tool() 辅助函数，它提供类型安全和参数校验。

tsimport { tool } from "@deveco/deveco-code-plugin"

export default tool({
  description: "Query the project database",
  args: {
    query: tool.schema.string().describe("SQL query to execute"),
  },
  async execute(args) {
    // Your database logic here
    return `Executed query: ${args.query}`
  },
})

文件名即为工具名称。上面的示例创建了一个名为 database 的工具。

单文件多工具

你也可以从单个文件中导出多个工具。每个导出都会成为一个独立的工具，命名格式为 <filename>_<exportname>：

tsimport { tool } from "@deveco/deveco-code-plugin"

export const add = tool({
  description: "Add two numbers",
  args: {
    a: tool.schema.number().describe("First number"),
    b: tool.schema.number().describe("Second number"),
  },
  async execute(args) {
    return args.a + args.b
  },
})

export const multiply = tool({
  description: "Multiply two numbers",
  args: {
    a: tool.schema.number().describe("First number"),
    b: tool.schema.number().describe("Second number"),
  },
  async execute(args) {
    return args.a * args.b
  },
})

这会创建两个工具：math_add 和 math_multiply。

与内置工具的名称冲突

自定义工具通过工具名称进行索引。如果自定义工具使用了与内置工具相同的名称，则优先使用自定义工具。

例如，这个文件取代了内置的bash工具：

tsimport { tool } from "@deveco/deveco-code-plugin"

export default tool({
  description: "Restricted bash wrapper",
  args: {
    command: tool.schema.string(),
  },
  async execute(args) {
    return `blocked: ${args.command}`
  },
})

参数

你可以使用 tool.schema（即 Zod）来定义参数类型。

tsargs: {
  query: tool.schema.string().describe("SQL query to execute")
}

你也可以直接导入 Zod 并返回一个普通对象：

tsimport { z } from "zod"

export default {
  description: "Tool description",
  args: {
    param: z.string().describe("Parameter description"),
  },
  async execute(args, context) {
    // Tool implementation
    return "result"
  },
}

上下文

工具会接收当前会话的上下文信息：

tsimport { tool } from "@deveco/deveco-code-plugin"

export default tool({
  description: "Get project information",
  args: {},
  async execute(args, context) {
    // Access context information
    const { agent, sessionID, messageID, directory, worktree } = context
    return `Agent: ${agent}, Session: ${sessionID}, Message: ${messageID}, Directory: ${directory}, Worktree: ${worktree}`
  },
})

使用 context.directory 获取会话的工作目录。
使用 context.worktree 获取 git worktree 根目录。

示例

用 Python 编写工具

你可以使用任何语言编写工具。以下示例展示了如何用 Python 实现两数相加。

首先，创建一个 Python 脚本作为工具：

pythonimport sys

a = int(sys.argv[1])
b = int(sys.argv[2])
print(a + b)

然后创建调用该脚本的工具定义：

tsimport { tool } from "@deveco/deveco-code-plugin"
import path from "path"

export default tool({
  description: "Add two numbers using Python",
  args: {
    a: tool.schema.number().describe("First number"),
    b: tool.schema.number().describe("Second number"),
  },
  async execute(args, context) {
    const script = path.join(context.worktree, ".deveco/tools/add.py")
    const result = await Bun.$`python3 ${script} ${args.a} ${args.b}`.text()
    return result.trim()
  },
})

这里我们使用 Bun.$ 工具函数来运行 Python 脚本。

工具允许 LLM 在您的代码库中执行操作。DevEco Code 自带一组内置工具，您也可以通过自定义工具或 MCP 服务器来扩展它。

默认情况下，所有工具都是启用的，且无需权限即可运行。您可以通过权限来控制工具的行为。

配置

使用 permission 字段来控制工具行为。您可以对每个工具设置允许、拒绝或需要审批。

json{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny",
    "bash": "ask",
    "webfetch": "allow"
  }
}

您还可以使用通配符同时控制多个工具。例如，要求某个 MCP 服务器的所有工具都需要审批：

json{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "mymcp_*": "ask"
  }
}

了解更多关于配置权限的内容。

内置工具

以下是 DevEco Code 中所有可用的内置工具。

bash

在项目环境中执行 shell 命令。

json{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "bash": "allow"
  }
}

该工具允许 LLM 运行终端命令，例如 npm install、git status 或其他任何 shell 命令。

edit

通过精确的字符串替换来修改现有文件。

json{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "allow"
  }
}

该工具通过替换精确匹配的文本来对文件进行编辑。这是 LLM 修改代码的主要方式。

write

创建新文件或覆盖现有文件。

json{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "allow"
  }
}

使用此工具允许 LLM 创建新文件。如果文件已存在，则会覆盖现有文件。

read

读取代码库中的文件内容。

json{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "read": "allow"
  }
}

该工具读取文件并返回其内容。它支持对大文件读取指定行范围。

grep

使用正则表达式搜索文件内容。

json{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "grep": "allow"
  }
}

在代码库中快速搜索内容。支持完整的正则表达式语法和文件模式过滤。

glob

通过模式匹配查找文件。

json{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "glob": "allow"
  }
}

使用 **/*.js 或 src/**/*.ts 等 glob 模式搜索文件。返回按修改时间排序的匹配文件路径。

lsp（实验性）

与已配置的 LSP 服务器交互，获取代码智能功能，如定义跳转、引用查找、悬停信息和调用层次结构。

json{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "lsp": "allow"
  }
}

支持的操作包括 goToDefinition、findReferences、hover、documentSymbol、workspaceSymbol、goToImplementation、prepareCallHierarchy、incomingCalls 和 outgoingCalls。

patch

对文件应用补丁。

json{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "allow"
  }
}

该工具将补丁文件应用到您的代码库中。适用于应用来自各种来源的 diff 和补丁。

skill

加载一个技能（即 SKILL.md 文件）并在对话中返回其内容。

json{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "skill": "allow"
  }
}

todowrite

在编码会话中管理待办事项列表。

json{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "todowrite": "allow"
  }
}

创建和更新任务列表以跟踪复杂操作的进度。LLM 使用此工具来组织多步骤任务。

webfetch

获取网页内容。

json{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "webfetch": "allow"
  }
}

允许 LLM 获取并读取网页内容。适用于查阅文档或研究在线资源。

websearch

在网络上搜索信息。

DEVECO_ENABLE_EXA=1 deveco

json{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "websearch": "allow"
  }
}

使用 Exa AI 进行网络搜索以查找相关信息。适用于研究主题、了解时事动态或获取超出训练数据截止日期的信息。

无需 API 密钥——该工具无需身份验证即可直接连接到 Exa AI 的托管 MCP 服务。

question

在执行过程中向用户提问。

json{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "question": "allow"
  }
}

该工具允许 LLM 在执行任务期间向用户提问。适用于以下场景：

• 收集用户偏好或需求
• 澄清模糊的指令
• 获取实现方案的决策
• 提供方向选择的选项

每个问题包含标题、问题正文和选项列表。用户可以从提供的选项中选择，也可以输入自定义答案。当有多个问题时，用户可以在提交所有答案之前在各问题之间切换浏览。

自定义工具

自定义工具允许您定义 LLM 可以调用的自定义函数。这些函数在您的配置文件中定义，可以执行任意代码。

了解更多关于创建自定义工具的内容。

MCP 服务器

MCP（Model Context Protocol）服务器允许您集成外部工具和服务，包括数据库访问、API 集成和第三方服务。

了解更多关于配置 MCP 服务器的内容。

内部机制

在内部，grep 和 glob 等工具底层使用 ripgrep。默认情况下，ripgrep 遵循 .gitignore 中的模式，这意味着 .gitignore 中列出的文件和目录将被排除在搜索和列表结果之外。

忽略模式

要包含通常会被忽略的文件，请在项目根目录下创建一个 .ignore 文件。该文件可以显式允许某些路径。

text!node_modules/
!dist/
!build/

例如，这个 .ignore 文件允许 ripgrep 在 node_modules/、dist/ 和 build/ 目录中进行搜索，即使它们已在 .gitignore 中列出。

您可以通过创建 AGENTS.md 文件来为 deveco 提供自定义指令。这类似于 Cursor 的规则功能。该文件包含的指令会被纳入 LLM 的上下文中，以便针对您的特定项目自定义其行为。

初始化

要创建新的 AGENTS.md 文件，您可以在 deveco 中运行 /init 命令。

该命令会扫描您的项目及其所有内容，了解项目的用途，并据此生成一个 AGENTS.md 文件。这有助于 deveco 更好地导航您的项目。

如果您已有 AGENTS.md 文件，该命令会尝试在其基础上进行补充。

示例

您也可以手动创建此文件。以下是一些可以放入 AGENTS.md 文件中的内容示例。

markdown# SST v3 Monorepo Project

This is an SST v3 monorepo with TypeScript. The project uses bun workspaces for package management.

## Project Structure

- `packages/` - Contains all workspace packages (functions, core, web, etc.)
- `infra/` - Infrastructure definitions split by service (storage.ts, api.ts, web.ts)
- `sst.config.ts` - Main SST configuration with dynamic imports

## Code Standards

- Use TypeScript with strict mode enabled
- Shared code goes in `packages/core/` with proper exports configuration
- Functions go in `packages/functions/`
- Infrastructure should be split into logical files in `infra/`

## Monorepo Conventions

- Import shared modules using workspace names: `@my-app/core/example`

我们在这里添加了项目特定的指令，这些指令会在您的团队中共享。

类型

deveco 还支持从多个位置读取 AGENTS.md 文件，不同的位置有不同的用途。

项目级

在项目根目录放置一个 AGENTS.md 文件，用于定义项目特定的规则。这些规则仅在您在该目录或其子目录中工作时生效。

全局级

您还可以在 ~/.config/deveco/AGENTS.md 文件中设置全局规则。这些规则会应用于所有 deveco 会话。

由于该文件不会被提交到 Git 或与团队共享，我们建议用它来指定 LLM 应遵循的个人规则。

Claude Code 兼容性

对于从 Claude Code 迁移过来的用户，DevEco Code 支持 Claude Code 的文件约定作为回退方案：

• 项目规则：项目目录中的 CLAUDE.md（在没有 AGENTS.md 的情况下使用）
• 全局规则：~/.claude/CLAUDE.md（在没有 ~/.config/deveco/AGENTS.md 的情况下使用）
• 技能：~/.claude/skills/ — 详情请参阅代理技能

要禁用 Claude Code 兼容性，请设置以下环境变量之一：

bashexport DEVECO_DISABLE_CLAUDE_CODE=1        # Disable all .claude support
export DEVECO_DISABLE_CLAUDE_CODE_PROMPT=1 # Disable only ~/.claude/CLAUDE.md
export DEVECO_DISABLE_CLAUDE_CODE_SKILLS=1 # Disable only .claude/skills

优先级

当 deveco 启动时，它会按以下顺序查找规则文件：

1. 本地文件，从当前目录向上遍历（AGENTS.md、CLAUDE.md）
2. 全局文件，位于 ~/.config/deveco/AGENTS.md
3. Claude Code 文件，位于 ~/.claude/CLAUDE.md（除非已禁用）

在每个类别中，第一个匹配的文件优先。例如，如果您同时拥有 AGENTS.md 和 CLAUDE.md，则只会使用 AGENTS.md。同样，~/.config/deveco/AGENTS.md 优先于 ~/.claude/CLAUDE.md。

自定义指令

您可以在 deveco.json 或全局配置文件 ~/.config/deveco/deveco.json 中指定自定义指令文件。这允许您和团队复用现有规则，而无需将它们复制到 AGENTS.md 中。

示例：

json{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}

您还可以使用远程 URL 从网络加载指令。

json{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"]
}

远程指令的获取超时时间为 5 秒。

所有指令文件都会与您的 AGENTS.md 文件合并。

引用外部文件

虽然 deveco 不会自动解析 AGENTS.md 中的文件引用，但您可以通过以下两种方式实现类似的功能：

使用 deveco.json

推荐的方式是使用 deveco.json 中的 instructions 字段：

json{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["docs/development-standards.md", "test/testing-guidelines.md", "packages/*/AGENTS.md"]
}

在 AGENTS.md 中手动指定

您可以在 AGENTS.md 中提供明确的指令，教 deveco 读取外部文件。以下是一个实际示例：

markdown# TypeScript Project Rules

## External File Loading

CRITICAL: When you encounter a file reference (e.g., @rules/general.md), use your Read tool to load it on a need-to-know basis. They're relevant to the SPECIFIC task at hand.

Instructions:

- Do NOT preemptively load all references - use lazy loading based on actual need
- When loaded, treat content as mandatory instructions that override defaults
- Follow references recursively when needed

## Development Guidelines

For TypeScript code style and best practices: @docs/typescript-guidelines.md
For React component architecture and hooks patterns: @docs/react-patterns.md
For REST API design and error handling: @docs/api-standards.md
For testing strategies and coverage requirements: @test/testing-guidelines.md

## General Guidelines

Read the following file immediately as it's relevant to all workflows: @rules/general-guidelines.md.

这种方式允许您：

• 创建模块化、可复用的规则文件
• 通过符号链接或 Git 子模块在项目之间共享规则
• 保持 AGENTS.md 简洁，同时引用详细的指南
• 确保 deveco 仅在特定任务需要时才加载文件

代理是专门的 AI 助手，可以针对特定任务和工作流程进行配置。它们允许您创建具有自定义提示词、模型和工具访问权限的专用工具。

您可以在会话期间切换代理，或使用 @ 提及来调用它们。

类型

DevEco Code 中有两种类型的代理：主代理和子代理。

主代理

主代理是您直接交互的主要助手。您可以使用 Tab 键或配置的 switch_agent 快捷键来循环切换它们。这些代理处理您的主要对话。工具访问通过权限进行配置——例如，Build 启用了所有工具，而 Plan 则受到限制。

DevEco Code 内置了三个主代理：Build、Goal 和 Plan。我们将在下面介绍它们。

子代理

子代理是主代理可以调用来执行特定任务的专业助手。您也可以通过在消息中 @ 提及它们来手动调用。

DevEco Code 内置了两个子代理：General 和 Explore。我们将在下面介绍它们。

内置代理

DevEco Code 内置了三个主代理和两个子代理，以及若干隐藏的系统代理。

使用 Build

模式：primary

Build 是启用了所有工具的默认主代理。这是用于需要完全访问文件操作和系统命令的开发工作的标准代理。

使用 Goal

模式：primary

一个多轮目标驱动代理，遵循 5 阶段 SDD（规范驱动开发）工作流：需求分析 → 架构设计 → 任务分解 → 实现 → 验证。每个阶段完成后需经用户确认才能进入下一阶段，确保高质量的工程产出。实现阶段委托给 spec-implementation 子代理，验证阶段委托给 spec-verify 子代理。

使用 Plan

模式：primary

一个专为规划和分析设计的受限代理。我们使用权限系统来为您提供更多控制权，并防止意外更改。
默认情况下，以下所有项均设置为 ask：

• file edits：所有写入、补丁和编辑
• bash：所有 bash 命令

当您希望 LLM 分析代码、建议更改或创建计划，而不对代码库进行任何实际修改时，此代理非常有用。

使用 General

模式：subagent

一个用于研究复杂问题和执行多步骤任务的通用代理。拥有完整的工具访问权限（todo 除外），因此可以在需要时修改文件。可用于并行运行多个工作单元。

使用 Explore

模式：subagent

一个用于探索代码库的快速只读代理。无法修改文件。当您需要按模式快速查找文件、搜索代码中的关键字或回答有关代码库的问题时，请使用此代理。

使用 Compaction

模式：primary

隐藏的系统代理，将长上下文压缩为较小的摘要。它会在需要时自动运行，且无法在 UI 中选择。

使用 Title

模式：primary

隐藏的系统代理，用于生成简短的会话标题。它会自动运行，且无法在 UI 中选择。

使用 Summary

模式：primary

隐藏的系统代理，用于创建会话摘要。它会自动运行，且无法在 UI 中选择。

使用 Spec-Implementation

模式：subagent

隐藏的子代理，由 Goal 代理在第 4 阶段自动调用。它根据已审批的规范文档执行实现任务（环境搭建 → 基础功能 → 用户故事 → 最终打磨），并返回实现报告。

使用 Spec-Verify

模式：subagent

隐藏的子代理，由 Goal 代理在第 5 阶段自动调用。它负责构建、部署和 UI 验证，支持两种验证范围：仅构建验证（build-only）和构建 + UI 验证（build+ui），并返回结构化的验证报告。

用法

1. 对于主代理，在会话期间使用 Tab 键循环切换。您也可以使用配置的 switch_agent 快捷键。
2. 子代理可以通过以下方式调用：
3. 由主代理根据其描述自动调用以执行专门任务。
4. 通过在消息中 @ 提及子代理来手动调用。例如：

txt@general help me search for this function

1. 会话间导航：当子代理创建自己的子会话时，您可以使用以下方式在父会话和所有子会话之间导航：
2. <Leader>+Right（或配置的 session_child_cycle 快捷键）向前循环：父会话 → 子会话1 → 子会话2 → ... → 父会话
3. <Leader>+Left（或配置的 session_child_cycle_reverse 快捷键）向后循环：父会话 ← 子会话1 ← 子会话2 ← ... ← 父会话

这使您可以在主对话和专门的子代理工作之间无缝切换。

配置

您可以自定义内置代理或通过配置创建自己的代理。代理可以通过两种方式进行配置：

JSON

在 deveco.json 配置文件中配置代理：

json{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "mode": "primary",
      "model": "deveco/glm-5.1",
      "prompt": "{file:./prompts/build.txt}",
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "plan": {
      "mode": "primary",
      "model": "deveco/glm-5.1",
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    },
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "mode": "subagent",
      "model": "deveco/glm-5.1",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

Markdown

您还可以使用 Markdown 文件定义代理。将它们放在：

• 全局：~/.config/deveco/agents/
• 项目级：.deveco/agents/

markdown---
description: Reviews code for quality and best practices
mode: subagent
model: deveco/glm-5.1
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---

You are in code review mode. Focus on:

- Code quality and best practices
- Potential bugs and edge cases
- Performance implications
- Security considerations

Provide constructive feedback without making direct changes.

Markdown 文件名即为代理名称。例如，review.md 会创建一个名为 review 的代理。

选项

让我们详细了解这些配置选项。

描述

使用 description 选项提供代理的功能及使用场景的简要描述。

json{
  "agent": {
    "review": {
      "description": "Reviews code for best practices and potential issues"
    }
  }
}

这是一个必需的配置选项。

温度

使用 temperature 配置控制 LLM 响应的随机性和创造力。

较低的值使响应更加集中和确定，而较高的值则增加创造力和多样性。

json{
  "agent": {
    "plan": {
      "temperature": 0.1
    },
    "creative": {
      "temperature": 0.8
    }
  }
}

温度值通常范围为 0.0 到 1.0：

• 0.0-0.2：非常集中和确定性的响应，适合代码分析和规划
• 0.3-0.5：平衡的响应，兼顾一定创造力，适合一般开发任务
• 0.6-1.0：更有创造力和多样性的响应，适合头脑风暴和探索

json{
  "agent": {
    "analyze": {
      "temperature": 0.1,
      "prompt": "{file:./prompts/analysis.txt}"
    },
    "build": {
      "temperature": 0.3
    },
    "brainstorm": {
      "temperature": 0.7,
      "prompt": "{file:./prompts/creative.txt}"
    }
  }
}

如果未指定温度，DevEco Code 将使用模型特定的默认值；大多数模型通常为 0，Qwen 模型为 0.55。

最大步数

控制代理在被强制以纯文本响应之前可以执行的最大代理迭代次数。这允许希望控制成本的用户对代理操作设置限制。

如果未设置此选项，代理将持续迭代，直到模型选择停止或用户中断会话。

json{
  "agent": {
    "quick-thinker": {
      "description": "Fast reasoning with limited iterations",
      "prompt": "You are a quick thinker. Solve problems with minimal steps.",
      "steps": 5
    }
  }
}

当达到限制时，代理会收到一个特殊的系统提示词，指示其回复工作摘要和建议的剩余任务。

禁用

设置为 true 以禁用代理。

json{
  "agent": {
    "review": {
      "disable": true
    }
  }
}

提示词

使用 prompt 配置为代理指定自定义系统提示词文件。提示词文件应包含针对代理用途的具体指令。

json{
  "agent": {
    "review": {
      "prompt": "{file:./prompts/code-review.txt}"
    }
  }
}

此路径相对于配置文件所在位置。因此它同时适用于全局 DevEco Code 配置和项目级配置。

模型

使用 model 配置为代理覆盖模型。适用于针对不同任务使用不同的优化模型。例如，用更快的模型进行规划，用更强大的模型进行实现。

json{
  "agent": {
    "plan": {
      "model": "deveco/glm-5.1"
    }
  }
}

DevEco Code 配置中的模型 ID 使用 provider/model-id 格式。例如，deveco/glm-5.1。

工具

使用 tools 配置控制代理中可用的工具。您可以通过将特定工具设置为 true 或 false 来启用或禁用它们。

json{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": true,
    "bash": true
  },
  "agent": {
    "plan": {
      "tools": {
        "write": false,
        "bash": false
      }
    }
  }
}

您还可以使用通配符同时控制多个工具。例如，要禁用 MCP 服务器中的所有工具：

json{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "readonly": {
      "tools": {
        "mymcp_*": false,
        "write": false,
        "edit": false
      }
    }
  }
}

了解更多关于工具的信息。

权限

您可以配置权限来管理代理可以执行的操作。目前，edit、bash 和 webfetch 工具的权限可以配置为：

• "ask" — 运行工具前提示审批
• "allow" — 允许所有操作，无需审批
• "deny" — 禁用该工具

json{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  }
}

您可以按代理覆盖这些权限。

json{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  },
  "agent": {
    "build": {
      "permission": {
        "edit": "ask"
      }
    }
  }
}

您还可以在 Markdown 代理中设置权限。

markdown---
description: Code review without edits
mode: subagent
permission:
  edit: deny
  bash:
    "*": ask
    "git diff": allow
    "git log*": allow
    "grep *": allow
  webfetch: deny
---

Only analyze code and suggest changes.

您可以为特定的 bash 命令设置权限。

json{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git push": "ask",
          "grep *": "allow"
        }
      }
    }
  }
}

这可以使用 glob 模式。

json{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git *": "ask"
        }
      }
    }
  }
}

您还可以使用 * 通配符来管理所有命令的权限。
由于最后匹配的规则优先，请将 * 通配符放在前面，将具体规则放在后面。

json{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "ask",
          "git status *": "allow"
        }
      }
    }
  }
}

了解更多关于权限的信息。

模式

使用 mode 配置控制代理的模式。mode 选项用于确定代理的使用方式。

json{
  "agent": {
    "review": {
      "mode": "subagent"
    }
  }
}

mode 选项可以设置为 primary、subagent 或 all。如果未指定 mode，则默认为 all。

隐藏

使用 hidden: true 将子代理从 @ 自动补全菜单中隐藏。适用于只应由其他代理通过 Task 工具以编程方式调用的内部子代理。

json{
  "agent": {
    "internal-helper": {
      "mode": "subagent",
      "hidden": true
    }
  }
}

这仅影响自动补全菜单中的用户可见性。如果权限允许，模型仍然可以通过 Task 工具调用隐藏的代理。

任务权限

使用 permission.task 控制代理可以通过 Task 工具调用哪些子代理。使用 glob 模式进行灵活匹配。

json{
  "agent": {
    "orchestrator": {
      "mode": "primary",
      "permission": {
        "task": {
          "*": "deny",
          "orchestrator-*": "allow",
          "code-reviewer": "ask"
        }
      }
    }
  }
}

当设置为 deny 时，子代理将从 Task 工具描述中完全移除，因此模型不会尝试调用它。

颜色

使用 color 选项自定义代理在 UI 中的视觉外观。这会影响代理在界面中的显示方式。

使用有效的十六进制颜色（例如 #FF5733）或主题颜色：primary、secondary、accent、success、warning、error、info。

json{
  "agent": {
    "creative": {
      "color": "#ff6b6b"
    },
    "code-reviewer": {
      "color": "accent"
    }
  }
}

Top P

使用 top_p 选项控制响应多样性。这是控制随机性的温度替代方案。

json{
  "agent": {
    "brainstorm": {
      "top_p": 0.9
    }
  }
}

值范围从 0.0 到 1.0。较低的值更加集中，较高的值更加多样化。

其他选项

您在代理配置中指定的任何其他选项都将作为模型选项直接传递给提供商。这允许您使用提供商特定的功能和参数。

例如，使用 OpenAI 的推理模型时，您可以控制推理力度：

json{
  "agent": {
    "deep-thinker": {
      "description": "Agent that uses high reasoning effort for complex problems",
      "model": "openai/gpt-5",
      "reasoningEffort": "high",
      "textVerbosity": "low"
    }
  }
}

这些附加选项是模型和提供商特定的。请查阅您的提供商文档以获取可用参数。

创建代理

您可以使用以下命令创建新代理：

bashdeveco agent create

此交互式命令将：

1. 询问代理的保存位置——全局或项目级。
2. 描述代理应该做什么。
3. 生成合适的系统提示词和标识符。
4. 让您选择代理可以访问哪些工具。
5. 最后，创建一个包含代理配置的 Markdown 文件。

使用场景

以下是不同代理的一些常见使用场景。

• Build 代理：启用所有工具的完整开发工作
• Goal 代理：规范驱动的多阶段目标开发，从需求到验证的全流程管控
• Plan 代理：分析和规划，不进行任何更改
• Review 代理：具有只读访问权限和文档工具的代码审查
• Debug 代理：专注于问题排查，启用 bash 和读取工具
• Docs 代理：文档编写，具有文件操作但不使用系统命令

示例

以下是一些您可能会觉得有用的示例代理。

文档代理

markdown---
description: Writes and maintains project documentation
mode: subagent
tools:
  bash: false
---

You are a technical writer. Create clear, comprehensive documentation.

Focus on:

- Clear explanations
- Proper structure
- Code examples
- User-friendly language

安全审计代理

markdown---
description: Performs security audits and identifies vulnerabilities
mode: subagent
tools:
  write: false
  edit: false
---

You are a security expert. Focus on identifying potential security issues.

Look for:

- Input validation vulnerabilities
- Authentication and authorization flaws
- Data exposure risks
- Dependency vulnerabilities
- Configuration security issues

要调试 DevEco Code 的问题，请先检查其存储在磁盘上的日志和本地数据。

日志

日志文件写入位置：

• macOS: ~/.local/share/deveco/log/
• Windows: 按 WIN+R 并粘贴 %USERPROFILE%\.local\share\deveco\log

日志文件以时间戳命名（例如 2025-01-09T123456.log），并保留最近的 10 个日志文件。

你可以通过 --log-level 命令行选项设置日志级别以获取更详细的调试信息。例如：deveco --log-level DEBUG。

存储

DevEco Code 将会话数据和其他应用数据存储在磁盘上：

• macOS: ~/.local/share/deveco/
• Windows: 按 WIN+R 并粘贴 %USERPROFILE%\.local\share\deveco

该目录包含：

• auth.json - 身份验证数据，如 API 密钥、OAuth Token
• log/ - 应用日志
• project/ - 项目特定数据，如会话和消息数据
• 如果项目位于 Git 仓库中，则存储在 ./<project-slug>/storage/
• 如果不是 Git 仓库，则存储在 ./global/storage/

获取帮助

如果你遇到 DevEco Code 的问题：

1. 在 GitCode 上报告问题

报告 Bug 或请求功能的最佳方式是通过我们的 GitCode 仓库：

gitcode.com/openharmony-sig/deveco-code/issues

在创建新 Issue 之前，请先搜索已有的 Issue，看看你的问题是否已被报告。

1. 加入我们的 Discord

如需实时帮助和社区讨论，请加入我们的 Discord 服务器：

opencode.ai/discord

常见问题

以下是一些常见问题及其解决方法。

DevEco Code 无法启动

1. 检查日志中的错误消息
2. 尝试使用 --print-logs 运行以在终端中查看输出
3. 使用 deveco upgrade 确保你使用的是最新版本

身份验证问题

1. 尝试在 TUI 中使用 /connect 命令重新进行身份验证
2. 检查你的 API 密钥是否有效
3. 确保你的网络允许连接到提供商的 API

模型不可用

1. 检查你是否已通过提供商的身份验证
2. 验证配置中的模型名称是否正确
3. 某些模型可能需要特定的访问权限或订阅

如果你遇到 ProviderModelNotFoundError，很可能是在某处错误地引用了模型。
模型应按如下方式引用：<providerId>/<modelId>

示例：

• openai/gpt-4.1
• openrouter/google/gemini-2.5-flash
• deveco/kimi-k2

要查看你有权访问哪些模型，请运行 deveco models

ProviderInitError

如果你遇到 ProviderInitError，很可能是配置无效或已损坏。

要解决此问题：

1. 首先，按照提供商指南验证你的提供商是否已正确设置
2. 如果问题仍然存在，请尝试清除已存储的配置：

bashrm -rf ~/.local/share/deveco

在 Windows 上，按 WIN+R 并删除：%USERPROFILE%\.local\share\deveco

1. 在 TUI 中使用 /connect 命令重新与提供商进行身份验证。

AI_APICallError 和提供商包问题

如果你遇到 API 调用错误，可能是由于提供商包过期导致的。DevEco Code 会根据需要动态安装提供商包（OpenAI、Anthropic、Google 等）并将它们缓存到本地。

要解决提供商包问题：

1. 清除提供商包缓存：

bashrm -rf ~/.cache/deveco

在 Windows 上，按 WIN+R 并删除：%USERPROFILE%\.cache\deveco

1. 重新启动 DevEco Code 以重新安装最新的提供商包

这将强制 DevEco Code 下载最新版本的提供商包，通常可以解决模型参数和 API 变更带来的兼容性问题。

DevEco Code 原生支持 Windows 平台，可以直接在 Windows 终端中运行，无需 WSL（Windows Subsystem for Linux）。

直接安装

在 Windows 上安装 DevEco Code 与 macOS 相同，通过 npm 安装：

bashnpm install -g @deveco/deveco-code

推荐终端

DevEco Code 在以下 Windows 终端中运行良好：

• PowerShell 7+（推荐）
• Windows PowerShell 5.1+
• Windows Terminal（推荐，支持多标签页和自定义主题）
• Command Prompt（基本支持）

HarmonyOS 开发环境

如果你需要进行 HarmonyOS 应用开发（编译构建、模拟器运行、真机调试），还需要：

1. 安装 DevEco Studio 6.1 及以上版本
2. 配置 DEVECO_HOME 环境变量，指向 DevEco Studio 安装目录：

powershell# PowerShell
$env:DEVECO_HOME = "C:\Program Files\Huawei\DevEco Studio"

或在系统环境变量中永久设置。