1. 先搞清楚 dsh-codex-connect 到底卡在哪一环
dsh-codex-connect 这个组件，本质上是在 DeepSeek Harness 和 openai-codex 之间搭一条桥。DeepSeek Harness 负责把模型能力封装成可调用的工作流插件，openai-codex 负责代码生成与补全的那一层交互，而 dsh-codex-connect 就是让这两边能对上话的中间件。很多人第一次装完 DeepSeek Harness，兴冲冲地想把 codex 接进来，结果发现要么连不上，要么连上了但返回一堆看不懂的报错。这时候大多数人第一反应是去翻文档，但文档往往只告诉你"怎么装"，不告诉你"装完出问题怎么办"。
我自己的习惯是，遇到这类连接类组件出问题，先不要急着改配置，而是先跑一遍doctor命令。dsh-codex-connect 自带一个诊断入口，通常挂在dsh-codex-connect doctor或者dsh doctor --component codex-connect下面，具体取决于你装的是哪个发行版本。这个 doctor 会依次检查：运行时环境是否满足最低版本、配置文件路径是否正确、端口是否被占用、依赖的 codex 侧服务是否可达、以及认证凭据是否过期。它输出的每一项都有明确的 PASS/FAIL 标记，你只要盯着第一个 FAIL 往下查就行，不用从头到尾瞎猜。
为什么我强调先跑 doctor 而不是先看日志？因为日志是"结果"，doctor 是"体检"。日志里可能同时出现五条报错，但其中四条是第一条引发的连锁反应。doctor 的好处是它按依赖顺序检查，第一个失败项基本就是根因。我见过太多人拿着日志里最后一条报错去搜，搜了半天发现那条报错只是"连接被拒绝"，真正的原因其实是前面某个配置文件根本没被加载。
还有一个容易被忽略的点：dsh-codex-connect 在不同平台上的默认路径不一样。Linux 下通常在~/.config/dsh/或者/etc/dsh/，桌面版可能落在用户目录下的AppData或者Library/Application Support里。如果你之前把 DeepSeek Harness 装到了 D 盘或者非默认位置，那 codex-connect 的配置文件很可能还在默认路径下找，两边对不上，自然连不通。这种情况 doctor 通常会报"config not found"或者"path mismatch"，看到这类提示，先去确认你的安装路径和配置路径是否一致。
下面这张表是我整理的高频现象与第一反应动作的对照，先有个全局印象，后面逐个展开：
| 现象 | 最可能的根因层 | 第一动作 |
|---|---|---|
| 命令找不到 / command not found | 安装层 | 检查 PATH 与安装路径 |
| 连接被拒绝 / connection refused | 服务层 | 确认 codex 侧是否在跑 |
| 认证失败 / unauthorized | 凭据层 | 检查 token 与过期时间 |
| 配置不生效 / config ignored | 路径层 | 核对配置加载顺序 |
| 超时 / timeout | 网络层 | 检查端口与防火墙 |
这张表不是让你死记，而是帮你建立"看到现象先定位到哪一层"的条件反射。接下来我把这五个现象一个一个拆开，每个都给出具体的排查命令和背后的逻辑。
2. 现象一：命令找不到，别急着重装
2.1 command not found 的真实原因往往不是没装
很多人敲dsh-codex-connect或者dsh codex-connect的时候，终端直接甩一句command not found，第一反应就是"是不是没装成功"，然后开始重装。但实际情况是，十次里有七八次，组件是装好了的，只是可执行文件所在的目录没进 PATH。尤其是你把 DeepSeek Harness 装到 D 盘、或者用非 root 用户装到自定义目录的时候，安装脚本可能把二进制放在了安装目录/bin/下面，但没帮你写进 shell 的 PATH。
排查这个很简单，先确认文件到底在不在：
# Linux / macOS find / -name "dsh-codex-connect" -type f 2>/dev/null # 如果你记得大概装在哪个盘或目录，缩小范围更快 find /your/install/path -name "dsh*" -type f 2>/dev/nullWindows 下用 PowerShell：
Get-ChildItem -Path C:\,D:\ -Recurse -Filter "dsh-codex-connect*" -ErrorAction SilentlyContinue找到文件之后，看它是不是可执行。Linux 下如果权限不对，ls -l会显示没有x位，这时候chmod +x补上就行。但更常见的是文件在、权限也对，就是 PATH 里没有这个目录。
2.2 把安装目录加进 PATH 的正确姿势
临时加和永久加是两回事。临时加只对当前终端会话有效：
export PATH="$PATH:/your/install/path/bin"永久加要看你用的是哪个 shell。bash 用户改~/.bashrc，zsh 用户改~/.zshrc，改完记得source一下。这里有个坑：如果你用的是桌面版 DeepSeek Harness，它可能自带一个终端环境，那个环境的 PATH 和你系统终端是分开的。你在系统终端里加好了 PATH，但桌面版内部调用的时候还是找不到，这时候要去桌面版的设置里找"环境变量"或者"高级设置"，把路径补进去。
提示：改完 PATH 之后，先
which dsh-codex-connect确认能找到，再跑 doctor。不要跳过这一步直接跑连接测试，否则你分不清是 PATH 问题还是连接问题。
还有一个细节：有些安装方式会创建一个软链接到/usr/local/bin/，但软链接指向的目标被移动或删除了，这时候which能找到，但执行会报"no such file or directory"。这种情况用ls -l $(which dsh-codex-connect)看一下链接指向，确认目标存在。
2.3 卸载残留导致的"假安装"
如果你之前装过旧版本的 DeepSeek Harness，卸载的时候没清干净，旧的可执行文件可能还在 PATH 里，但版本对不上。这时候你敲命令能跑，但行为诡异，doctor 可能报一些莫名其妙的错。判断方法很简单：
dsh-codex-connect --version如果版本号和你刚装的对不上，或者干脆报错说找不到某个依赖库，那基本就是残留问题。彻底清理的做法是：先找到所有相关的可执行文件和配置目录，手动删掉，再重新装。Linux 下配置通常在~/.config/dsh/和~/.local/share/dsh/，桌面版可能在~/.dsh/或者安装目录下的data/里。删之前建议先备份，万一里面有你的自定义配置。
我自己的经验是，卸载 DeepSeek Harness 的时候，光跑卸载脚本不够，一定要手动检查这三个地方：可执行文件目录、配置目录、以及 shell 的 PATH 配置文件里有没有残留的 export 语句。残留的 export 会让你的新安装指向旧路径，这种问题最隐蔽，doctor 都不一定能直接报出来。
3. 现象二：连接被拒绝，先确认对面在不在
3.1 connection refused 的本质是"端口没人监听"
dsh-codex-connect 要连的对面，通常是 openai-codex 侧的一个本地服务或者远程端点。connection refused这个报错的含义非常明确：你的连接请求到达了目标 IP 和端口，但那个端口上没有程序在监听。注意，这和"超时"是两回事。超时是包发出去了没回应，拒绝是明确告诉你"这里没人"。
所以第一步不是改 dsh-codex-connect 的配置，而是确认 codex 侧的服务到底起没起。如果你用的是本地 codex 服务，先看进程：
# Linux / macOS ps aux | grep -i codex # 或者看端口 ss -tlnp | grep <codex端口> # 老系统用 netstat netstat -tlnp | grep <codex端口>Windows 下：
Get-Process | Where-Object {$_.ProcessName -like "*codex*"} netstat -ano | findstr <codex端口>如果进程不在，那问题就清楚了，先把 codex 侧的服务拉起来。如果进程在但端口不对，那可能是 codex 侧配置里写的监听端口和 dsh-codex-connect 里写的目标端口不一致。这种情况 doctor 通常会报"port mismatch"或者"endpoint unreachable"。
3.2 端口占用的排查与处理
有时候 codex 侧的服务确实起了，但它想监听的端口被别的程序占了，于是它要么启动失败，要么自动换了一个端口，而 dsh-codex-connect 还在往原端口连。这种问题在 Linux 上尤其常见，因为很多服务默认端口就那么几个，容易撞车。
排查端口占用：
# Linux lsof -i :<端口> # 或者 fuser <端口>/tcp # macOS lsof -i :<端口> # Windows netstat -ano | findstr :<端口> # 拿到 PID 之后 tasklist | findstr <PID>找到占用端口的程序之后，你有两个选择：要么把那个程序停掉或改端口，要么把 codex 侧的服务改到另一个空闲端口，同时同步修改 dsh-codex-connect 的目标端口配置。我一般倾向于后者，因为动别人的服务风险更大。改端口的时候注意，dsh-codex-connect 的配置文件里可能不止一处写了端口，有的在连接配置里，有的在健康检查配置里，改的时候要一起改，否则 doctor 会报"health check failed"。
3.3 防火墙和 SELinux 的隐形拦截
如果进程在、端口也对，但还是 connection refused，那就要考虑防火墙了。Linux 下iptables或者firewalld可能把端口拦了，表现有时候是拒绝，有时候是超时，取决于具体规则。快速验证方法是临时关掉防火墙试一下：
# 临时关闭 firewalld（仅用于排查，排查完记得开回来） systemctl stop firewalld # 或者用 iptables 看规则 iptables -L -n | grep <端口>SELinux 也会拦，尤其是你把服务装到了非标准路径下。查看 SELinux 状态：
getenforce如果是Enforcing，可以临时设成Permissive试一下：
setenforce 0如果设成 Permissive 之后连接就通了，那说明是 SELinux 策略问题，你需要给对应的可执行文件打标签或者写策略，而不是一直关着 SELinux。这个坑我在 Kali 上装 DeepSeek Harness 的时候踩过，当时 codex-connect 一直连不上，查了半天端口和进程都没问题，最后发现是 SELinux 把非标准路径下的服务给拦了。
注意：排查阶段临时关防火墙或 SELinux 是可以的，但排查完一定要恢复。长期关着等于把门敞开，不是个好习惯。
4. 现象三：认证失败，token 的坑比你想的多
4.1 unauthorized 不一定是 token 错了
看到unauthorized或者401，很多人第一反应是"token 填错了"，然后反复复制粘贴。但实际上，认证失败的原因至少有四种：token 本身错误、token 过期、token 权限不足、以及 token 格式不对（比如多了空格或换行）。dsh-codex-connect 在读取 token 的时候，如果配置文件里 token 那一行末尾有个看不见的换行或者空格，它可能原样带进去，导致认证失败。
排查方法：先把 token 单独拿出来验证。如果你用的是 API key 类的凭据，可以用 curl 直接打一下 codex 侧的健康检查端点：
curl -H "Authorization: Bearer <你的token>" http://<codex地址>:<端口>/health如果 curl 也返回 401，那说明 token 本身有问题，和 dsh-codex-connect 无关。如果 curl 通了但 dsh-codex-connect 不通，那问题就在 dsh-codex-connect 读取 token 的方式上。这时候去检查配置文件，确认 token 字段没有多余字符。有些配置文件格式对缩进敏感，YAML 里多一个空格都可能导致解析出问题。
4.2 token 过期与自动刷新机制
很多 codex 侧的凭据是有有效期的，短的可能几小时，长的几天。dsh-codex-connect 如果没配自动刷新，过期之后就会一直报认证失败。doctor 通常会报"token expired"或者"credential invalid"，但有些版本只报笼统的"auth failed"，需要你自己去看凭据的过期时间。
检查凭据过期时间的方法取决于你用的认证方式。如果是 JWT，可以直接解码看exp字段：
# 把 token 中间那段 base64 解出来看 echo "<token中间段>" | base64 -d 2>/dev/null如果是配置文件里写了过期时间，直接看配置。确认过期之后，重新生成或刷新 token，更新到 dsh-codex-connect 的配置里。这里有个经验：更新完 token 之后，最好重启一下 dsh-codex-connect 的服务或进程，因为有些实现是启动时读一次配置，之后不再重读，你不重启它还用旧的。
4.3 权限范围与 scope 配置
还有一种认证失败是"权限不足"，报错可能是403而不是401。这种情况 token 本身是有效的，但它没有被授予访问 codex 侧某个接口的权限。dsh-codex-connect 在连接的时候可能会调用多个端点，比如先做健康检查，再拉取模型列表，再建立实际连接。如果 token 只有部分权限，可能健康检查过了，但后续步骤失败。
排查这种问题，要看 doctor 的详细输出，它会告诉你哪一步失败了。如果是权限问题，你需要去 codex 侧的凭据管理里给这个 token 加上对应的 scope。不同版本的 codex 对 scope 的命名不一样，有的叫read、write，有的叫codex.connect、codex.invoke，具体看文档。加完 scope 之后同样要重启 dsh-codex-connect。
我自己的做法是，在正式环境里给 dsh-codex-connect 单独建一个凭据，只授予它需要的最小权限，而不是直接用管理员 token。这样一方面安全，另一方面出问题的时候容易定位，因为权限边界清晰。
5. 现象四：配置不生效，加载顺序是关键
5.1 配置文件到底读的是哪一个
dsh-codex-connect 支持多级配置，通常有全局配置、用户配置、项目级配置三层。加载顺序一般是：全局 < 用户 < 项目，后面的覆盖前面的。但不同版本可能不一样，有的版本是反过来，项目级优先级最低。这就导致一个常见问题：你在项目目录下改了配置，但实际生效的是用户目录下的全局配置，你的修改被覆盖了。
确认当前生效的配置路径，最直接的方法是看 doctor 的输出，它通常会列出"loaded config files"或者"config search path"。如果没有，可以看启动日志，日志里一般会打印读了哪些文件。找到实际生效的那个文件，再去改它，而不是改你以为的那个。
# 很多工具支持打印当前配置 dsh-codex-connect config show # 或者 dsh-codex-connect --show-config如果命令不支持，就去看进程的启动参数，或者用strace跟踪文件读取（Linux）：
strace -f -e trace=openat dsh-codex-connect 2>&1 | grep -i config5.2 配置格式的常见错误
配置文件格式错误是另一个高频坑。YAML 对缩进极其敏感，多一个空格少一个空格结果完全不同。JSON 则对逗号和引号敏感，末尾多一个逗号就解析失败。TOML 相对宽容，但字段名拼错照样不生效。
排查格式问题，先做语法校验：
# YAML python -c "import yaml,sys; yaml.safe_load(open('config.yaml'))" # JSON python -m json.tool config.json # TOML python -c "import tomllib; tomllib.load(open('config.toml','rb'))"校验通过不代表字段名对。字段名拼错是最隐蔽的，因为格式没问题，程序也不报错，就是那个字段被忽略了。这时候要对照文档一个字段一个字段核对。我一般会把文档里的示例配置复制过来，只改值不改键名，这样能避免大部分拼写错误。
5.3 环境变量覆盖配置文件的陷阱
dsh-codex-connect 很多配置项支持用环境变量覆盖。比如配置文件里写了port: 8080，但环境变量里有个DSH_CODEX_PORT=9090，那实际生效的是 9090。这种覆盖机制在容器化部署里很常见，但在本地手动装的时候容易忘。
排查方法：把所有相关的环境变量列出来看看：
env | grep -i dsh env | grep -i codex如果发现有环境变量和你配置文件里的值冲突，要么删掉环境变量，要么改环境变量。这里有个经验：环境变量的优先级通常高于配置文件，所以当你发现"改了配置没生效"的时候，先查环境变量，再查加载顺序。
提示：桌面版 DeepSeek Harness 有时候会在启动时注入自己的环境变量，这些变量你在系统终端里
env是看不到的。如果怀疑是这种情况，去桌面版的设置里找"环境变量"面板，或者看它的启动日志。
6. 现象五：超时，网络层的问题最容易被误判
6.1 timeout 和 connection refused 的区别
这两个报错经常被混为一谈，但它们的排查方向完全不同。connection refused是"有人告诉你这里没人"，timeout是"你喊了半天没人应"。timeout 通常意味着包发出去了，但要么被防火墙丢了，要么路由不通，要么对面处理太慢。
先做基础连通性测试：
# 测试端口是否可达 nc -zv <目标地址> <端口> # 或者 telnet <目标地址> <端口> # 测试路由 traceroute <目标地址> # Windows 用 tracert <目标地址>如果nc也超时，那问题在网络层，和 dsh-codex-connect 本身无关。如果nc通了但 dsh-codex-connect 超时，那可能是 dsh-codex-connect 的超时设置太短，或者对面处理确实慢。
6.2 超时参数的调整
dsh-codex-connect 的配置文件里通常有超时相关的参数，比如connect_timeout、read_timeout、request_timeout。默认值可能比较保守，比如 5 秒或 10 秒。如果你的 codex 侧服务启动慢或者处理慢，这个时间可能不够。
调整的时候不要一次调太大，先调到 30 秒试一下。如果 30 秒能通，说明确实是超时问题，再根据实际情况微调。如果调到 30 秒还是超时，那大概率不是超时参数的问题，而是网络本身不通。
# 示例配置片段 codex: connect_timeout: 30s read_timeout: 60s request_timeout: 120s注意不同版本参数名可能不一样，有的叫timeout，有的叫deadline，以你实际版本的文档为准。
6.3 DNS 解析慢导致的假超时
还有一种超时是 DNS 解析慢造成的。如果你在配置里写的是域名而不是 IP，dsh-codex-connect 每次连接都要先解析域名。如果 DNS 服务器响应慢，或者域名解析本身有问题，就会表现为超时。
排查方法：把配置里的域名换成 IP 试一下。如果换成 IP 就通了，那说明是 DNS 问题。解决办法要么是换一个更快的 DNS，要么是在本机 hosts 文件里把域名和 IP 的映射写死。
# Linux / macOS cat /etc/hosts # Windows type C:\Windows\System32\drivers\etc\hosts在 hosts 里加一行：
<codex的IP> <codex的域名>这样解析就变成本地的了，不经过 DNS 服务器，速度快很多。这个技巧在本地开发环境里特别实用，因为本地服务的域名解析经常出幺蛾子。
7. 把 doctor 用透：从输出里读出根因
7.1 doctor 输出的结构解读
前面反复提到 doctor，这里专门说一下怎么读它的输出。一个设计良好的 doctor 输出通常分几块：环境检查、配置检查、依赖检查、连接检查、认证检查。每块下面有若干检查项，每项有状态和说明。
读的时候按顺序看，第一个 FAIL 就是你要先解决的。不要跳着看，也不要因为后面有 WARN 就慌。WARN 通常不影响核心功能，FAIL 才是阻断性的。有些 doctor 会把 FAIL 的原因和建议的修复命令一起打出来，这种最省事，直接照着做就行。
如果 doctor 输出太长，可以重定向到文件慢慢看：
dsh-codex-connect doctor > doctor.log 2>&1然后搜FAIL和ERROR：
grep -n -i "fail\|error" doctor.log7.2 doctor 报的错和实际根因不一致怎么办
有时候 doctor 报的错是表象，不是根因。比如它报"连接失败"，但实际根因是配置文件没加载。这种情况通常是因为 doctor 的检查顺序有问题，或者某个检查项的失败引发了连锁反应。
遇到这种情况，我的做法是：先解决 doctor 报的第一个 FAIL，解决完再跑一遍。如果第一个 FAIL 解决了但出现了新的 FAIL，那说明之前的 FAIL 确实是根因。如果第一个 FAIL 解决不了，或者解决了但问题依旧，那就需要手动深入排查那一层。
还有一种情况是 doctor 本身有 bug，报了一个不存在的问题。这种比较少见，但如果你确认那一项没问题，可以跳过，看下一项。判断方法是对照文档和实际文件，确认 doctor 说的和实际不符。
7.3 自定义 doctor 检查项
有些版本的 dsh-codex-connect 支持自定义 doctor 检查项，你可以在配置里加自己的检查脚本。这个功能在排查特定环境问题时很有用。比如你可以加一个检查，确认某个依赖库的版本是否满足要求，或者确认某个目录的权限是否正确。
配置方式通常是在配置文件里加一段：
doctor: custom_checks: - name: "check codex binary" command: "which codex-server" expect_exit_code: 0这样 doctor 跑的时候会额外执行你的检查。具体语法看版本文档，不是所有版本都支持。
8. 几个我踩过的坑和对应的快速恢复手段
8.1 装到 D 盘之后路径全乱
Windows 下把 DeepSeek Harness 装到 D 盘，然后 dsh-codex-connect 的配置里还写着 C 盘的默认路径，这是最常见的"装完不能用"原因。表现是 doctor 报"config not found"或者"binary not found"，但你明明装了。
快速恢复：找到实际安装目录，把 dsh-codex-connect 的配置里所有路径改成实际路径。重点检查这几个字段：install_dir、config_dir、data_dir、log_dir。改完重启服务。
8.2 Kali 上装完 SELinux 拦截
Kali 默认可能没开 SELinux，但如果你手动开了或者用了某些加固配置，SELinux 会拦非标准路径下的服务。表现是进程在、端口对、防火墙也放行了，但就是连不上。
快速恢复：getenforce确认状态，临时setenforce 0验证。确认是 SELinux 问题后，给可执行文件打标签：
semanage fcontext -a -t bin_t "/your/path/dsh-codex-connect" restorecon -v /your/path/dsh-codex-connect8.3 卸载重装后旧配置残留
卸载 DeepSeek Harness 之后，~/.config/dsh/和~/.local/share/dsh/可能还在，里面有你之前的配置。重装之后，新版本可能读到了旧配置，导致行为异常。
快速恢复：卸载后手动删掉这两个目录（先备份），再重装。重装后不要急着改配置，先跑 doctor 确认默认配置能通，再逐步加你的自定义配置。
8.4 桌面版和命令行版配置不互通
桌面版 DeepSeek Harness 和命令行版可能用不同的配置目录。你在命令行里配好了，桌面版读不到，反之亦然。表现是"命令行能跑，桌面版报错"或者反过来。
快速恢复：确认你用的是哪个版本，然后去对应的配置目录改。桌面版的配置目录通常在用户目录下的隐藏文件夹里，具体位置看桌面版的设置里"关于"或"高级"页面。
9. 排查顺序的固化：形成自己的 checklist
9.1 从现象到层的映射表
把前面五个现象和对应的排查层固化下来，形成条件反射：
| 现象 | 先查 | 再查 | 最后查 |
|---|---|---|---|
| command not found | PATH | 文件是否存在 | 权限 |
| connection refused | 对面进程 | 端口占用 | 防火墙/SELinux |
| unauthorized | token 有效性 | token 过期 | scope 权限 |
| config ignored | 实际加载路径 | 格式校验 | 环境变量覆盖 |
| timeout | 基础连通性 | 超时参数 | DNS 解析 |
这张表建议存下来，下次遇到问题直接对照，能省很多时间。
9.2 每次排查完记录一条
我自己的习惯是，每次解决一个 dsh-codex-connect 的问题，就在笔记里记一条：现象、根因、解决命令。积累多了之后，你会发现很多问题反复出现，有了记录就能秒解。尤其是环境相关的问题，比如路径、权限、防火墙，换个机器可能又遇到，有记录就不用重新查。
记录的时候重点记"根因"而不是"现象"，因为同一个现象可能有不同根因。比如 connection refused 可能是进程没起，也可能是端口被占，记的时候要写清楚是哪种。
9.3 定期跑 doctor 做预防性检查
不要等到出问题了才跑 doctor。我一般会在每次升级 DeepSeek Harness 或 dsh-codex-connect 之后，以及每次改完配置之后，都跑一遍 doctor。这样能在问题影响实际使用之前就发现。doctor 跑起来很快，几秒钟的事，但能省下后面几十分钟的排查时间。
如果 doctor 支持定时任务，可以配一个每天跑一次的 cron，把输出写到日志里。这样即使你不主动跑，也能回溯某一天的状态。
# 示例 cron，每天凌晨 3 点跑一次 0 3 * * * /your/path/dsh-codex-connect doctor >> /var/log/dsh-doctor.log 2>&1这个做法在服务器环境里特别有用，因为服务器上的问题往往不是你主动发现的，而是用户报过来的。有了每日 doctor 日志，你能快速判断问题是新出现的还是一直存在的。
9.4 版本升级后的兼容性检查
dsh-codex-connect 和 DeepSeek Harness、openai-codex 之间有版本兼容性要求。升级其中一个之后，另外两个可能不兼容。表现是各种奇怪的报错，doctor 可能报"version mismatch"也可能不报。
升级后的第一件事，是确认三个组件的版本是否在兼容矩阵里。兼容矩阵通常在文档的"版本说明"或"release notes"里。如果不在，要么降级，要么把三个都升到兼容的版本。我自己的做法是，升级前先看 release notes 里的兼容性说明，确认没问题再升，避免升完发现不兼容又得回滚。
10. 关于日志：什么时候看，怎么看
10.1 日志级别与输出位置
dsh-codex-connect 的日志级别通常有 debug、info、warn、error 几档。默认可能是 info，排查问题的时候临时调到 debug，能看到更详细的信息。调整方式看配置，通常是log_level: debug。
日志输出位置可能是控制台、文件、或者两者都有。文件日志的位置在配置里找log_file或log_dir。如果配置里没写，看 doctor 输出或者启动参数。
10.2 从日志里定位关键行
日志很长的时候，不要从头看。先搜关键词：
grep -n -i "error\|fail\|exception\|timeout\|refused" dsh-codex-connect.log找到关键行之后，看它前后各 20 行，了解上下文。很多错误是连锁的，关键行前面往往有更根本的原因。
如果日志里有堆栈，从最下面往上看，最下面通常是根因，上面是调用链。但有些语言的堆栈是反的，具体看语言习惯。
10.3 日志轮转与磁盘占用
debug 级别的日志增长很快，如果没配轮转，可能几天就把磁盘占满。排查完问题记得把日志级别调回 info，并确认日志轮转配置生效。轮转配置通常在log_rotate或log_max_size之类的字段里。
如果磁盘已经被日志占满了，先清理旧日志，再调级别。清理的时候注意别删正在写的那个文件，否则可能导致进程异常。
11. 最后分享几个实用小技巧
第一个技巧：把常用的排查命令做成 alias 或脚本。比如我有个dsh-check脚本，依次跑 doctor、看进程、看端口、看日志尾部，一条命令出全部信息。这样排查的时候不用一个个敲。
#!/bin/bash echo "=== doctor ===" dsh-codex-connect doctor echo "=== process ===" ps aux | grep -i codex | grep -v grep echo "=== port ===" ss -tlnp | grep <端口> echo "=== log tail ===" tail -50 /var/log/dsh-codex-connect.log第二个技巧：改配置之前先备份。cp config.yaml config.yaml.bak，出问题了直接还原，比一点点改回去快得多。尤其是排查阶段，你可能要反复改配置试，有备份心里踏实。
第三个技巧：如果 doctor 和日志都看不出问题，试试最小化配置。把配置文件里除了必填项之外的全注释掉，跑一遍。如果最小化配置能通，再一项一项加回来，加到哪一项出问题，就是那一项的问题。这个方法虽然笨，但对那种"配置太多不知道哪项冲突"的情况特别有效。
第四个技巧：关注 dsh-codex-connect 的 release notes。很多你遇到的问题，新版本可能已经修了。升级之前看 release notes，升级之后跑 doctor，这是最基本的维护习惯。
第五个技巧：如果实在搞不定，把 doctor 输出和日志脱敏之后发到社区。发之前记得把 token、IP、路径里的敏感信息替换掉。描述问题的时候说清楚：什么现象、跑了什么命令、期望什么结果、实际什么结果。信息给全了，别人才能帮你定位。
