同时适配 OpenCode 和 Codex CLI 的配置方法

问题 链接到标题

两个终端 AI 编码 agent 各有优势，但配置格式完全不互通。

• OpenCode：配置在 .opencode/ 目录，subagent 用 Markdown + YAML frontmatter，权限控制细粒度
• Codex CLI（OpenAI）：配置在 .codex/ 目录，custom agent 用 TOML 格式，权限模型粗粒度
• Skills 加载路径两边也不同

如果继续分别在 .opencode/skills/ 和 .codex/skills/ 各放一份，维护成本会翻倍。更新一条命令模板要改两个文件，迟早不同步。

本文记录了一个实际项目的配置方案：Skill 放共享层，Agent 放独立层，AGENTS.md 做通用索引。

全貌对比 链接到标题

先看两个工具的配置差异：

两个关键发现：

1. 两个工具都认 .agents/skills/ 作为 skills 路径——这是共用的最佳切入点
2. AGENTS.md 两边都支持——适合放中性的项目知识索引
3. Subagent 格式完全不同——没有统一的可能，各自维护

共用层：Skills 链接到标题

最核心的复用点。将 skills 从各自的专用目录迁移到共同认可的 .agents/skills/。

迁移前：skills 散落在各工具的私有目录下

.opencode/skills/aliyun-mgr/SKILL.md   ← 仅 OpenCode 发现
.codex/skills/aliyun-mgr/SKILL.md      ← 仅 Codex 发现（需手动复制）

迁移后：统一放共享目录，两边自动发现

.agents/skills/aliyun-mgr/SKILL.md     ← OpenCode ✅ Codex ✅
.agents/skills/hugo-blog/SKILL.md      ← OpenCode ✅ Codex ✅
.agents/skills/wol/SKILL.md            ← OpenCode ✅ Codex ✅

Skill 文件内容不用做任何修改，标准的 frontmatter 两边都解析：

---
name: aliyun-mgr
description: 阿里云资源管理 — 通过 aliyun CLI 管理 DNS 记录、安全组规则、查询 ECS 实例
---

前文 Skill + Subagent：用 OpenCode 替代 Terraform 做阿里云运维 中的 Skill 部分内容不需要任何调整。

独立层：Subagents / Custom Agents 链接到标题

这部分不能共用，因为两边的格式差异太大。

OpenCode Subagent 链接到标题

路径：.opencode/agents/aliyun-mgr.md

格式为 Markdown + YAML frontmatter，核心是 mode: subagent 和细粒度 permission：

---
description: 阿里云资源管理。DNS 记录增删改、安全组规则管理、ECS 实例查询。
mode: subagent
permission:
  bash:
    "aliyun *": "allow"
    "set -a*": "allow"
    "source *": "allow"
    "ssh *": "allow"
    "jq *": "allow"
  edit: deny
  write: deny
---

你是一个阿里云运维助手。
每次操作前加载凭证，操作步骤引用 skill aliyun-mgr 的命令模板。
执行完成后返回结构化结果。

关键能力：按命令模式做 allow/deny，还能按工具级别禁止 edit/write。这在 DevOps 场景中非常实用——允许跑 aliyun CLI，但绝对不允许修改项目文件。

Codex Custom Agent 链接到标题

路径：.codex/agents/aliyun-mgr.toml

格式为 TOML，核心是 sandbox_mode 和 developer_instructions：

name = "aliyun-mgr"
description = "阿里云资源管理 — 通过 aliyun CLI 管理 DNS 记录、安全组规则、查询 ECS 实例"
sandbox_mode = "workspace-write"
model_reasoning_effort = "high"

developer_instructions = """
你是一个阿里云运维助手。

每次操作前加载凭证。
操作步骤引用 skill aliyun-mgr 的命令模板。
执行完成后返回结构化结果。
"""

模型配置注意：Codex custom agent 可以设置 model 字段，但如果用桥接方式接入非 OpenAI 模型（如 DeepSeek），硬编码一个不存在的模型名会导致 subagent 创建失败，回退到主 agent 执行。解决方案是省略 model 行，让 subagent 自动继承主 session 的模型。详见后文"模型桥接"部分。

权限模型落差 链接到标题

两者的权限控制精度有显著差异：

Codex 的 sandbox_mode 只有三个级别：

• read-only：只读，不能执行命令
• workspace-write：可读写文件 + 执行命令
• danger-full-access：完全访问

这意味着在 Codex 侧无法做到"只允许特定命令，禁止编辑代码文件"这种精度。如果安全性要求高，OpenCode 是更合适的选择。

独立层：项目配置 链接到标题

OpenCode 链接到标题

opencode.json 放在 .opencode/ 目录：

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["docs/hosts.md"],
  "permission": {
    "skill": { "*": "allow" }
  }
}

instructions 预加载最基础的文件（如主机列表），其他知识由 agent 按需读取。这部分在 OpenCode 静态记忆架构从零配置指南 中有详细说明。

Codex 链接到标题

Codex 的配置分全局和项目两级。全局配置放 ~/.codex/config.toml，项目配置放 .codex/config.toml。

如果用桥接方式接 DeepSeek（通过 Moon Bridge 协议转换），配置如下：

model = "moonbridge"
model_provider = "moonbridge"
sandbox_mode = "workspace-write"

[model_providers.moonbridge]
name = "Moon Bridge"
base_url = "http://内网服务器:38440/v1"
wire_api = "responses"

[profiles.deepseek-flash]
model = "deepseek/deepseek-v4-flash"
model_provider = "moonbridge"

这里 model 不要和 subagent 中的 model 混淆。主配置的 model 是默认模型，subagent 不指定 model 时会继承这个值。Moon Bridge 的具体部署方式参见 Codex CLI 用 DeepSeek 的协议转换方案。

共享层：AGENTS.md 链接到标题

两个工具都读取项目根目录的 AGENTS.md，这是唯一一个两边格式完全一致的配置层。适合放：

• 项目结构概述
• 文档索引路由
• 通用操作规则
• 懒加载指令

例如，一个 DevOps 项目的 AGENTS.md：

# 项目名 - 日常运维

## 懒加载规则

CRITICAL: 当遇到 `docs/xxx.md` 引用时，用 Read tool 按需加载。
不预加载所有文件，根据当前任务只读需要的。

## 文档索引

- SSH 主机列表 → docs/hosts.md（已预载）
- PVE 集群节点及 GPU VM → docs/pve.md
- 数据库连接 → docs/databases.md
- 监控系统 → docs/monitoring.md

## 使用规则

- 敏感信息存 .env，使用前先 source 加载
- SSH 免密登录，直接 ssh <hostname>

注意保持中性——不要写某个工具特有的语法或指令，否则另一个工具可能误解析。

踩坑记录 链接到标题

1. Codex subagent 模型不可用 链接到标题

在 subagent TOML 中写 model = "gpt-5.5"，但当前环境通过 Moon Bridge 桥接的是 DeepSeek，服务器返回 404。Codex 会回退到用 default agent 执行，只加载 developer_instructions 作为指令。

解决：删掉 subagent 中的 model 行，让 subagent 继承主 session 的模型。

2. OpenCode skill 迁移后路径不对 链接到标题

Subagent 中硬编码引用了 skill 路径（如 .opencode/skills/aliyun-mgr/SKILL.md），技能迁移到 .agents/skills/ 后路径失效，subagent 加载不到命令模板。

解决：更新 subagent 中所有 skill 路径引用。

3. 两个工具的 AGENTS.md 语法冲突 链接到标题

OpenCode 支持 mode: subagent、permission 等 YAML frontmatter 扩展，如果写在项目 AGENTS.md 中，Codex 不识别但不会报错（忽略未知 frontmatter 字段）。但反过来，如果 Codex 未来增加 TOML 片段语法，OpenCode 可能报错。

解决：AGENTS.md 只放中性内容，不绑定任一工具的方言。

最终项目结构 链接到标题

project-root/
├── AGENTS.md                       ← 共用：文档索引 + 规则
├── .agents/skills/                 ← 共用：Skills（两边自动发现）
│   ├── aliyun-mgr/SKILL.md
│   ├── hugo-blog/SKILL.md
│   └── wol/SKILL.md
├── .opencode/
│   ├── opencode.json               ← OpenCode 独用：项目配置
│   └── agents/
│       └── aliyun-mgr.md           ← OpenCode 独用：subagent
├── .codex/
│   └── agents/
│       └── aliyun-mgr.toml         ← Codex 独用：custom agent
└── docs/
    └── *.md                        ← 共用：知识库

总结：三条原则 链接到标题

1. Skill 放共享层：.agents/skills/ 两边自动发现，一次编写两处可用
2. Agent 放独立层：各自目录 + 各自格式，不试图统一
3. AGENTS.md 放中性内容：文档索引 + 通用规则，不绑定某一工具的方言

两个工具不是二选一——OpenCode 适合需要细粒度权限控制的 DevOps 场景，Codex 在 OpenAI 模型生态和并行 subagent 方面有优势。让它们在同一个项目中共存，各自发挥所长，才是最高效的配置方式。