dify 1.16.0 升级实战：原生 Agent 沙箱、MCP 协议与 GPT-5.6 兼容配置一文看懂

1. 升级前先搞清楚：1.16.0 到底动了哪些底层

dify 1.16.0 这次升级，最容易被忽略的不是 UI 上多了个 Agent 构建器，而是它把 Agent 从「工作流里的一个节点」变成了「跑在 Linux 沙箱里的独立后端服务」。这意味着你的部署拓扑变了：以前一套 api + worker + web 就能跑，现在多了agent_backend和local_sandbox两个容器，Agent 的代码执行、文件读写、包安装全在沙箱里完成，跟主服务做了隔离。

适合谁看这篇：已经用 Docker Compose 或源码部署过 dify、现在想升到 1.16.0 的开发者。如果你还没部署过，这篇的配置片段也能当参考，但升级步骤那部分可以先跳过。

我这次升级踩的坑主要集中在三块：环境变量改名没跟上导致 Agent 起不来、GPT-5.6 的 API 类型还是旧的 Chat Completions 报错、MCP 服务端版本协商没配对。下面按「前置准备 → 可复制配置 → 验证 → 排障」的顺序拆开讲，配置片段都能直接抄。

先明确一个概念，方便后面理解：Agent 沙箱就是一个受限的 Linux 运行环境，Agent 在里面装包、跑脚本、读写文件，即使跑飞了也炸不到你的主服务。MCP 协议是模型和外部工具之间的通信标准，1.16.0 支持到 2025-06-18 版，多了版本协商和结构化输出。GPT-5.6 兼容的核心是 OpenAI 把新模型的接口从 Chat Completions 换成了 Responses，dify 新配置默认走 Responses，但老的自定义密钥还留着旧设置。

2. 前置准备：TaoToken 接入与密钥规划

升级前建议先把模型接入这条链路理顺，不然升完发现 Agent 调不通模型，排查起来会同时怀疑沙箱和密钥两头。我自己的做法是模型请求统一走一个兼容 OpenAI 协议的网关，这样 dify 里配一次 base_url 和 key，后面换模型不用改代码。

TaoToken 在这里的角色就是提供 OpenAI 兼容的调用入口，dify 的 OpenAI 插件把 API Base 指过去就能用。官网入口在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 地址是 https://taotoken.net/api ，注意这个不带 UTM 参数，配置里填的就是它。

具体到 dify 的模型供应商配置，你需要准备两样东西：一个 API Key，和上面那个 API Base。Key 在控制台生成，地址是 https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite ，生成后复制出来，dify 里粘贴时注意别带前后空格，这个坑我见过好几次，报 401 但其实是空格问题。

如果你后面要跑长期编码类 Agent，或者想让 Agent 持续调用工具链，可以了解下 Coding Plan，入口在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。模型对话调试的入口在 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite ，升级过程中想快速验证某个模型通不通，直接在这里试比在 dify 里试快得多。

接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面写了不同协议的调用方式，配 MCP 或者自定义模型时对着看。如果你用 Claude Code 这类工具做 Agent 开发，Anthropic 兼容的说明在 https://taotoken.net/claudecode-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claudecode_anthropic&utm_campaign=rewrite 。

提示：升级前先把当前能用的模型配置截图存一份，尤其是自定义供应商的 API 类型和 base_url，回滚时能省很多事。

3. 可复制配置：config.toml、settings.json 与沙箱环境变量

这一节是重点，配置抄错一个字段 Agent 就起不来。先给一个config.toml的骨架，这是源码部署时 Agent 后端读的配置，Docker 部署对应的是环境变量，逻辑一样。

# config.toml - Agent 后端服务配置骨架 [server] host = "0.0.0.0" port = 5050 secret_key = "替换成你生成的密钥" [redis] url = "redis://redis:6379/2" keepalive = true keepalive_idle = 300 [sandbox] backend = "local" home_dir = "/home/agent" landlock_enabled = true landlock_version = 1 [timeout] stream_read_seconds = 30 run_seconds = 1200

secret_key一定要换，生成命令是：

python -c 'import secrets; print(secrets.token_urlsafe(32))'

landlock_version = 1这个别改成 2，官方为了兼容更广的内核版本降到了 v1，你改高在部分内核上会直接失败。

然后是settings.json，这是 MCP 服务端的配置骨架，1.16.0 支持 2025-06-18 协议版本，关键是protocolVersion字段：

{ "mcpServers": { "my-tool-server": { "protocolVersion": "2025-06-18", "transport": "http", "url": "http://your-mcp-server:8080/mcp", "headers": { "X-Custom-Auth": "{{request.headers.X-Custom-Auth}}" }, "capabilities": { "tools": { "listChanged": true }, "structuredOutput": true } } } }

注意headers里那个占位符写法，这是 1.16.0 新增的运行时动态注入能力，{{request.headers.X-Custom-Auth}}会在每次请求时替换成调用方传进来的头，做逐请求认证透传就靠它。以前只能写死 token，现在能透传了。

沙箱相关的环境变量，Docker 部署时写进.env：

# Agent 后端 AGENT_BACKEND_BASE_URL=http://agent_backend:5050 AGENT_BACKEND_STREAM_READ_TIMEOUT_SECONDS=30 AGENT_BACKEND_RUN_TIMEOUT_SECONDS=1200 DIFY_AGENT_SERVER_SECRET_KEY=替换成生成的密钥 DIFY_AGENT_REDIS_URL=redis://redis:6379/2 # 沙箱 NEXT_PUBLIC_ENABLE_AGENT_V2=true # 工作流生成 WORKFLOW_GENERATION_TIMEOUT_MS=180000 WORKFLOW_GENERATOR_NODE_BUILDER_MAX_WORKERS=6 # Redis 保活 REDIS_KEEPALIVE=1 REDIS_KEEPALIVE_IDLE=300

这里有个必须注意的点：ENABLE_AGENT_V2这个旧变量已经被移除了，1.16.0 用的是NEXT_PUBLIC_ENABLE_AGENT_V2，而且默认就是开的。如果你.env里还留着旧的，删掉，不然可能干扰。

Docker Compose 里新增的两个服务长这样：

services: agent_backend: image: langgenius/dify-agent-backend:1.16.0 env_file: .env depends_on: - redis - db local_sandbox: image: langgenius/dify-agent-local-sandbox:1.16.0 env_file: .env

api和worker现在要依赖agent_backend，如果你维护了自定义 compose 文件，记得把depends_on补上，不然启动顺序乱了 Agent 会连不上后端。

4. 验证请求：Agent 调用与模型兼容性实测

配置写完别急着高兴，先验证。分两步：先验模型通不通，再验 Agent 能不能在沙箱里跑起来。

第一步，验证 GPT-5.6 兼容性。进 dify 的模型供应商设置，找到 OpenAI 那栏，检查 API 类型。1.16.0 新配置默认是 Responses，但如果你之前存过自定义密钥，它可能还留着 Chat Completions。手动切到 Responses，保存。

然后用 curl 直接打一下，确认网关侧没问题：

curl https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-5.6", "messages": [{"role": "user", "content": "ping"}] }'

返回里有正常的choices就说明模型链路通了。如果这里就报错，别去 dify 里找问题，先解决网关侧。

第二步，验证 Agent 沙箱。升级完执行数据库迁移：

docker compose exec api flask db upgrade

然后进 dify 控制台，新建一个 Dify Agent，基础提示词随便写个「列出当前目录文件」，保存后运行。正常的话你会看到它在沙箱里执行ls并返回结果。如果卡住不动，多半是agent_backend没起来，用这个命令看日志：

docker compose logs -f agent_backend

看到Uvicorn running on http://0.0.0.0:5050才算正常。沙箱容器也要确认：

docker compose ps | grep sandbox

第三步，验证 MCP 服务端。把工作流发布为 MCP Server，用支持 2025-06-18 的客户端连一下，看版本协商是否成功。如果客户端是旧版，dify 会向后兼容，但结构化输出能力用不了。

5. 本篇常见错排查

升级过程中我遇到和收集到的报错，按出现频率排一下。

Agent 启动后一直 pending，日志报连接拒绝。九成是AGENT_BACKEND_BASE_URL写错了。Docker 内部通信用服务名，应该是http://agent_backend:5050，不是localhost。源码部署才用localhost。

模型调用报 400，提示参数不支持。这是 GPT-5.6 走了旧 Chat Completions 接口的典型症状。去模型供应商设置把 API 类型切成 Responses。注意这个设置对已保存的自定义密钥不会自动迁移，必须手动改。

沙箱里装包失败，报权限错误。检查landlock_enabled和landlock_version。版本必须是 1，home_dir要指向沙箱内有写权限的目录。另外确认local_sandbox容器真的在跑，docker compose ps里状态是 Up 才行。

MCP 连接报协议版本不匹配。检查settings.json里的protocolVersion是不是2025-06-18。如果你连的服务端只支持旧版本，把 dify 这边的版本降下来，或者升级服务端。版本协商失败时 dify 不会自动降级到任意版本，只会兼容它支持的旧客户端。

升级后登录跳转异常。1.16.0 修了开放重定向漏洞，同时改了重定向 URL 的保留逻辑。如果你前面挂了反向代理，检查X-Forwarded-*头有没有正确传递，代理配置里proxy_set_header那几行别漏。

数据库迁移报错。先确认备份做了。9 个迁移文件涉及工作流版本、Agent 角色、文件系统重构等，如果之前手动改过表结构，可能冲突。这种情况建议在测试环境先跑一遍flask db upgrade，看具体哪个迁移失败再针对性处理。

注意：升级前务必备份 volumes 数据，尤其是 PostgreSQL 和 Redis 的卷。迁移一旦执行，回滚成本很高。

6. 升级后的收尾与后续接入

升级完成后，有几个收尾动作建议做掉。一是把.env里所有新增的 28 个变量过一遍，重点确认DIFY_AGENT_SERVER_SECRET_KEY是生产级随机值，不是默认值。二是检查NEXT_PUBLIC_ENABLE_FEATURE_PREVIEW的默认值从 false 变成了 true，如果你不想要预览功能，手动关掉。三是把ENABLE_AGENT_V2旧变量从所有配置文件里清干净。

后续如果要继续做 Agent 开发，模型接入这块建议固定用一套配置。API Key 管理在 https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite ，接入细节对着文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 配。想先试试模型对话效果，用 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite 快速验证。长期跑编码类 Agent 的话，Coding Plan 在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。

最后说个实测下来的经验：dify 1.16.0 的 Agent 沙箱在首次运行时会有一次环境初始化，比后续调用慢不少，别以为是卡死了。等第一次跑完，后面就快了。如果超过AGENT_BACKEND_RUN_TIMEOUT_SECONDS（默认 1200 秒）还没结果，那才是真出问题了，去翻agent_backend的日志找线索。