AgentGo

AgentGo

AgentGo 让 AI 助手可以在你的电脑上运行 Codex 和 Claude Code。它是一个 MCP 服务：MCP 客户端连接后，助手就能查看你授权的项目，把编码任务交给 Codex 或 Claude Code，跟进任务进度，并读取结果。

AgentGo 运行在存放代码以及已登录的 codex 和 claude CLI 的电脑上，并通过 Cloudflare 隧道对外提供服务，因此助手可以从任何地方访问它：无论是云端 Agent、手机还是另一台笔记本电脑。

请先阅读。 这些 Agent 会以你的身份运行，使用你的文件、登录凭据和 git 凭据，并自行批准操作。任何拿到 AgentGo 密码的人都能让它们做任何你能做的事。只把密码交给你愿意让其使用键盘的客户端，并且只添加你愿意让 Agent 自由操作的项目。

我为什么要构建它

我受够了 Codex 的远程连接和远程设备设置。我始终没能让它稳定运行，即便能用，速度也太慢。AgentGo 就是我对此的解决方案。

所需条件

• macOS 或 Linux，且安装了 Node.js 24.13 或更高版本。AgentGo 使用 Node 内置的 SQLite，它目前仍会输出“experimental”警告。
• 已安装并登录 codex、claude，或两者都已安装并登录。AgentGo 使用你现有的登录凭据，绝不会索要 API 密钥。已通过 Codex 0.160.1 和 Claude Code 2.1.291 测试。
• PATH 中有 ripgrep（rg），用于文件搜索工具。macOS 上可运行：brew install ripgrep。
• 用于建立隧道的 cloudflared。如果没有，AgentGo 可以为你下载（见下文）。
• 支持 Streamable HTTP 传输并允许设置 Authorization 标头的 MCP 客户端。

开始使用

安装 CLI，并检查所需的一切是否就绪：

npm install -g agentgo-mcp
agentgo doctor

这会安装两个命令：agentgo 和 agentgo-mcp。它们的作用相同；本文档使用 agentgo。

doctor 会显示是否已安装 codex、claude、rg 和 cloudflared，以及你是否已登录各个 Agent。

接下来，告诉 AgentGo 你的项目所在位置。将它指向项目所在的文件夹，其中的每个文件夹都会成为 Agent 可以操作的一个工作区：

agentgo workspace add-folder ~/code

每个工作区都以其文件夹命名，因此 ~/code/my-app 会成为 my-app（空格和其他特殊字符会转换为连字符）。之后创建的项目会自动显示，隐藏文件夹则会跳过。要添加位于其他位置的单个项目，可以自行指定名称：

agentgo workspace add notes ~/Documents/notes

agentgo workspace list 会显示 Agent 可以看到的内容，agentgo workspace remove <name or folder> 则会移除指定项目。更改会立即生效，即使服务正在运行也一样。

然后启动服务：

agentgo start

这会在后台启动 AgentGo 和 Cloudflare 隧道，然后输出 MCP URL 及需一并发送的标头：

MCP URL:       https://<random-words>.trycloudflare.com/mcp
Header name:   Authorization
Header value:  Bearer <password>

将两者添加到 MCP 客户端中。请包含 Bearer 一词及其后的空格。

首次运行 start 时会创建密码，之后会重复使用。服务运行期间再次运行 start，只会再次打印密码。要更换密码，请运行 agentgo token rotate；旧密码会立即失效。

如果尚未安装 cloudflared，start 会停止并提示你。你可以自行安装（macOS 上运行 brew install cloudflared），也可以运行 agentgo start --yes，让 AgentGo 从 GitHub 下载官方版本并根据其公布的校验和进行验证。如果 cloudflared 位于不常见的位置，请传入 --cloudflared <path>。

管理服务

agentgo status
agentgo stop
agentgo restart

更改工作区、模型或设置后，无需重启；服务会在收到下一个请求时应用更改。停止服务会中断正在进行的所有运行。已做出的更改会保留，但不会自动撤销或恢复运行。

如果服务无法启动，其日志位于 ~/.agentgo/daemon.log。

从脚本调用命令时，可添加 --json。密码位于 token 字段中。

一个稳定的地址

默认情况下，你会获得 Cloudflare Quick Tunnel。它不需要 Cloudflare 账户， 但每次隧道启动或重新连接时，URL 都会变化。如果你在 Cloudflare 上有域名， 可以改用固定地址：

agentgo stop
agentgo start --custom-domain-with-cf agents.example.com

如果 cloudflared 尚未登录你的 Cloudflare 账户，这会打开浏览器供你登录。随后，AgentGo 会在你的账户中创建隧道（或复用之前创建的隧道），并为该主机名添加 DNS 记录。它不会覆盖已有的 DNS 记录。

如果你希望在 Cloudflare 控制面板中管理隧道，请将其公共主机名指向 http://127.0.0.1:8765，将隧道令牌保存到文件中，然后运行：

agentgo start --tunnel-token-file ~/tunnel-token --hostname agents.example.com --port 8765

start 会记住上次启动时的方式，因此之后调用 start 和 restart 时会复用同一条隧道。传入 --quick 可切回 Quick Tunnel，传入 --local 则会在 127.0.0.1 上监听，完全不使用隧道。

如果隧道断开，AgentGo 会在后台重新连接。正在进行的运行不会受到影响。

仅本地，通过 stdio

如果你的 MCP 客户端运行在同一台计算机上，也可以直接启动 AgentGo：

{
  "mcpServers": {
    "agentgo": {
      "command": "agentgo",
      "args": ["stdio"]
    }
  }
}

此模式下没有隧道或密码。运行仅在客户端保持 AgentGo 开启期间持续：客户端断开连接时，正在进行的运行会中断。

stdio 服务和后台服务不能同时使用同一个状态目录。请先停止后台服务，或者通过 "args": ["stdio", "--state-dir", "/path"] 为 stdio 服务指定独立目录，并使用相同的 --state-dir 将工作区添加到该目录中。

助手能做什么

AgentGo 为助手提供 13 个工具。

查找文件。 这些工具直接读取文件，不会启动 Agent。

工具	功能
listWorkspaces	列出你已添加的项目
listDirectory	列出目录中的文件和文件夹
readFile	读取文本文件中的行
globFiles	按名称模式查找文件，例如 src/**/*.ts
grepFiles	使用 ripgrep 搜索文件内容

运行 Agent。

工具	功能
getAgentCapabilities	显示已安装的 Agent 及其版本
getSupportedModels	列出每个 Agent 接受的模型、工作量级别和服务层级
startAgentRun	在工作区中为 Codex 或 Claude Code 分配任务
getAgentRunStatus	检查运行是排队中、进行中还是已完成
getAgentRunOutput	查看 Agent 的发言、操作和最终答复
listAgentRuns	列出过去和当前的运行
cancelAgentRun	停止运行
continueAgentSession	在同一对话中向已完成的运行发送后续内容

助手启动的运行如下所示：

{
  "provider": "codex",
  "model": "gpt-6.1-sol",
  "effort": "high",
  "serviceTier": "priority",
  "workspaceId": "my-app",
  "prompt": "Fix the failing tests and explain what was wrong.",
  "idempotencyKey": "fix-tests-1"
}

它会立即返回 taskId 和 sessionId。然后，助手会轮询 getAgentRunStatus，并使用 getAgentRunOutput 读取结果。要跟进，助手会使用 sessionId 和新的提示词调用 continueAgentSession。

以下几点值得注意：

• Agent 会审核自己的操作。 Codex 使用其 workspace-write 沙箱和自动审核器（auto_review）运行。Claude Code 则在自动模式下运行，并关闭权限提示。它们的审核器仍可能拒绝某项操作。运行期间没有人可以回答问题，因此如果 Codex 请求输入，运行会以 INPUT_REQUIRED 失败。无法完全绕过权限。
• 浏览工具受限；Agent 不受这些限制。 readFile、grepFiles 等工具只能在工作区内操作，不会跟随符号链接，并会拒绝访问 .env、.ssh、.aws、.git、.npmrc 和私钥等机密内容。Agent 只受自身沙箱和审核器限制，因此可以读取和运行它们允许的任何内容。
• 搜索会跳过依赖项和构建输出。 globFiles 和 grepFiles 每次只搜索一个工作区，最多搜索 100,000 个文件。它们会遵循 .gitignore，跳过隐藏文件，以及 node_modules、vendor、dist、build、target、.venv 和 __pycache__ 等文件夹，无论这些文件夹出现在哪里。listDirectory 和 readFile 仍可打开这些内容。
• 不会猜测模型。 助手应先调用 getSupportedModels。Codex 会报告自己的列表。对于 Claude，AgentGo 默认提供 sonnet 和 opus 别名，以及低、中、高工作量；可使用 agentgo model add claude-sonnet-5-5 --efforts low,medium,high,xhigh,max 添加其他模型。未知模型、工作量级别或服务层级都会报错，不会静默替换。使用 Claude 时，不要填写 serviceTier。
• 最多同时运行五项任务。 它们可以位于不同或相同的工作区。同一工作区中的 Agent 互不了解，因此请为并行运行分配不同的代码部分。额外的运行会排队等待。
• 重试不会启动第二项运行。 每项运行都有一个 idempotencyKey。如果助手使用相同的键和参数重试，就会获取原来的运行。使用相同的键但不同的参数会报错。
• 运行有时间限制。 默认限制为 30 分钟；除非助手通过 limits.wallTimeSeconds 请求更长时间，否则最长为一小时。
• succeeded 表示 Agent 已完成。 这不代表测试通过或更改正确。
• 助手能看到 Agent 显示的内容。 运行输出包含 Agent 的消息及其使用的工具。对于 Codex，还包含它运行的命令、命令输出和修改的文件。不包含隐藏推理。 如果 Agent 打印了它读取到的机密内容，这些内容也会出现在输出中。

AgentGo 将状态保存在何处

所有内容都存放在 ~/.agentgo 中：你的工作区和设置、密码、 隧道设置、运行历史记录、服务器日志，以及 AgentGo 下载的 cloudflared。使用 --state-dir 或 AGENTGO_HOME 环境变量可将其 放到其他位置。工作区不能位于其中，也不能包含它。

运行历史记录会保留 30 天。此后，提示词和输出会被删除， 但每次运行的小型记录会保留下来，因此即使很久之后重试，也无法再次启动 它。Codex 和 Claude Code 会分别保留自己的对话历史记录，AgentGo 不会触碰这些记录。

如果服务器意外停止，下次启动时，正在进行的运行会被标记为 interrupted。它们绝不会自动重新运行；请检查工作区中未完成的更改，并在需要时 自行继续会话。

Agent 不会继承你的全部环境变量。它们会获取 PATH、HOME、区域设置、 代理设置，以及 Codex 和 Claude Code 用于登录的变量 （OPENAI_*、ANTHROPIC_*，以及 AWS、Google 和 Azure 的相关变量）。AgentGo 密码绝不会传递给它们。

agentgo config show 会打印当前设置。你可以在 ~/.agentgo/config.json 中更改这些设置：

设置	默认值	控制内容
maxConcurrentRuns	5	可同时运行的任务数（最多 8 个）
maxQueuedRuns	100	可在队列中等待的任务数
maxRunSeconds	3600	运行可请求的最长时限
maxRunOutputBytes	10 MiB	运行可生成的输出量上限，超过后将停止
retentionDays	30	提示词和输出的保留时间
searchExclude	node_modules、dist、…	搜索时跳过的文件夹和文件名（config show 会列出所有名称）
codexPath、claudePath、rgPath	codex、claude、rg	各程序的位置

将其用作库

npm install agentgo-mcp

connectAgent 会为正在运行的 AgentGo 服务器提供一个类型化客户端：

import { connectAgent } from 'agentgo-mcp';

const agent = await connectAgent({
  mcpConnectionURL: process.env.AGENTGO_URL!,
  token: process.env.AGENTGO_PASSWORD!,
});

try {
  const run = await agent.startAgentRun({
    provider: 'codex',
    model: 'gpt-6.1-sol',
    effort: 'high',
    workspaceId: 'my-app',
    prompt: 'Fix the failing tests and explain what was wrong.',
    idempotencyKey: 'fix-tests-1',
  });

  let status = await agent.getAgentRunStatus(run.taskId);
  while (status.pollAfterMs) {
    await new Promise(resolve => setTimeout(resolve, status.pollAfterMs!));
    status = await agent.getAgentRunStatus(run.taskId);
  }

  const output = await agent.getAgentRunOutput(run.taskId);
  console.log(status.status, output.result?.text);
} finally {
  await agent.close();
}

URL 必须使用 HTTPS，但 localhost 除外。每个工具也都可以通过 agent.call(name, args) 调用。若要改用 stdio 连接，请传入 { transport: new StdioClientTransport({ command: 'agentgo', args: ['stdio'] }) }， 并从 @modelcontextprotocol/client/stdio 导入 StdioClientTransport。

该包还导出了构建 CLI 所用的组件：

• start、stop、status 和 restart 的功能与相应命令相同。 start({ downloadCloudflared: true }) 会返回 MCP URL 和 token。
• serveAgentStdio({ stateDir }) 会从你自己的进程通过 stdio 提供服务。
• AgentService.create({ stateDir }) 会加载工作区和运行历史记录。 createAgentMcpServer(service) 会将其封装为 MCP 服务，你可以为其连接 自己的传输方式；createAgentHttpServer({ service, token }) 则会在 127.0.0.1 上通过 HTTP 提供服务，并进行密码检查。

开发 AgentGo

克隆此仓库后：

npm install
npm test
npm run typecheck

npm test 会先进行构建。测试使用模拟的 codex、claude 和 cloudflared 程序，因此不会产生费用，也不会触及 Cloudflare。测试 要求 PATH 中有 rg。

此外，还有针对真实程序的冒烟测试：

npm run smoke:providers -- codex
npm run smoke:providers -- claude
npm run smoke:tunnel

smoke:providers 会在临时文件夹中运行两次简短的真实对话，检查 Agent 是否能编辑文件并记住对话。它会使用你平时的 Codex 或 Claude 用量。 smoke:tunnel 会启动一个真实的 Quick Tunnel，并检查经过身份验证的客户端 能否通过它访问 AgentGo，而不会运行 Agent。添加 -- --yes 即可允许其下载 cloudflared。

发布版本

AgentGo 以 agentgo-mcp 的名称发布到 npm，并通过 server.json 列入 MCP Registry。 你需要登录 npm（npm login）和注册表 （使用官方 mcp-publisher CLI 执行 mcp-publisher login github）。

首先，将 server.json 中的两个 version 字段都设置为即将发布的版本。然后，在仓库根目录运行：

git add -A && git commit -m "Describe the release"
npm version minor          # or patch; must match the version in server.json
git push --follow-tags
npm publish
npm view agentgo-mcp@<version> version   # wait until this shows up
mcp-publisher publish

npm pack --dry-run 会显示发布前将包含在包中的内容。 npm publish 会先构建软件包。

npm publish 成功后，npm 可能需要几分钟才会列出新版本。等待期间不要再次发布；npm 会拒绝上传相同版本。若在版本显示之前运行 mcp-publisher publish，会因“version not found”而失败，因此请等待 npm view 显示该版本。

Codex 和 Claude Code 条款

AgentGo 并非由 OpenAI 或 Anthropic 制作，也与它们无关联。它会运行你已安装的 codex 和 claude 程序，不会对其进行修改；这些程序使用你已设置好的登录信息。AgentGo 绝不会处理或存储这些登录信息。

OpenAI 和 Anthropic 的条款仍适用于 Agent 执行的所有操作，因此：

• 仅供个人使用。 将 AgentGo 密码交给他人，会让对方使用你的 Codex 和 Claude 账户，而这违反了两家公司的条款。
• 订阅仅供普通个人使用。 如果你要大量运行 Agent 或让它们无人值守地运行，请使用 API 密钥登录 CLI。

许可证

MIT。部分 Cloudflare 托管、存储和 HTTP 代码改编自 PrintGo；详见 NOTICE。