base44-remote-dev

通过 MCP 远程开发 Base44 应用

将自己的编码 Agent 连接到 Base44 应用的沙盒，直接在其中开发——运行命令、读取和编辑文件、搜索内容、列出目录——由 Base44 提供沙盒，由你提供 Agent 和大模型。

这适用于任何支持 MCP 的客户端。示例使用 Claude Code。

**最简单的开始方式：**在 Base44 应用编辑器中，点击 Send to Coding Agent。对于本地 Agent，它会提供一段可直接粘贴的提示词（用于获取 README，并通过 MCP 或 base44 sandbox CLI 操作沙盒——见第 10 节）； 对于 Web，它会提供一段提示词，可粘贴到 claude.ai 聊天中（需使用 Base44 MCP 连接器），并附带一个 Open Claude 按钮。该按钮是发现入口——本指南其余部分则是参考资料。

**两种传输方式：**Web Agent 使用 claude.ai 和 Base44 MCP 连接器（第 1–9 节）——请注意，这是常规的 claude.ai 聊天，不是 Claude Code 网页版（claude.ai/code），后者运行在自己的、基于代码仓库的沙盒中。本地 Agent 可以连接同一个 MCP 服务，也可以使用 base44 sandbox CLI 操作沙盒（需要 Base44 CLI 令牌，见第 10 节）——工具、行为和错误代码都相同；CLI 只是使用更短的命令名称来调用它们（sandbox read、sandbox ls 等）。

---

1. 连接 MCP 服务

Base44 MCP 端点：

https://app.base44.com/mcp

使用 Claude Code 注册（可从任意文件夹运行）：

claude mcp add --transport http base44 https://app.base44.com/mcp

如果希望在每个项目中都能使用，而不只是当前文件夹，请添加 --scope user。

claude mcp add 只会写入配置——不会进行身份验证。

2. 身份验证

启动 Claude Code 并打开 MCP 菜单：

claude

然后，在 Claude Code 中：

/mcp

选择 base44 → Authenticate。浏览器会打开 Base44 OAuth 流程（PKCE）——登录并批准。成功后，/mcp 会显示 base44 已连接，并列出其工具。

无法打开浏览器的纯 CLI／无头客户端会改用 OAuth 设备授权流程（/oauth/device/code）——请求授权码，在另一台设备的浏览器中批准，然后客户端会收到令牌。

权限范围

工具	所需权限范围
read_file、grep、list_directory、list_user_apps	apps:read（默认授予）
write_file、edit_file、run_command、create_checkpoint	sandbox:write

默认不会授予 sandbox:write——执行 Shell 命令和修改文件需要显式授予此权限。如果读取工具可以正常工作，但修改工具返回 NOT_AUTHORIZED，说明你的令牌缺少 sandbox:write；请重新连接并授予沙盒访问权限（设备授权流程可以显式请求此权限）。

---

3. 选择应用并熟悉环境

每个工具都需要提供 appId。使用 list_user_apps 查找你的应用，然后在请求中固定该 ID，确保 Agent 每次调用时都会传入它。

先以只读方式开始，在修改任何内容之前建立整体认知：

Using the base44 tools on appId <APP_ID>:
1. list_directory on the app root (recursive, depth 2)
2. read_file src/App.jsx and src/pages.config.js
3. grep for the component I want to change
Summarize the structure before editing.

**冷启动：**如果应用没有正在运行的沙盒，首次调用工具时会自动根据最近一次提交启动沙盒——只是会花费较长时间。之后的调用会很快。

**CLI 命令名称：**通过 base44 sandbox CLI（第 10 节）使用时，这些读取工具对应的命令为：list_directory → sandbox ls、read_file → sandbox read，以及 grep → sandbox grep。

---

4. 进行更改

• edit_file（CLI 中的 sandbox edit）——更改现有文件时首选。提供精确的 old_text→new_text 编辑。除非设置了 replace_all，否则每个 old_text 在文件中必须唯一。 一次调用中的所有编辑会原子地应用（要么全部成功，要么全部不应用），并返回统一差异。设置 dry_run: true 可在不写入的情况下预览差异。
• write_file（CLI 中的 sandbox write）——用于创建新文件。要覆盖现有文件，必须传入 overwrite: true（不会静默覆盖）。
• run_command（CLI 中的 sandbox run）——在沙盒中运行任意 bash 命令（构建、安装、 脚手架、codemod）。工作目录默认为应用根目录；跨调用的 cd 不会保留，因此请使用 cwd 参数或串联命令（cd sub && cmd）。默认超时时间为 120 秒（最长 600 秒）；输出上限约为 1 MB。
• create_checkpoint（CLI 中的 sandbox checkpoint）——在构建器的版本历史中保存一个还原点。可选传入 name （消息/标题；如省略则自动生成——简短概述更改内容，便于用户选择正确的版本）。所有待处理的更改都会先刷新并提交， 确保检查点锚定到最新代码；随后会返回检查点 ID、名称和 git 提交哈希。完成一项工作后必须调用，并且停止前务必调用——关于未创建检查点的工作可能被回滚的原因，请参见第 6 节。（如果尚无法确认最近的自动提交已持久化，该操作会返回可重试的 COMMIT_FLUSH_PENDING，而不会为过时状态创建检查点——稍后重试。）

示例：

On appId <APP_ID>, use edit_file to change the homepage heading in
src/pages/Home.jsx from "Welcome" to "Welcome back". Show me the diff first
with dry_run, then apply it.

---

5. 预览和验证（编辑 → 检查循环）

没有实时日志流工具，但你可以闭合反馈循环：

• 实时查看：GET /api/apps/{app_id}/sandbox/preview-url 会启动开发服务器并返回预览 URL。Vite HMR 会在你进行编辑时反映更改。409 表示应用代码当前无法构建。

• 构建状态：GET /api/apps/{app_id} 会将 status.state 返回为 ready / processing / error。

  两者都是平台 API 操作，而不是沙盒工具。通过 MCP 调用时，请使用 execute_api。直接通过 REST 调用时，需要个人 API 密钥。 工作区 API 密钥会被拒绝。

• 按需查看构建/类型检查/lint 错误，使用 run_command：

  npm run build       # bundler/compile errors
  npx tsc --noEmit    # type errors
  npm run lint        # lint errors
  

• 读取开发服务器（Vite）日志——托管的开发服务器会将日志写入 /tmp/vite.log。通过 run_command 执行 tail 来查看 HMR/编译错误：

  tail -c 32000 /tmp/vite.log
  

  （该路径位于应用目录树之外，因此只能通过 run_command 访问， 不能通过文件工具访问——因此需要 sandbox:write。）

可靠的循环：edit_file → npm run build（或 tail /tmp/vite.log）→ 修复任何 错误 → 打开预览 URL 查看效果。

浏览器运行时错误（能够编译但在渲染时抛出错误的组件、 失败的客户端 API 调用）会出现在浏览器控制台中，而不是 /tmp/vite.log。打开预览 URL 即可发现这些错误。

---

6. 更改如何持久化

你无需“保存”。每次更改内容的调用都会安排一次防抖自动提交（约 5 秒后）：更改会提交并推送到 Base44 的代码存储，因此：

• 即使沙盒终止，更改也会保留（沙盒会根据最近一次提交重新创建）；
• 更改会显示在构建器的 Library/Data 选项卡中；
• 后端函数部署会保持一致；并且
• 发布应用时也会包含这些更改。

实际影响：

• 存在一个很短的丢失窗口（约 5 秒）——最后一次编辑后不要立即终止会话；稍等片刻，让更改完成提交。
• 提交不是检查点。 只有检查点会显示在构建器的版本历史记录中。当用户在较早的版本上点击 Restore，或在构建器消息上点击 Revert this 时，应用代码会回滚到该检查点对应的提交，且上一个检查点之后写入的所有内容都会被丢弃，无法通过恢复点找回。完成一个工作单元时，以及停止之前，务必调用 create_checkpoint（sandbox checkpoint），这样用户下次恢复时才能回到你的工作，而不是将其抹去。
• 对实体、Agent、工作流、后端函数和页面路由所做的编辑会在提交后自动同步到 Base44。纯页面、组件和 CSS 编辑保存在 git 中，无需其他操作。

---

7. 并发：你与 Base44 构建器

你和应用内的 Base44 构建器不能同时修改同一个应用：

• 你正在使用沙盒工具时，Base44 构建器聊天会被阻止（“An external agent is currently working on this app”）。你的会话是隐式的——最近的工具调用就是会话；短暂空闲一段时间（约 10 分钟）后，会话结束。
• 如果 Base44 构建器正在构建，你的更改工具会返回 BUILDER_BUSY。将其视为等待后重试的信号。不要先检查构建状态再写入。构建器可能会在此期间启动，因此在遇到 BUILDER_BUSY 后重试才能确保安全。只读工具在构建期间仍可使用。

---

8. 防护措施与限制

• 路径仅限于应用目录。 文件工具只能在应用目录内操作；目录遍历和绝对路径会被拒绝（PATH_OUTSIDE_SANDBOX）。
• 文件工具无法访问 .agents/（PROTECTED_PATH）——其中存放由 Agent 管理的配置和密钥（.agents/.env）。不要尝试通过文件工具读取或编辑此目录。
• 速率限制按应用计算：读取约 120 次/分钟，更改约 60 次/分钟，命令约 30 次/分钟。如果遇到 RATE_LIMITED，请放慢速度。
• delete_file 不是专用工具——请通过 run_command rm 删除文件。

你可能会遇到的错误代码

NOT_AUTHORIZED（缺少权限范围或标志） · APP_NOT_FOUND（ID 错误或无访问权限） · PATH_OUTSIDE_SANDBOX · PROTECTED_PATH · NOT_FOUND · BINARY_FILE · EDIT_TEXT_NOT_FOUND · EDIT_TEXT_NOT_UNIQUE（使 old_text 具有唯一性，或使用 replace_all） · OVERWRITE_NOT_ALLOWED（传入 overwrite: true） · TIMEOUT · OUTPUT_TRUNCATED · BUILDER_BUSY · COMMIT_FLUSH_PENDING（待处理的自动提交尚未持久化；请稍后重试—— 例如调用 create_checkpoint 时） · RATE_LIMITED · BACKEND_ERROR。

这些消息旨在帮助 Agent 自行纠正——请阅读并据此调整。

---

9. 提示与技巧

• 先读后写。 快速执行一遍 list_directory + read_file（或 grep）成本很低，却能大幅提高编辑准确度。
• 对 edit_file 使用 dry_run，在提交更改前确认差异，尤其是进行多项编辑时。
• 修改现有文件时，优先使用 edit_file 而不是 write_file——精准编辑可以避免覆盖内容，并生成便于审阅的差异。
• 对于大型文件，使用 read_file 的 offset/limit 读取指定行范围，而不是将整个文件读入上下文。
• 遇到“看起来有问题”的情况时，先查看 /tmp/vite.log 的末尾，不要猜测——日志通常会指出确切的文件和行号。
• 让它完成提交。 最后一次编辑后暂停几秒，让自动提交完成，再断开连接或发布。
• 每次都为工作创建检查点。 完成一个工作单元时、停止前，以及进行一组有风险的编辑前，都调用 create_checkpoint（sandbox checkpoint）。它会先刷新待处理的更改。否则，你的编辑虽然已提交，却不会出现在版本历史中；在构建器中执行下一次 Restore 或 Revert 时，这些更改就会被丢弃（第 6 节）。
• 一次只运行一个 Agent。 此功能专为每个应用使用一个外部 Agent 而设计；不要针对同一个应用运行并行会话。

---

10. 通过 base44 sandbox CLI 使用本地 Agent

如果 Agent 在你的机器上运行，它可以通过 Base44 CLI 驱动同一个沙盒，而不是使用 MCP；身份验证也使用 Base44 CLI，而不是 OAuth。工具、行为和错误代码（第 8 节）都相同——只有调用方式和身份验证不同。

身份验证。 使用 Base44 CLI 登录（base44 login）——凭据与用于 base44 functions deploy 的相同。和不依赖项目的 base44 connectors 命令一样，沙盒子命令会依次从 --app-id、BASE44_APP_ID 和本地 .app.jsonc 中解析应用 ID；不需要 config.jsonc。

命令名称。 CLI 为每个沙盒工具提供了更短的命令名称：

MCP 工具	CLI 命令
list_directory	base44 sandbox ls
read_file	base44 sandbox read
write_file	base44 sandbox write
edit_file	base44 sandbox edit
run_command	base44 sandbox run
grep	base44 sandbox grep
create_checkpoint	base44 sandbox checkpoint

npx base44 sandbox read --app-id <APP_ID> src/App.jsx

base44 sandbox checkpoint 可选接受 --name（消息/标题），并保存一个还原点。 完成一个工作单元时以及停止前都要运行它——CLI 写入的内容会提交，但不会创建检查点；在构建器中执行 Restore 或 Revert 时，最后一个检查点之后的所有内容都会被丢弃（第 6 节）：

npx base44 sandbox checkpoint --app-id <APP_ID> --name "before refactor"

向 Agent 提供特定应用的完整参考文档（说明，无需身份验证即可获取）：

https://app.base44.com/api/sandbox/<APP_ID>/local-agent/readme.md

（云端/MCP 对应的地址是 .../api/sandbox/<APP_ID>/claude-web/readme.md。）

此技能中的其他所有内容——编辑→预览→验证循环（第 5 节）、持久性（第 6 节）、并发（第 7 节）和防护措施（第 8 节）——都同样适用；只有调用方式和身份验证不同。

---

11. 连接器（OAuth 集成）

除了沙盒文件／Shell 工具，Base44 MCP 服务还提供两个工具，用于管理应用中的第三方 OAuth 连接器（Google Calendar、Gmail、Slack 等）。它们不会操作沙盒文件系统，而是直接操作应用的连接器状态。两者都需要 appId。

工具	范围	用途
list_connectors	apps:read	列出应用的连接器。不传入 integrationTypes 时，返回完整目录（名称、描述、是否已连接，以及已连接时的状态和已授予的范围）。传入 integrationTypes 可查看特定连接器的详细信息。
initiate_connector_connection	apps:write	连接（或重新设置范围）连接器。输入：appId、integrationType、scopes，以及可选的 connectionConfig。

请注意以下两点：

• 声明式范围（替换，而非合并）。 initiate_connector_connection 会将连接器设置为与你传入的 scopes 完全一致。未传入的范围会被移除，用户需要重新授权。务必先调用 list_connectors，然后传入完整的目标范围集合（要保留的现有范围加上任何新范围）。
• OAuth 需要人工操作。 工具会返回 already_authorized: true（无需操作），或返回一个 redirect_url，用户必须在浏览器中打开该链接以登录并授权——你无法自行完成此操作。用户完成后，再次调用 list_connectors 以验证状态并读取已授予的范围（提供方授予的范围可能少于请求的范围）。

这些操作只需要 apps:read／apps:write，不需要 sandbox:write。通过 CLI 接口（第 10 节）执行时，对应的是不依赖项目的 base44 connectors 命令（list-available、initiate --integration-type <t> --scopes <s...> --app-id <id>、pull），它们会输出相同的授权 URL。