Skip to main content

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

Info

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

Tip

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

开始之前#

使用 Dify Cloud 时，可直接开始安装。

使用自部署的服务器时，先确认：

安装#

Info

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

运行安装程序

支持 x64 和 arm64 架构。

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

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

Tip

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

验证安装

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

登录#

发起登录

传入你在浏览器中打开 Dify 时用的地址（Dify Cloud 为 https://cloud.dify.ai）：

如果浏览器没有自动打开（例如通过 SSH 连接时），在任意设备上打开 difyctl 打印出的 URL。

本地服务器使用 http:// 或自签名证书时，加上 --insecure。此后的命令都会沿用这个选项，直到不带它重新登录为止，所以只在本地开发时使用。

在浏览器中批准

在 授权 difyctl 页面输入 difyctl 打印出的验证码，点击 继续。验证码 15 分钟后过期。

页面显示你的账户和工作空间时，先核对两者无误，再点击 授权。difyctl 和你的编码 Agent 都会以这个账户的身份操作，这个账户能做的事，它们都能做。如果账户不对，点击 取消，换成正确的账户登录 Dify，再重新发起登录。

difyctl 将使用页面上显示的工作空间。要换成其他工作空间，登录后 切换 difyctl 的工作空间 即可。

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

列出应用#

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

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

配置编码 Agent#

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

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

掌控命令和密钥#

不要关闭 Agent 自带的 Shell 命令审批：difyctl 执行每条命令前都不会先征求同意。Skill 会要求 Agent 在删除任何内容、安装集成或发布应用之前先问过你。它是否照做，取决于 Agent 所用的 AI 模型。

Tip

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

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

自行查找命令#

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

如果想直接浏览，就运行 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 重新登录，把令牌保存到文件中。