快速开始

niuma_code 是一款 Claude Code 配套工具。下载 niuma.exe，配置 API 密钥，即可启动——无需安装。

你将学到

如何下载并运行 niuma.exe
如何配置 API 供应商
如何首次启动 niuma_code
基本导航和核心命令

环境要求

要求	说明
操作系统	Windows 10 或更高版本
磁盘空间	~50 MB 可用空间
API 密钥	Anthropic API 密钥（或兼容供应商）

niuma_code 以单个可执行文件分发——无需 Python、Node.js 或 npm。

第一步：下载

从官网下载最新版本：

# 直接下载链接
# https://niumacode.oss-cn-beijing.aliyuncs.com/releases/niuma.exe

将 niuma.exe 保存到任意位置（例如 D:\tools\niuma.exe）。

第二步：配置 API 密钥

在 ~/.niuma/settings.json 创建配置文件：

# 导航到用户主目录
cd %USERPROFILE%
mkdir .niuma 2>nul

创建 settings.json：

{
    "factories": [
        {
            "base_url": "https://api.anthropic.com",
            "api_key": "sk-ant-你的密钥",
            "options": ["claude-sonnet-4-6"]
        }
    ]
}

字段	说明
`base_url`	API 端点 URL
`api_key`	认证密钥
`options`	可用模型名称列表

第三步：启动

niuma.exe

你应该看到 niuma_code 的 logo 和交互提示符：

  (__) ^__^   niuma code
  (nu) (ma)   claude-sonnet-4-6
  (__)  \/    D:\your\project
   /|   ||

输入你的第一个问题，按 Enter 开始对话。

第四步：基本操作

操作	方式
发送消息	输入内容后按 Enter
取消生成	按 `Esc`
切换模型	输入 `/model`
查看命令	输入 `/help`
退出	输入 `/quit`

第一次对话

发送一条简单消息验证一切正常：

> 你好！能帮我了解一下这个项目吗？

niuma_code 会：

连接到你配置的 API
启动自主工具调用循环
读取文件、探索代码并回复

配置选项

多供应商配置

添加多个 API 端点，随时在模型之间切换：

{
    "factories": [
        {
            "base_url": "https://api.anthropic.com",
            "api_key": "sk-ant-key1",
            "options": ["claude-sonnet-4-6", "claude-opus-4-8"]
        },
        {
            "base_url": "https://api.openai.com",
            "api_key": "sk-openai-key2",
            "options": ["gpt-4o"]
        }
    ]
}

使用 /model 打开模型选择浮层即可随时切换。

高级配置

以下是 settings.json 的完整参考。所有字段均为可选，只需配置 factories 即可启动。

{
    "factories": [
        {
            "base_url": "https://api.anthropic.com",
            "api_key": "your-api-key-here",
            "options": ["claude-sonnet-4-6", "claude-opus-4-8"]
        }
    ],
    "llm": {
        "default_model": "claude-sonnet-4-6",
        "default_effort": "high",
        "max_contexts": 5,
        "resume_latest_context": false,
        "options": [
            {"claude-sonnet-4-6": ["low", "medium", "high"]},
            {"claude-opus-4-8": ["low", "medium", "high"]}
        ],
        "thinking_budget_low": "0",
        "thinking_budget_medium": "0",
        "thinking_budget_high": "10000",
        "thinking_budget_max": "20000"
    },
    "env": {
        "persona_name": "niuma",
        "model_background": "claude-haiku-4-5",
        "temperature_zero": "true",
        "debug_seed": "",
        "trace_enabled": "false",
        "debug_usage": "false",
        "api_timeout": "30",
        "api_round_max": "120",
        "api_stall_max_retries": "2",
        "permission_mode": "auto",
        "allowed_tools": ""
    },
    "memory_palace": {
        "enable_v9": true,
        "llm_enabled": false,
        "base_url": "https://api.anthropic.com",
        "api_key": "your-api-key-here",
        "model": "claude-haiku-4-5"
    },
    "memory_quality": {
        "min_store_importance": 0.4,
        "min_recall_score": 0.35,
        "dedup_threshold": 0.3
    },
    "compact": {
        "inline_trigger": 0.8,
        "inline_keep_ratio": 0.4,
        "idle_trigger": 0.5,
        "idle_keep_ratio": 0.4,
        "max_summary_tokens": 4096,
        "auto_recall_clear": false
    }
}

`factories` — API 供应商

字段	类型	说明
`base_url`	string	API 端点 URL
`api_key`	string	认证密钥
`options`	string[]	该供应商下可用的模型名称列表

`llm` — 模型与上下文行为

字段	类型	默认值	说明
`default_model`	string	`claude-sonnet-4-6`	启动时使用的默认模型
`default_effort`	string	`high`	默认推理力度（`low` / `medium` / `high`）
`max_contexts`	int	`5`	最大并行上下文数量，超出后 LRU 淘汰
`resume_latest_context`	bool	`false`	`true`：重启恢复上次活跃上下文；`false`：每次启动新上下文
`options`	array	—	各模型支持的推理力度等级
`thinking_budget_*`	string	—	各推理力度下的思考 token 预算

`env` — 运行时设置

字段	类型	默认值	说明
`persona_name`	string	`niuma`	助手显示名称
`model_background`	string	`claude-haiku-4-5`	后台任务模型（recall 评分、摘要等）
`temperature_zero`	string	`true`	强制 temperature=0 以获得确定性输出
`api_timeout`	string	`30`	HTTP 请求超时（秒）
`api_round_max`	string	`120`	单次会话最大对话轮数
`api_stall_max_retries`	string	`2`	API 响应停滞时重试次数
`permission_mode`	string	`auto`	工具权限模式（`auto` / `ask` / `allow`）
`allowed_tools`	string	`""`	工具白名单，逗号分隔（空字符串=全部允许）

`memory_palace` — 记忆系统

字段	类型	默认值	说明
`enable_v9`	bool	`true`	启用 session 启动时记忆召回
`llm_enabled`	bool	`false`	使用 LLM 进行记忆分析（需额外 API key）
`base_url`	string	—	记忆分析 LLM 端点（启用时填写）
`api_key`	string	—	记忆分析 LLM 密钥（启用时填写）
`model`	string	`claude-haiku-4-5`	记忆分析使用的模型

`memory_quality` — 记忆质量阈值

字段	类型	默认值	说明
`min_store_importance`	float	`0.4`	最低重要性分数，低于此值不存储
`min_recall_score`	float	`0.35`	最低召回分数，低于此值不出现在召回结果中
`dedup_threshold`	float	`0.3`	语义相似度阈值，超过则视为重复记忆

`compact` — 上下文压缩

字段	类型	默认值	说明
`inline_trigger`	float	`0.8`	上下文填充达到此比例时触发内联压缩
`inline_keep_ratio`	float	`0.4`	内联压缩后保留的比例
`idle_trigger`	float	`0.5`	空闲达到此比例时触发空闲压缩
`idle_keep_ratio`	float	`0.4`	空闲压缩后保留的比例
`max_summary_tokens`	int	`4096`	生成摘要的最大 token 数
`auto_recall_clear`	bool	`false`	压缩后自动清除 recall 结果

下一步

harness — 自主对话 — 了解默认自主模式
loop — 工程化编排 — 目标驱动的任务执行
并行上下文管理 — 同时处理多个任务