在云策Omni 里配置了自定义能力却“用起来像没加”，通常不是配置项写错一个字那么简单，而是要先判断它停在哪一步：一是启动时根本没加载这个能力；二是加载了，但绑定到了另一个模型路径或另一个作用层；三是加载正确，但被上层配置覆盖，实际生效值不是你改的那一份。按“日志、路径、最小输入、作用范围、单点改动重启”的顺序走一遍，多数情况能定位到具体一层，而不是反复改配置碰运气。

先别急着改配置内容。第一步在启动日志里确认能力名有没有出现、以什么状态出现，把“没加载”和“加载了但没生效”分开；第二步逐字符核对能力绑定的模型路径与当前生效配置是否指向同一位置，重点排除相对路径与工作目录不一致造成的静默失效；第三步用固定最小输入打一次调用，看返回里有没有该能力的标识。这三步都通过后再查配置层级是否被上层覆盖，最后只改一处并重启归因。跳过任一步，后面的判断都缺少依据。

在启动日志里确认该能力有没有被加载

这一步的目标只有一个：把“没加载”和“加载了但没生效”分成两条排查线路。前者要查注册与扫描逻辑，后者要查绑定与优先级，混在一起查会一直在错误的方向上改配置。

日志里重点看三类行：启动阶段的能力注册或扫描记录、加载完成后的清单汇总行、以及带有跳过或覆盖含义的行。关键词通常包括能力本身的名称、register、load、enabled、disabled、skip、ignored、override、duplicate。如果日志级别默认较高，加载明细可能不打印，可以先临时调低到调试级别再重启一次，仅用于这一次排查。

# 示例路径按实际部署位置替换
# 1. 按能力名找
 grep -n -i "你的能力名" ./logs/omni-start.log

# 2. 找注册与加载类记录
 grep -n -iE "register|load|enabled|disabled" ./logs/omni-start.log

# 3. 找被跳过或被覆盖的记录
 grep -n -iE "skip|ignored|override|duplicate|not found" ./logs/omni-start.log

把命中的行原样抄下来，不要只记“有一条”。记录格式建议是：时间戳、日志级别、原始行内容、你对该行的判断（已注册 / 注册后未启用 / 找不到路径 / 被同名项覆盖）。如果整份启动日志里完全搜不到该能力名，基本可以判定它没有进入加载流程，此时继续查路径和调用链意义不大，应先回到能力目录结构、文件命名和启用开关上确认。如果能搜到，就带着命中行的原文进入下一步。

核对能力绑定的模型路径与当前配置是否一致

路径写错常常不报错，而是静默跳过或落到一个空实现上，表现为“配置在、能力不在”。比对方法是逐字符对照，而不是凭肉眼觉得像。需要对照三处：配置文件里写的路径、启动日志里实际使用的路径、以及磁盘上文件的真实位置。

# 配置片段骨架，字段名按你的实际配置替换
capabilities:
  custom_demo:
    enabled: true
    entry: ./capabilities/custom_demo/main.yaml   # 相对路径示例
    # entry: /opt/omni/capabilities/custom_demo/main.yaml  # 绝对路径示例
    model: default

对照时注意四个容易出问题的地方：一是相对路径的基准目录，它取决于进程启动时的工作目录，用绝对路径启动服务和用相对路径启动服务，解析结果可能完全不同；二是文件名的大小写与后缀，YAML 里写 main.yaml 而实际文件是 main.yml，属于典型静默失效；三是软链接，配置指向的是链接还是链接目标，日志里可能只显示其中之一；四是同名能力在多个目录下都存在，实际加载的未必是你改的那一个。可以用下面几条命令确认真实位置，并与日志中的路径逐字比对。

# 查看进程工作目录，确认相对路径的基准
 ls -l /proc/<pid>/cwd

# 把配置里的相对路径解析成真实绝对路径
 realpath ./capabilities/custom_demo/main.yaml

# 确认文件确实存在且名字大小写正确
 ls -l ./capabilities/custom_demo/

如果 realpath 的结果和日志里的路径不完全一致，包括多一层目录、多了符号、大小写不同，就先修正到这里，再往下走。这一步只解决“指向对不对”，不解决“生效了没有”。

用一次最小输入触发该能力

路径确认无误后，要验证调用链本身通不通。做法是固定一个输入、固定一个调用入口，只打一次，然后把返回内容完整记录下来。输入要尽量短，不含其他能力的触发条件，避免多个能力同时响应导致归因困难。

# 调用骨架示例，命令与参数按实际接入方式替换
 # 入口：对话页 / 接口 / 命令行，任选其一，但要每次都固定同一个
 # 输入：固定一句不触发其他能力的话
 # 期望：返回中出现该能力的标识（名称、前缀、标记字段等）

curl -s -X POST http://127.0.0.1:<port>/<your-endpoint> \
  -H "Content-Type: application/json" \
  -d '{"input":"fixed minimal test input","model":"default"}' \
  -w "\n耗时: %{time_total}s\n"

记录格式建议固定为五列：调用入口、固定输入原文、返回内容（或关键字段）、耗时、是否出现该能力标识。返回里没有标识，说明调用链没有走到该能力；返回里有标识但内容不符合预期，说明能力已进入链路但内部逻辑或参数不对；返回直接报错，先解决报错再谈覆盖问题。耗时只作为“是否真的执行了外部步骤”的辅助线索，不要拿来当性能结论。这一步通过之后，才适合怀疑配置层级。

对照作用范围确认是否被上层配置覆盖

配置通常有多层：系统或全局默认、项目或工作区级、用户会话级、单次请求携带的参数。生效规则一般是后者覆盖前者，同层内同名项按加载顺序或显式优先级决定。你在某一层改的值没体现出来，往往是因为更高优先级的那一层同时定义了这个能力，且值为关闭或指向别的路径。

排查时不要逐层翻文件猜，而是直接看运行时生效值。多数系统会提供三种入口之一：生效配置打印命令、启动时的配置汇总日志、或管理页面上的“当前配置”视图。任选其一，确认该能力的 enabled 字段与 entry 路径在生效值里到底是什么。

# 生效配置查看骨架，三种方式按实际支持情况选择
 # 1) 命令行打印
 omni config show `--effective`

# 2) 启动日志中的配置汇总段
 grep -n -A 20 -i "effective config" ./logs/omni-start.log

# 3) 管理页面：查看当前生效配置视图
 #    重点看该能力的 enabled 与 entry 两项

如果生效值和你改的文件不一致，就找到实际提供该值的那一层，把它记为“覆盖源”，不要先在原文件上继续改。同时留意同层内的加载顺序：两个目录放了同名能力时，后加载的会覆盖先加载的，日志里通常有重复或覆盖提示，可以回到第一步的命中行里核对。

只改一处配置后重启，确认变化是否生效

定位到可疑层之后，一次只改一个地方，否则多层同时变化时无法归因。改动前先记录原值，改动后按正常方式重启，不要用热加载和完整重启混着试。

# 改动记录模板
 # 改动项：capabilities.custom_demo.entry
 # 改动前：./capabilities/custom_demo/main.yaml
 # 改动后：/opt/omni/capabilities/custom_demo/main.yaml
 # 改动层级：项目级配置（全局默认未动）
 # 重启方式：重启 omni 服务进程，未使用热加载
 # 重启后日志差异：加载行由 skip 变为 loaded，路径与改动后一致
 # 行为变化：同一固定输入返回中出现该能力标识

重启后要做两件对照：日志差异和行为变化。日志上，对比改动前后同一关键词的命中行是否从跳过、未找到变成已加载；行为上，重放上一步那个固定输入，看返回里能力标识是否出现。若日志显示已加载但行为没变，问题在能力内部实现或参数，不在绑定层；若日志毫无变化，说明改的文件不是生效来源，回到上一步重新找覆盖源。改动项、重启方式、日志差异、行为变化这四项都写下来，下次同类问题可以直接对照，而不是从头猜。