Alkaid0 是一个模块化的 AI Coding 工具 与 Agent 框架，专为构建具备多 Agent 能力、工具调用系统和流式响应处理功能的智能编码助手而设计。该框架基于 Go 语言构建。
设计理念：低消耗 用户友好 可扩展 强兼容性
- 多 Agent 架构：支持主 Agent 与子 Agent（Subagent）嵌套调用，子 Agent 可独立绑定路径和作用域
- 沙箱安全执行：内置沙箱隔离机制，Linux 使用 mount namespace，Windows 使用 DACL + 受限令牌
- 会话管理：支持会话断连延迟释放（保留上下文，断线可重连恢复）、后台运行模式
- 自动审批规则：基于 expr 表达式引擎，支持细粒度工具调用自动审批/拒绝
- 测试覆盖：持续提升测试覆盖率，集成 mock 服务器测试
# Linux
curl -sSL https://alk.cxykevin.top/i.sh | bash# Windows
irm https://alk.cxykevin.top/i.ps1 | iex路径 ~/.config/alkaid0/log.log (直接启动二进制文件) / /var/log/alkaid0/log.log (Linux 系统级别安装) / C:\ProgramData\alkaid0\config.json (Windows 系统级别安装)
日志经过脱敏处理（脱去 Provider URL / KEY），但会保留请求的 Model ID 和 Agent Name 以及完整输入输出。日志不会携带工作区信息但 AI 模型的输出可能会包含部分用户代码。
提供 toolkit 包以查看日志。用法见其 --help。
路径
# 从二进制文件启动
~/.config/alkaid0/config.json
# Linux 软件包安装版本
/etc/alkaid0/config.json
# Windows 软件包安装版本
C:\ProgramData\alkaid0\config.json{
"$schema": "https://raw.githubusercontent.com/cxykevin/alkaid0/refs/heads/main/docs/schemas/config.json",
"Version": 1,
"ThemeID": 0,
"Model": {
"ProviderURL": "https://openrouter.com/api/v1(这里没用)",
"ProviderKey": "sk-or-xxx(这里没用)",
"DefaultModelID": 1,
"Models": {
"0": {
"ModelName": "模型名",
"ModelID": "模型ID",
"ModelDescription": "模型描述（可选）",
"ModelAddPrompt": "附加系统提示词（可选）",
"ModelTopP": -1,
"ModelTopK": -1,
"ModelTemperature": -1,
"TokenLimit": 8192,
"ProviderURL": "https://模型供应商/v1",
"ProviderKey": "sk-模型密钥",
"EnableThinking": true,
"CompressSize": 128000,
"Hide": false,
"Type": "",
"ProviderSpecificConfig": {
"EnableDeepseekThinking": false,
"EnableReasoningEffort": true,
"EnableTopP": false,
"EnableTopK": false,
"EnableTemperature": false,
"EnableUsage": true,
"EnableToolCallingCompat": false,
"Dimension": 0
}
},
"1": {
"ModelName": "embedding模型名",
"ModelID": "embedding模型ID",
"ProviderURL": "https://模型供应商/v1",
"ProviderKey": "sk-模型密钥",
"EnableThinking": true,
"Hide": true,
"Type": "embedding",
"ProviderSpecificConfig": {
"Dimension": 1024
}
}
}
},
"Agent": {
"Agents": {
"frontend": {
"AgentName": "前端工程",
"AgentDescription": "前端工程Agent",
"AgentShortDescription": "擅长前端开发的前端工程Agent",
"AgentPrompt": "你是一个前端工程师，请根据用户的需求，提供前端工程解决方案。",
"AgentModel": 0,
"AutoApprove": "",
"AutoReject": "",
"DisableSandbox": false
}
},
"IgnoreBuiltinAgents": false,
"GlobalPrompt": "始终使用中文回答",
"SummaryModel": 0,
"MaxCallCount": 50,
"AutoApprove": "",
"AutoReject": "",
"IgnoreDefaultRules": false,
"DisablePromptPreprocess": false,
"UseShell": "",
"TerminalEnvs": {
"LANG": "zh_CN.UTF-8"
},
"Fetch": {
"RewriteHeaders": {
"https://api\\.example\\.com/.*": {
"Authorization": "Bearer sk-xxx"
}
}
},
"DisableSandbox": false
},
"ignoreSignals": false,
"Context": {
"LSP": {
"Enabled": false,
"IdleTimeout": 600,
"LanguageServers": {
".go": {
"Command": "gopls",
"Args": []
}
}
},
"EmbeddingModelID": 1,
"SearchSummaryModel": 0,
"OnlineSearch": {
"timeout": 30,
"proxy_url": "",
"retry_count": 3,
"bing": {
"enable": true,
"min_delay": 2,
"max_delay": 5,
"max_results": 10
},
"github": {
"enable": false,
"token": "ghp_xxx",
"max_results": 5
},
"arxiv": {
"enable": false,
"max_results": 5
},
"tavily": {
"enable": false,
"api_key": "tvly-xxx",
"search_depth": "basic",
"include_answer": false,
"include_raw_content": false,
"max_results": 10
},
"context7": {
"enable": false,
"api_key": "",
"max_results": 5
},
"zread": {
"enable": false,
"locale": "zh",
"max_results": 5
},
"brave": {
"enable": false,
"api_key": "BSA-xxx",
"safesearch": "moderate",
"max_results": 10
},
"test": {
"enable": false
},
"grepapp": {
"enable": false,
"max_results": 10
},
"sourcegraph": {
"enable": false,
"token": ""
},
"stackoverflow": {
"enable": false,
"api_key": ""
},
"hackernews": {
"enable": false
},
"devto": {
"enable": false
},
"libraries_io": {
"enable": false,
"api_key": ""
}
},
"Codebase": {
"BM25Weight": 0.7,
"VectorMinSimilarity": 0.5,
"BM25RetentionScore": 0.0
}
},
"Server": {
"Key": "<你的 websocket key>",
"Path": "/acp",
"Host": "127.0.0.1",
"Port": 7433,
"DisableStdioServer": false,
"SessionTimeout": 60
},
"Feedback": {
"DisableAutoTelemetry": false
}
}支持通过 RPC 方法 alk.cxykevin.top/config/get 和 alk.cxykevin.top/config/set 远程读取和修改配置，方便客户端集成。
配置完上述 json 后直接启动主程序，服务端会在 ws://<host>:<port>/<path> 开启一个 websocket 服务。此时服务端同时会启动一个标准的 stdio 服务器便于调试。
服务端使用 Query 参数认证。在 Query 参数中添加 key=<key> 即可。如果没有 Query 参数选项，则可以在 Path 中设置 /acp?k=<key>。
支持 Websocket 桥接的客户端可以直接链接。只支持 stdio 的客户端可以使用提供的 helper 链接。
目前 helper 只支持
ws，不支持wss。
可以通过 ./可执行文件 acp 启动服务端内置 helper。如果你需要轻量化部署并链接到远程，则可以使用单独的 helper 可执行文件并不带任何参数启动。如果你使用 go install 安装，则服务器绑定到了 alkaid0，单独的 helper 可以使用 alk 命令。
helper 会自动读取本机的 ~/.config/alkaid0/config.json 并自动链接，一般本机无需再次手动配置 key。
如果你需要链接到远程或自动链接无效，可以使用以下参数：
-config配置文件路径-host服务器的 host-port服务器的 port-path服务器的 path-key服务器配置的 websocket key
如果你无法链接请检查是否在服务端和客户端都设置了
Key。服务端不允许空key启动（stdio 服务器正常工作）。如果内置的 stdio 导致服务器自动退出或其它问题，则可在
config.json中设置DisableStdioServer为true以禁用。
支持会话断连延迟释放——客户端断开后会话不会立即销毁，保留上下文状态，允许客户端重新连接后恢复。同时支持后台运行模式，适合长时间执行的命令或任务。
网络请求采用指数退避重试机制，最多重试 3 次。当 LLM Provider 返回临时性错误时自动重试，提升系统稳定性。
命令执行 PTY 实现：
- Linux：
/dev/ptmxPTY - macOS：基于
openpty - Windows：管道透传 (ConPTY 无法正确在 Service 中工作)
| 平台 | 隔离机制 |
|---|---|
| Linux | mount namespace + 挂载隔离 |
| Windows | 作业对象（Job Object）+ 令牌限制（Token Restrictions） |
| macOS | 暂无 |
支持动态创建、管理子 Agent（Subagent）：
- 每个子 Agent 可绑定特定工作路径、模型、提示词
- 支持独立的作用域（Scope）控制
- 子 Agent 可自动审批规则独立配置，未配置时回退到全局默认
/background (on|off): 切换后台运行模式，断连后保持会话存活/compress: 压缩上下文历史/feedback <反馈内容>: 提交反馈到反馈服务端/help: 显示命令帮助（无参数）/index [clean|status|cancel|lsp-reset]: 构建代码库索引（提取 LSP 符号 → 提交 embedding 任务）；子命令：clean清库、status显示进度、cancel停止、lsp-reset重置 LSP 失败计数/init: 分析代码库并生成 AGENTS.md 指导文件（无参数）/mask add <值>|del <值>: 管理自定义脱敏值，add出站脱敏并在响应中还原，del停止脱敏/reload: 从磁盘重载配置（无参数）/s [short]: 发送已配置短语，/s <short>展开并发送，/s（无参数）列出所有短语/title [标题]: 设置会话标题，无参数时回退到 AI 生成标题/version: 显示版本信息（无参数）
在会话中输入 /feedback <反馈内容> 即可将反馈提交到反馈服务端（feederback），并附带最近 60KB 日志与系统信息。反馈完成后会返回反馈 ID。
程序会每 30 天自动上报一次使用信息。
采集内容：
- 版本号、构建 commit、Go 版本
- 操作系统与架构
- 配置中使用的模型 ID
不采集：
- 对话内容、工作区代码
- 日志文件内容
- 配置中的密钥
如何关闭：
在 config.json 中设置：
{
"Feedback": {
"DisableAutoTelemetry": true
}
}alkaid0 实现 ACP v2 协议（protocolVersion: 2），并对 ACP 做私有扩展。详见 docs/acp/extension.md 与 docs/acp/fs.md。
自动审批规则使用 github.com/expr-lang/expr 实现。这是一个轻量级的表达式语言，支持 C 风格的基本的逻辑运算和函数调用。
- 全局：
Agent.AutoApprove/Agent.AutoReject - Subagent：
Agent.Agents.{subagent}.AutoApprove/Agent.Agents.{subagent}.AutoReject - 规则空字符串表示不启用；Subagent 为空时会回退到全局默认。
- Reject 优先：命中 AutoReject 直接拒绝，即使同时命中 AutoApprove。
- Approve 需全需：所有 ToolCall 都命中 AutoApprove 才批准。
- 程序内置了一套规则，AutoReject 和 AutoApprove 均取或的关系。
AgentsConfig.IgnoreDefaultRules设置为 true 后，全局默认规则不生效。除非你明确知道自己在做什么，否则不建议设置该字段。
ToolCalls：完整的[]ToolCallArrayToolCall：当前工具调用（单个）Agent：当前 Agent 配置
ToolCall 结构：
ToolCall.NameToolCall.IDToolCall.Parameters（map[string]*any，即 json 中Object）
regex(pattern, text)正则匹配contains(s, sub)字符串包含hasParam(call, key)参数存在param(call, key)参数值
AutoApprove: "ToolCall.Name == 'read'"
AutoReject: ""
AutoReject: "contains(ToolCall.Name, 'run') && regex('rm\\s', param(ToolCall, 'command'))"
AutoApprove: "ToolCall.Name == 'run' && (contains(param(ToolCall,'command'), 'git status') || contains(param(ToolCall,'command'), 'git diff'))"
AutoReject: "hasParam(ToolCall, 'path') && regex('^/etc', param(ToolCall, 'path'))"