> ## Documentation Index
> Fetch the complete documentation index at: https://coding-1afcb9be.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 故障排查

> 启动、连接、权限、路径、补丁和会话相关问题的排查线索。

# 故障排查

当客户端无法连接、工具缺失或命令行为与普通 shell 不一致时，从这里开始。

## 客户端无法连接

先确认传输方式。

HTTP 模式下检查服务是否在预期入口监听：

```bash theme={null}
curl http://127.0.0.1:8000/mcp
```

直接 CLI 默认是 `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`，客户端必须发送：

```text theme={null}
Authorization: Bearer <token>
```

OAuth 模式下，如果服务位于代理或 tunnel 后面，确认 `CODING_TOOLS_MCP_SERVER_URL` 与外部可见 URL 一致。

## 非 loopback HTTP 启动失败

当前实现拒绝无鉴权的非 loopback 绑定。添加 Bearer token 或 OAuth：

```bash theme={null}
coding-tools-mcp --host 0.0.0.0 --auth-token "$CODING_TOOLS_MCP_AUTH_TOKEN"
```

`CODING_TOOLS_MCP_AUTH_MODE=noauth` 只应在外层已有可信鉴权和网络隔离时使用。

## `tools/list` 里缺少工具

检查当前 profile：

```bash theme={null}
coding-tools-mcp --tool-profile full
```

`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 特性时，可重启为：

```bash theme={null}
coding-tools-mcp --permission-mode trusted
```

如果只是网络特征检测导致阻止，可考虑 `--allow-network`。

## 找不到可执行文件

`exec_command` 继承受控环境。先检查服务看到的执行环境，再调整 `--shell-env-inherit` 或显式传入环境变量。不要在 `safe` 或 `trusted` 中传入看起来像 secret 的值，因为它们会被过滤。

## 路径被拒绝或找不到文件

直接文件工具都会基于配置的工作区解析路径。确认服务启动时使用了正确工作区：

```bash theme={null}
coding-tools-mcp --workspace /path/to/workspace
```

当相对命令目录不符合预期时，使用 `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 限制，长输出命令应定期轮询。

## Landlock 警告

Linux 上服务会在可用时使用 Landlock 文件系统隔离。如果宿主不支持，命令执行会回退到策略检查并报告警告。运行不可信命令时应使用外层沙箱。