故障排查
当客户端无法连接、工具缺失或命令行为与普通 shell 不一致时，从这里开始。客户端无法连接
先确认传输方式。 HTTP 模式下检查服务是否在预期入口监听：127.0.0.1:8000。部分辅助脚本或 tunnel 文档可能使用 8765，因此要同时确认实际 --port、CODING_TOOLS_MCP_PORT、包装脚本和客户端 URL。
stdio 模式下，确认客户端命令包含 --stdio，并且没有把额外日志写到 stdout。JSON-RPC 响应必须保持在 stdout，诊断信息应写 stderr。
HTTP 返回 unauthorized
如果配置了--auth-token 或 CODING_TOOLS_MCP_AUTH_TOKEN，客户端必须发送：
CODING_TOOLS_MCP_SERVER_URL 与外部可见 URL 一致。
非 loopback HTTP 启动失败
当前实现拒绝无鉴权的非 loopback 绑定。添加 Bearer token 或 OAuth：CODING_TOOLS_MCP_AUTH_MODE=noauth 只应在外层已有可信鉴权和网络隔离时使用。
tools/list 里缺少工具
检查当前 profile：
read-only 会隐藏 apply_patch、exec_command、write_stdin、kill_session、set_default_cwd 和 request_permissions 等工具。设置 CODING_TOOLS_MCP_ENABLE_VIEW_IMAGE=0 会禁用 view_image。
命令被阻止
safe 模式会阻止常见风险命令模式。常见诊断包括网络、shell 展开、内联脚本、敏感环境、破坏性命令、超长超时、特权可执行文件或写入 generated/ignored 文件。
本地开发命令需要包管理器或 shell 特性时，可重启为：
--allow-network。
找不到可执行文件
exec_command 继承受控环境。先检查服务看到的执行环境，再调整 --shell-env-inherit 或显式传入环境变量。不要在 safe 或 trusted 中传入看起来像 secret 的值，因为它们会被过滤。
路径被拒绝或找不到文件
直接文件工具都会基于配置的工作区解析路径。确认服务启动时使用了正确工作区：get_default_cwd 和 set_default_cwd 检查或修改默认目录。
read_file 编码或二进制失败
read_file 只支持 UTF-8 文本，并会拒绝看起来像二进制的文件。图片文件使用 view_image；其他二进制检查可在合适权限模式下通过命令行工具处理。
补丁失败
先用apply_patch 的 dry_run: true 验证。常见原因包括上下文过期、路径不在工作区、generated/ignored 写入策略，或 patch 文本格式不符合预期。
长时间运行的 session 问题
保存exec_command 返回的 session_id，用 write_stdin 轮询或写入输入，用 kill_session 终止。输出可能受 max_output_bytes 和 session buffer 限制，长输出命令应定期轮询。