快速开始 - Dify Docs

本文档由 AI 自动翻译。如有任何不准确之处，请参考英文原版。

如果在 Dify 1.18.0 之前就用过 difyctl，服务器升级到 1.18.0 或更高版本后，旧版本将无法使用。difyctl 的命令和登录方式都已有变化，先从 Dify 1.18.0 升级指南开始。

要让编码 Agent 替你完成这些配置，把这个页面发给它即可。登录仍需你在浏览器中批准。

开始之前

使用 Dify Cloud 时，可直接开始安装。使用自部署的服务器时，先确认：

服务器为 Dify 1.18.0 或更高版本。如果是 1.17.x 或更早的版本，改为参阅该 Dify 版本对应的文档。
已将 OPENAPI_ENABLED 和 ENABLE_OAUTH_BEARER 设为 true。

安装

brew install dify 装上的是 Dify 的插件开发 CLI，而非 difyctl。

运行安装程序

macOS / Linux
Windows
手动下载

支持 x64 和 arm64 架构。

curl -fsSL https://raw.githubusercontent.com/langgenius/dify/main/cli/scripts/install-cli.sh | sh

该命令会安装最新 Dify 版本附带的 difyctl。如果自部署的服务器运行的不是最新版本，将 DIFY_VERSION 设为服务器的版本号：

curl -fsSL https://raw.githubusercontent.com/langgenius/dify/main/cli/scripts/install-cli.sh | DIFY_VERSION=1.18.0 sh

脚本会核对下载文件的校验和，再安装到 ~/.local/bin/difyctl。

支持的平台：x64。

irm https://raw.githubusercontent.com/langgenius/dify/main/cli/scripts/install.ps1 | iex

该命令会安装最新 Dify 版本附带的 difyctl。如果自部署的服务器运行的不是最新版本，先将 DIFY_VERSION 设为服务器的版本号：

# 在当前 PowerShell 会话中持续有效
$env:DIFY_VERSION = "1.18.0"
irm https://raw.githubusercontent.com/langgenius/dify/main/cli/scripts/install.ps1 | iex

脚本会核对下载文件的校验和，再安装到 %LOCALAPPDATA%\difyctl\bin\difyctl.exe。

在 Dify 的 GitHub Releases 中找到与服务器 Dify 版本匹配的发布版本，下载以下两个资源文件：
- 适用于你所用平台的二进制文件（difyctl-v<version>-<os>-<arch>）
- 校验和清单（difyctl-v<version>-checksums.txt）
计算二进制文件的 SHA-256 哈希值，并与校验和清单中对应的条目比对。如果两者不一致，说明下载的文件已损坏或遭到篡改，删除后重新下载。
shasum -a 256 difyctl-v<version>-darwin-<arch>
sha256sum difyctl-v<version>-linux-<arch>
Get-FileHash difyctl-v<version>-windows-x64.exe

将二进制文件加入 PATH：

chmod +x difyctl-v<version>-<os>-<arch>
mkdir -p ~/.local/bin
mv difyctl-v<version>-<os>-<arch> ~/.local/bin/difyctl

New-Item -ItemType Directory -Force "$env:LOCALAPPDATA\difyctl\bin" | Out-Null
Move-Item difyctl-v<version>-windows-x64.exe "$env:LOCALAPPDATA\difyctl\bin\difyctl.exe"

如需安装到其他目录或修改其他安装设置，详见配置。

验证安装

difyctl version

如果提示 command not found，说明安装目录不在你的 PATH 中。按以下方式加入：

# 添加到 ~/.zshrc 或 ~/.bashrc；直接运行只在当前会话中有效
export PATH="$HOME/.local/bin:$PATH"

[Environment]::SetEnvironmentVariable('PATH', "$env:LOCALAPPDATA\difyctl\bin;" + [Environment]::GetEnvironmentVariable('PATH', 'User'), 'User')
# 然后打开一个新的终端

如果浏览器没有自动打开（例如通过 SSH 连接时），在任意设备上打开 difyctl 打印出的 URL。本地服务器使用 http:// 或自签名证书时，加上 --insecure。此后的命令都会沿用这个选项，直到不带它重新登录为止，所以只在本地开发时使用。

在浏览器中批准

在 授权 difyctl 页面输入 difyctl 打印出的验证码，点击继续。验证码 15 分钟后过期。页面显示你的账户和工作空间时，先核对两者无误，再点击授权。difyctl 和你的编码 Agent 都会以这个账户的身份操作，这个账户能做的事，它们都能做。如果账户不对，点击取消，换成正确的账户登录 Dify，再重新发起登录。difyctl 将使用页面上显示的工作空间。要换成其他工作空间，登录后切换 difyctl 的工作空间即可。

之后要重新登录或退出登录，详见管理登录。如果登录失败，详见故障排查。

列出应用

列出你登录的工作空间中的应用，确认 difyctl 能正常使用：

difyctl get console_app

只有开启了服务 API 访问的应用才会列出。

配置编码 Agent

difyctl Skill 用来教编码 Agent 使用 difyctl。把它安装到你所用的每个编码 Agent 的 Skill 目录中：

# Claude Code
difyctl install skills ~/.claude/skills

# Codex、Cursor、Gemini CLI、GitHub Copilot、OpenCode 及大多数其他 Agent
difyctl install skills ~/.agents/skills

其他 Agent 的 Skill 目录可在各自的文档中查到。如果 Agent 没有找到这个 Skill，重启它即可。

掌控命令和密钥

不要关闭 Agent 自带的 Shell 命令审批：difyctl 执行每条命令前都不会先征求同意。Skill 会要求 Agent 先问过你，再安装集成、发布应用，或运行 help 中标为 destructive 或没有标签的命令。它是否照做，取决于 Agent 所用的 AI 模型。

想让 Agent 无需询问就能随意查看，可放行只读取服务器数据的 difyctl get、difyctl describe 和 difyctl knowledge_fs Cloud。

你在对话中输入的任何内容，包括模型供应商的 API 密钥，都会经过 Agent 所用的模型。不想让密钥经过模型，可在 Agent 用到之前自己在 Dify 中添加好，或等 Agent 索要时，告诉它你会自己添加。

自行查找命令

在 help 后面用几个词描述要做的事，它会列出匹配的命令。例如，查找发布应用的命令：

difyctl help publish app

如果想直接浏览，就运行 difyctl help。如何给命令传值、如何按结果中的提示继续操作，详见查找并运行命令。

后续步骤

以下各项都可交给编码 Agent 来做，也可自己动手：

故障排查

错误信息	处理方法
`only https:// hosts are accepted`	改用 `https://` 地址。本地服务器使用 `http://` 时，加上 `--insecure`。
`network error calling POST <server>/openapi/v1/oauth/device/code`	检查服务器地址和网络。 `difyctl` 无法校验服务器证书时，也会报这个错误。本地服务器使用自签名证书时，加上 `--insecure`。
`this Dify host does not implement the OAuth device flow`	检查服务器地址。使用 Dify Cloud 时，地址应为 `https://cloud.dify.ai`。使用自部署的服务器时，如果地址无误，确认 `OPENAPI_ENABLED` 已设为 `true`。
浏览器中：`我们这边出现了问题，请稍后重试。`	使用自部署的服务器时，确认 `ENABLE_OAUTH_BEARER` 已设为 `true`。
`authorization denied`	有人在浏览器中点击了取消。重新运行 `login`。
`code expired before authorization`	验证码在 15 分钟内未获批准。重新运行 `login`。
`OS keychain is unreachable`	加上 `--no-keyring` 重新登录，把令牌保存到文件中。

​开始之前

​安装

​登录

​列出应用

​配置编码 Agent

​掌控命令和密钥

​自行查找命令

​后续步骤

​故障排查

开始之前

安装

登录

列出应用

配置编码 Agent

掌控命令和密钥

自行查找命令

后续步骤

故障排查