NarutoCode 使用说明

NarutoCode 是一个在终端中使用的 Agent 编程工具。启动后，你可以直接用自然语言让它分析项目、修改文件、执行命令、排查问题或整理文档。

说明：客户端 GUI 暂时没有完成，当前仅提供终端（TUI）使用方式。

1. 准备配置文件

首次使用前，需要创建配置文件：

~/.narutocode/config.json

示例配置：

{
  "llms": [
    {
      "provider": "OpenAI",
      "protocol": "OpenAIChat",
      "address": "https://api.openai.com/v1",
      "apiKey": "YOUR_OPENAI_API_KEY",
      "model": "gpt-4.1",
      "maxContextWindowTokens": 128000,
      "maxOutputTokens": 16384,
      "supportsVision": true
    },
    {
      "provider": "DeepSeek",
      "protocol": "OpenAIChat",
      "address": "https://api.deepseek.com",
      "apiKey": "YOUR_DEEPSEEK_API_KEY",
      "model": "deepseek-chat",
      "maxContextWindowTokens": 64000,
      "maxOutputTokens": 8192
    }
  ],
  "system": {
    "logLevel": "Error",
    "compactionThresholds": {
      "imageCompaction": 0.25,
      "toolEviction": 0.6,
      "summarization": 0.8,
      "fallbackTruncation": 0.9,
      "minimumPreservedGroups": 8
    }
  },
  "mcpServers": {
    "codegraph": {
      "type": "stdio",
      "command": "codegraph",
      "args": ["serve", "--mcp"],
      "description": "用于分析 agent-framework（MAF）的源码",
      "workingDirectory": "",
      "enabled": true
    }
  },
  "enableApproval": false,
  "maxTurnCount": 10
}

把 apiKey、model 和 address 替换成你自己的模型配置。provider 是模型供应商的唯一标识，后续可以通过 /provider 命令切换。

如果使用 Anthropic 协议，可以增加一个 protocol 为 Anthropic 的配置：

{
  "provider": "Anthropic",
  "protocol": "Anthropic",
  "address": "https://api.anthropic.com",
  "apiKey": "YOUR_API_KEY",
  "model": "claude-sonnet-4-20250514",
  "maxContextWindowTokens": 200000,
  "maxOutputTokens": 16384,
  "supportsVision": true
}

MCP 服务配置

如果需要接入外部 MCP Server，可以在 mcpServers 中配置。支持 stdio 和 http 两种传输类型。

stdio：首次加载工具时启动对应本地命令，并把 MCP Server 暴露的工具加入 Agent 可用工具列表。
http：连接远程或本地 HTTP MCP 服务，自动兼容 Streamable HTTP 和 HTTP+SSE 协议。

{
  "mcpServers": {
    "codegraph": {
      "type": "stdio",
      "command": "codegraph",
      "args": ["serve", "--mcp"],
      "description": "用于分析 agent-framework（MAF）的源码",
      "workingDirectory": "",
      "enabled": true
    },
    "codegraph-frontend": {
      "type": "stdio",
      "command": "codegraph",
      "args": ["serve", "--mcp"],
      "description": "用于分析前端代码仓库的 CodeGraph 服务。",
      "workingDirectory": "",
      "enabled": true
    },
    "remote-tools": {
      "type": "http",
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      },
      "description": "远程 MCP 工具服务。",
      "enabled": true
    }
  }
}

mcpServers 的键是服务名称。agent 会使用 {服务名称}__{工具名称} 作为工具名，避免多个 MCP 服务暴露同名工具时冲突。

description 会拼接到该 MCP 服务暴露工具的描述前面。多个 MCP 服务提供同类工具时，可以用它告诉 AI 每个服务对应的用途，例如分别用于后端仓库、前端仓库或文档仓库。

http 类型的 headers 可选，用于在每次 HTTP 请求中附带自定义请求头，例如鉴权令牌、租户标识等。

NarutoCode 会额外使用运行时设置文件保存当前默认模型：

~/.narutocode/settings.json

如果首次启动时 settings.json 不存在，或里面没有有效的 provider，NarutoCode 会自动写入 llms 数组中的第一个 provider。

配置项说明

配置项	必填	说明
`llms`	是	LLM 模型配置数组，至少配置一个模型。
`llms[].provider`	是	模型厂商唯一标识，例如 `OpenAI`、`DeepSeek`、`Anthropic` 或自定义名称。
`llms[].protocol`	是	模型接入协议，支持 `OpenAIChat`、`OpenAIResponses`、`Anthropic`。
`llms[].address`	是	模型服务地址，必须是完整 URL。
`llms[].apiKey`	是	模型服务访问密钥。
`llms[].model`	是	要使用的模型名称。
`llms[].maxContextWindowTokens`	否	最大上下文窗口 Token 数。
`llms[].maxOutputTokens`	否	模型最大输出 Token 数，默认 `128000`。
`llms[].supportsVision`	否	模型是否支持视觉输入，默认 `false`。为 `false` 时，发送给模型的聊天历史会过滤其中的图片内容（替换为 `[image]` 占位文本），图片输入功能不可用。
`system.logLevel`	否	日志最小输出级别，支持 `Trace`、`Debug`、`Information`、`Warning`、`Error`、`Critical`；未配置或配置无效时默认 `Error`。
`system.compactionThresholds.imageCompaction`	否	图片压缩触发阈值（相对于上下文窗口的比例），默认 `0.25`。当 Token 使用率达到上下文窗口的 25% 时触发图片压缩。
`system.compactionThresholds.toolEviction`	否	工具结果压缩触发阈值（相对于上下文窗口的比例），默认 `0.6`。当 Token 使用率达到上下文窗口的 60% 时触发工具结果压缩。
`system.compactionThresholds.summarization`	否	摘要压缩触发阈值（相对于上下文窗口的比例），默认 `0.8`。当 Token 使用率达到上下文窗口的 80% 时触发摘要压缩。
`system.compactionThresholds.fallbackTruncation`	否	兜底截断触发阈值（相对于上下文窗口的比例），默认 `0.9`。当摘要后仍接近窗口上限时，只保留最近上下文，避免请求超过模型窗口。
`system.compactionThresholds.minimumPreservedGroups`	否	摘要和兜底截断时至少保留的最近消息组数量，默认 `8`。
`mcpServers`	否	MCP 服务配置对象，键为 MCP 服务名称。
`mcpServers.<name>.type`	否	MCP 服务传输类型，支持 `stdio` 和 `http`，默认 `stdio`。
`mcpServers.<name>.command`	stdio 必填	MCP 服务启动命令，仅适用于 `stdio` 类型。
`mcpServers.<name>.url`	http 必填	MCP HTTP 服务端点，必须为绝对 `http` 或 `https` URL，仅适用于 `http` 类型。
`mcpServers.<name>.headers`	否	MCP HTTP 服务自定义请求头，仅适用于 `http` 类型，键值会随每次请求发送。
`mcpServers.<name>.args`	否	MCP 服务启动参数数组，例如 `["serve", "--mcp"]`。
`mcpServers.<name>.description`	否	MCP 服务用途描述，会拼接到该服务暴露工具的描述前面，帮助 AI 区分多个同类 MCP 服务。
`mcpServers.<name>.workingDirectory`	否	MCP 服务启动工作目录；为空时使用当前进程工作目录。
`mcpServers.<name>.env`	否	MCP 服务启动时附加的环境变量对象。
`mcpServers.<name>.enabled`	否	是否启用该 MCP 服务，默认 `true`。
`enableApproval`	否	是否开启 Shell 工具审批，默认 `false`。设置为 `true` 后，执行 Shell 工具前需要确认。
`maxTurnCount`	否	单次对话最大交互轮次，默认 `10`。

2. 启动工具

如果你拿到的是压缩包，先解压并进入目录：

tar -xzf narutocode-osx-arm64-aot.tar.gz
cd narutocode-osx-arm64-aot

在要操作的项目目录中运行：

./narutocode

也可以直接指定工作目录：

./narutocode /path/to/workspace

如果已经把 narutocode 放到了 PATH 中，也可以直接使用：

narutocode /path/to/workspace

启动后，NarutoCode 会以该目录作为当前工作区。后续让 Agent 查看、修改或执行的内容都会基于这个工作区。

3. 启动网关（可选）

网关是一个独立的可执行程序，作用是把 NarutoCode 的 Agent 能力扩展到外部消息通道（如企业微信）。网关启动后，外部用户通过企业微信机器人发来的消息，会交给 Agent 处理并自动回复。

适用场景

在企业微信中通过 AI 机器人与 NarutoCode 交互
远程让 Agent 分析项目、修改代码、排查问题
不需要打开终端，通过聊天窗口即可使用 Agent 能力

准备网关配置

网关使用独立的配置文件，不影响 config.json：

~/.narutocode/gateway.json

示例配置：

{
  "weComBots": [
    {
      "id": "project-a-bot",
      "workspace": "/path/to/your/project-a",
      "enabled": true,
      "botId": "aib-xxxxx",
      "botSecret": "your-bot-secret",
      "corpId": "your-corp-id",
      "corpSecret": "your-corp-secret",
      "agentIdForRestApi": 1000002,
      "maxInboundChars": 4096
    }
  ]
}

如果需要绑定多个企业微信机器人到不同的工作目录，可以在 weComBots 数组中配置多组：

{
  "weComBots": [
    {
      "id": "project-a-bot",
      "workspace": "/path/to/your/project-a",
      "enabled": true,
      "botId": "aib-aaa",
      "botSecret": "secret-a"
    },
    {
      "id": "project-b-bot",
      "workspace": "/path/to/your/project-b",
      "enabled": true,
      "botId": "aib-bbb",
      "botSecret": "secret-b"
    }
  ]
}

启动网关

./narutocode-gateway

也可以指定配置文件路径：

./narutocode-gateway --config /path/to/gateway.json

启动成功后会输出：

网关已启动，按 Ctrl-C 退出。

之后在企业微信中对机器人发送消息，Agent 会处理后自动回复。每个机器人绑定各自的工作目录会话，互不干扰。

网关配置项说明

配置项	必填	说明
`weComBots`	是	企业微信机器人绑定数组，至少配置一个。
`weComBots[].id`	是	Gateway 内部绑定标识，用于区分多个机器人，必须唯一。
`weComBots[].workspace`	是	该机器人消息进入的根工作目录路径，不同绑定的工作目录不能重复。
`weComBots[].enabled`	否	是否启动该机器人通道，默认 `false`。
`weComBots[].botId`	是	企业微信 AI 机器人 BotId，格式 `aib-xxxxx`。
`weComBots[].botSecret`	是	AI 机器人长连接 Secret。
`weComBots[].corpId`	否	企业 CorpID，REST API 降级发送使用。
`weComBots[].corpSecret`	否	自建应用 Secret，用于获取 access_token。
`weComBots[].agentIdForRestApi`	否	自建应用 AgentId，REST API 降级发送使用。
`weComBots[].maxInboundChars`	否	入站消息最大字符数，超出截断，默认 `4096`。

botId 和 botSecret 用于接收消息（WebSocket 长连接）。corpId、corpSecret、agentIdForRestApi 为可选的 REST API 凭据，仅在 WebSocket 回复不可用时降级使用。

企业微信凭据也可以通过环境变量提供，环境变量名以绑定 id 派生前缀。例如 id 为 project-a-bot 时，对应环境变量：

环境变量	对应配置项
`WECOM_PROJECT_A_BOT_BOT_ID`	`weComBots[].botId`
`WECOM_PROJECT_A_BOT_BOT_SECRET`	`weComBots[].botSecret`
`WECOM_PROJECT_A_BOT_CORP_ID`	`weComBots[].corpId`
`WECOM_PROJECT_A_BOT_CORP_SECRET`	`weComBots[].corpSecret`
`WECOM_PROJECT_A_BOT_AGENT_ID_FOR_REST_API`	`weComBots[].agentIdForRestApi`

规则：将绑定 id 中的非字母数字字符替换为下划线，全部转大写，加 WECOM_ 前缀。

4. 子 Agent 委派（可选）

NarutoCode 支持在工作目录下配置子 Agent，让根 Agent 将特定任务委派给其他工作目录中的专业子 Agent 执行。

配置文件

创建配置文件：

~/.narutocode/subagents.json

示例配置：

{
  "delegation": {
    "agentExecutionTimeoutSeconds": 600
  },
  "workspaces": [
    {
      "workspace": "/path/to/your/project",
      "subAgents": [
        {
          "id": "code-reviewer",
          "name": "代码审查子 Agent",
          "description": "负责审查代码的正确性、安全性和性能问题。",
          "workspace": "/path/to/your/project-review"
        },
        {
          "id": "release-operator",
          "name": "发布执行子 Agent",
          "description": "负责发布前检查、构建验证和发布清单生成。",
          "workspace": "/path/to/your/project-release"
        }
      ]
    }
  ]
}

工作原理

子 Agent 的可见性由根工作目录精确匹配决定：只有当当前工作目录与配置中的 workspace 完全一致时，才会注入对应子 Agent。
不存在全局可用的子 Agent。未配置的工作目录不会暴露任何委派能力，保持原有单 Agent 行为。
每个子 Agent 在自身配置的 workspace（目标工作目录）中独立执行，拥有独立的文件系统、Shell 和会话上下文，不污染根会话历史。

委派机制

根 Agent 通过 delegate_agents 工具委派任务，支持两种调度模式：

parallel：同时执行多个互不依赖的子任务。
sequential：按顺序执行有前后依赖的子任务。

配置项说明

配置项	必填	说明
`delegation.agentExecutionTimeoutSeconds`	否	单个子 Agent 任务最长执行秒数，默认 `600`。
`workspaces[].workspace`	是	根工作目录路径，决定哪些工作目录会获得子 Agent 能力。
`workspaces[].subAgents[].id`	是	在当前根工作目录范围内唯一的子 Agent 标识。
`workspaces[].subAgents[].name`	是	子 Agent 名称，用于提示词和日志展示。
`workspaces[].subAgents[].description`	是	子 Agent 职责描述，帮助根 Agent 判断何时委派。
`workspaces[].subAgents[].workspace`	是	子 Agent 实际执行任务的目标工作目录。

subagents.json 不存在或为空时，根 Agent 不会暴露 delegate_agents 工具，行为与普通单 Agent 完全一致。

5. 切换模型 Provider

如果 config.json 中配置了多个模型，可以在运行中使用 /provider 查看和切换当前模型。

查看当前 provider 和可选列表：

/provider

切换到指定 provider：

/provider DeepSeek

切换成功后，NarutoCode 会把当前 provider 写入：

~/.narutocode/settings.json

下次启动时会优先使用这个 provider。如果 settings.json 没有有效 provider，则自动使用 llms 数组的第一个配置。

6. 配置推理强度

可以使用 /effort 查看和切换当前推理强度。

查看当前 effort 和可选列表：

/effort

切换到指定 effort：

/effort high

可选值为 low、medium、high、xhigh。切换成功后，NarutoCode 会把当前 effort 写入：

~/.narutocode/settings.json

下次启动时会优先使用这个 effort。如果 settings.json 没有配置 effort，则默认使用 medium。

7. 输入任务

启动后可以直接输入自然语言任务，例如：

帮我分析这个项目的目录结构

帮我找出登录接口相关代码，并说明调用链路

帮我修改 README，把新配置项补充进去

运行测试并修复失败的问题

8. 图片输入

如果需要让 Agent 分析图片，可以使用 /image：

/image ./docs/screenshot.png 请分析这张截图里的错误

支持的图片格式：

png、jpg、jpeg、webp、gif

也可以一次传入多张图片：

/image ./before.png ./after.png 对比这两张图的差异

图片输入依赖当前模型支持视觉。需要为当前使用的模型在 config.json 中开启：

{
  "llms": [
    {
      "provider": "OpenAI",
      "protocol": "OpenAIChat",
      "address": "https://api.openai.com/v1",
      "apiKey": "YOUR_OPENAI_API_KEY",
      "model": "gpt-4.1",
      "maxContextWindowTokens": 128000,
      "maxOutputTokens": 16384,
      "supportsVision": true
    }
  ]
}

未开启（默认 false）时，聊天历史中的图片会被替换为 [image] 占位文本，模型无法分析图片内容。

9. 工具审批

默认情况下：

"enableApproval": false

Shell 工具不需要额外审批。

如果希望执行 Shell 工具前先确认，可以改为：

"enableApproval": true

开启后，当 Agent 请求执行 Shell 工具时，终端会提示审批：

1 agree / 0 deny

输入：

1：同意执行
0：拒绝执行

10. 运行中继续输入

当 Agent 正在回复或执行任务时，你仍然可以继续输入下一条消息。NarutoCode 会把新输入加入队列，等当前任务结束后继续处理。

11. 取消和退出

取消当前操作：按 Ctrl+C
退出工具：输入 exit 或 quit

如果当前有正在运行的 Agent 操作，第一次 Ctrl+C 会优先取消当前操作。

12. 会话历史和本地数据

NarutoCode 会按工作目录保存会话历史。默认数据文件位置：

~/.narutocode/data/data.db

下次在同一个工作目录启动时，会自动加载对应的历史会话。控制台会保留可见聊天记录；发送给模型的上下文会按配置自动压缩和截断，以减少长会话占用并避免超过模型窗口。

13. 常见问题

提示配置文件不存在怎么办？

确认是否已经创建：

~/.narutocode/config.json

并检查 JSON 格式是否正确。

切换模型后需要重启吗？

如果只是切换已配置的模型，不需要重启，直接使用 /provider <provider> 即可。

如果修改了 config.json 中的模型列表、地址、密钥或协议，建议重新启动 NarutoCode，让新配置生效。

为什么工具执行前没有审批？

检查配置中是否设置了：

"enableApproval": true

未设置时默认关闭审批。

作者

作者：Naruto
GitHub：https://github.com/NarutoAI

Name		Name	Last commit message	Last commit date
Latest commit History 100 Commits
doc		doc
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
Directory.Build.props		Directory.Build.props
Directory.Packages.props		Directory.Packages.props
LICENSE		LICENSE
NarutoCode.slnx		NarutoCode.slnx
README.md		README.md

Navigation Menu

Uh oh!

Repository files navigation

NarutoCode 使用说明

1. 准备配置文件

MCP 服务配置

配置项说明

2. 启动工具

3. 启动网关（可选）

适用场景

准备网关配置

启动网关

网关配置项说明

4. 子 Agent 委派（可选）

配置文件

工作原理

委派机制

配置项说明

5. 切换模型 Provider

6. 配置推理强度

7. 输入任务

8. 图片输入

9. 工具审批

10. 运行中继续输入

11. 取消和退出

12. 会话历史和本地数据

13. 常见问题

提示配置文件不存在怎么办？

切换模型后需要重启吗？

为什么工具执行前没有审批？

作者

公众号

About

Releases

Packages

Contributors

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

NarutoCode 使用说明

1. 准备配置文件

MCP 服务配置

配置项说明

2. 启动工具

3. 启动网关（可选）

适用场景

准备网关配置

启动网关

网关配置项说明

4. 子 Agent 委派（可选）

配置文件

工作原理

委派机制

配置项说明

5. 切换模型 Provider

6. 配置推理强度

7. 输入任务

8. 图片输入

9. 工具审批

10. 运行中继续输入

11. 取消和退出

12. 会话历史和本地数据

13. 常见问题

提示配置文件不存在怎么办？

切换模型后需要重启吗？

为什么工具执行前没有审批？

作者

公众号

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages